GuaReader for VS Code

GuaReader 是从同仓库 IntelliJ IDEA 插件移植而来的 VS Code 电子书阅读扩展。默认模式不会复制书籍正文，也不会修改当前源文件；可选的临时空白行模式会在阅读期间短暂修改编辑器缓冲区。

下载与安装

从 GitHub Release 下载 gua-reader-vscode-0.3.0.vsix，在 VS Code 扩展视图右上角选择 ... | Install from VSIX...。Windows、macOS 和 Linux 使用同一个安装包，要求 VS Code 1.96 或更高版本。

功能

• 导入 UTF-8、带 BOM 的 UTF-8、GB18030 编码 TXT，以及 EPUB 2/3。
• 按 EPUB OPF manifest/spine 的阅读顺序提取 XHTML 正文。
• 在底部 Terminal+ 面板中以 Gradle 构建输出的外观阅读。
• 可在编辑器区域打开第二个同步阅读视图。
• 支持两种代码行阅读布局：不修改文档的虚拟尾随注释，以及自动创建阅读空白行的临时模式。
• 光标行已有注释时，自动复用注释符号与空格，并对齐当前主题的 comment token 颜色、粗体、斜体和下划线；字体与字号继承编辑器。
• 上一页、下一页和关闭操作通过文字 CodeLens 显示，可直接单击，无需按 Ctrl。
• 面板、编辑器视图和代码行阅读共享同一页、同一进度和分页配置。
• Terminal+ 当前页码可直接编辑并按 Enter 跳转；Inline 状态栏页码可单击后输入目标页。
• 在 VS Code 全局状态中保存最近书库和阅读进度，跨工作区恢复；首次升级会自动迁移各工作区的旧进度。
• Panic 模式立即隐藏代码行文字，并把阅读视图替换为普通 Gradle 输出。
• 跟随 VS Code 主题，或配置字体、字号、颜色、粗体、斜体、每页行数及每行字符范围。
• EPUB ZIP 解析不使用运行时第三方依赖，并限制条目路径与解压大小。

使用

1. 点击底部面板中的 Terminal+，或从命令面板运行 GuaReader: Show Terminal+。
2. 点击 Open 并选择 .txt 或 .epub。
3. 使用 Prev / Next 翻页，或编辑底部当前页码并按 Enter 跳转；首次点击 Inline 选择模式，以后点击 Inline 会使用上次模式直接开启或关闭；点击旁边的 ▾ 可随时选择或切换模式；Editor 在编辑器区域打开同步视图。
4. 在设置中搜索 GuaReader 调整显示和分页。

首次点击 Inline 或点击旁边的 ▾ 会弹出模式菜单，无需进入设置：

• trailingDecoration（默认）：把正文显示成现有代码行末尾的虚拟注释，不修改文档。
• temporaryBlankLines：根据 Lines Per Page 在光标下方插入临时空白行，并在空白行上显示正文。关闭代码行阅读或进入 Panic 模式时会自动移除这些空白行。

正文通过 Decoration 对齐真实注释所在列；底部显示 上一页 / 书名与页数 / 下一页 / 关闭 文字 CodeLens。操作栏采用 VS Code 原生位置，不与正文列强制对齐。

选择会保存在扩展状态中，作为下次打开内联阅读的默认布局，不需要修改 VS Code 设置。

开启 Inline 时，如果光标行包含 // 说明、# note、* Javadoc 或 <!-- comment -->，虚拟正文会自动使用相同的注释格式和主题样式。切换颜色主题后会自动刷新；关闭 GuaReader: Follow Theme 时，以扩展中的自定义外观设置为准。

临时模式只在确认占位行仍为空时自动删除；如果在占位区域输入了内容，扩展会保留该区域并给出警告，避免误删代码。

启用自动保存时，临时空白行可能在 Inline 开启期间被暂时写入文件，这是保持阅读区域不消失所必需的；关闭 Inline 后扩展会删除这些行，自动保存会随后保存清理结果。若 VS Code 或扩展宿主异常退出，请在提交代码前检查 Git diff。

默认快捷键：

更改快捷键：Windows/Linux 按 Ctrl+K Ctrl+S，macOS 按 ⌘+K ⌘+S，搜索 GuaReader，点击动作左侧的铅笔图标后输入新组合键。完整的命令 ID 和 keybindings.json 示例见项目首页。

与 IDEA 版本的平台差异

VS Code 当前没有 IntelliJ Block Inlay 和可浮动 Tool Window 的对应公共 API，因此移植采用以下等价交互：

• 代码行阅读通过 Decoration 显示虚拟注释；默认附着到光标下方一组较短的连续代码行，可选模式则创建临时空白行。两种模式都使用可直接单击的文字 CodeLens 交互。
• IDEA 的 Float 在 VS Code 中对应 Editor，即在编辑器区域打开可拆分、可移动的 Webview 标签页。
• VS Code 稳定 API 不支持 IntelliJ Block Inlay；虚拟注释不会创建引用窗口、评论卡片或回复框。只有明确启用 temporaryBlankLines 时才会临时修改编辑器缓冲区。

开发与打包

要求 Node.js 20 或更高版本。

cd vscode-extension
npm install
npm test
npm run package

• npm test 编译并运行分页、TXT/GB18030、EPUB 和 ZIP 安全测试。
• npm run package 生成与当前版本一致的 .vsix 安装包。
• 调试时可在 VS Code 中打开本目录，按 F5 启动 Extension Development Host。

安装本地包：

code --install-extension .\gua-reader-vscode-0.3.0.vsix

阅读状态保存在 VS Code globalState 中，仅记录书籍路径、标题和页码，不保存正文。0.3.0 会在每个旧工作区首次打开时自动合并原 workspaceState 进度。