225 lines
9.2 KiB
Markdown
225 lines
9.2 KiB
Markdown
# MDHelper 帮助文档阅读器设计方案
|
|
|
|
当前版本:`0.2.0`
|
|
|
|
## 1. 项目目标
|
|
|
|
MDHelper 是一个用 Python 编写的本地文档阅读器。它以 Markdown 为核心,同时支持 HTML、Python、C/C++ 等本地文档或源码文件的可视化展示。项目重点是离线可用、对本地项目友好、支持多标签阅读、全文搜索、自动刷新、样式管理和导出。
|
|
|
|
0.2.0 阶段的核心目标是:在保持现有桌面应用能力的基础上,进一步提升阅读模式的滚动流畅度,让普通文档浏览更接近浏览器打开网页的体验。
|
|
|
|
## 2. 当前技术路线
|
|
|
|
```text
|
|
Python 3.13
|
|
-> PySide6 / Qt Widgets
|
|
-> QWebEngineView 渲染 HTML
|
|
-> markdown-it-py 解析 Markdown
|
|
-> Pygments 生成代码高亮 HTML
|
|
-> 本地 CSS/JS 管理表格、代码块、媒体控件、图片预览、滚动进度
|
|
```
|
|
|
|
选择 `QWebEngineView` 的原因是它内置 Chromium 渲染能力,可以自然展示 HTML5 `<audio>`、`<video>`、GIF、图片、表格、复杂 CSS、Mermaid 图表和数学公式。相比纯 Qt 文本控件,它更适合做包含多媒体内容的帮助文档阅读器。
|
|
|
|
## 3. 软件包清单
|
|
|
|
| 软件包 | 当前环境版本 | 作用 |
|
|
|---|---:|---|
|
|
| Python | 3.13.13 | 运行环境 |
|
|
| PySide6 | 6.11.1 | GUI、Qt Widgets、WebEngine、Multimedia |
|
|
| markdown-it-py | 4.2.0 | Markdown 解析器 |
|
|
| Pygments | 2.20.0 | 代码块和代码文件高亮 |
|
|
| Pillow | 12.2.0 | 图片相关处理 |
|
|
| python-docx | 1.2.0 | DOCX 导出备选实现 |
|
|
| PyInstaller | 6.20.0 | Windows 单文件 exe 打包 |
|
|
|
|
外部可选工具:
|
|
|
|
| 工具 | 作用 |
|
|
|---|---|
|
|
| pandoc | DOCX 导出备选引擎,适合复杂 Markdown 文档 |
|
|
| 系统默认浏览器 | 打开外部 HTTP/HTTPS 链接 |
|
|
| 系统文件关联 | 打开不在 MDHelper 内预览的本地文件 |
|
|
|
|
## 4. 当前项目结构
|
|
|
|
```text
|
|
MDHelper/
|
|
sample.md
|
|
docs/
|
|
media/
|
|
hooks/
|
|
hook-PySide6.QtQml.py
|
|
mdhelper/
|
|
__init__.py
|
|
app.py # QApplication 入口、启动参数、运行目录
|
|
main_window.py # 主窗口、菜单、多标签、文件树、导出、自动刷新
|
|
document_tree.py # 文件发现、类型分组、标题读取
|
|
markdown_renderer.py # Markdown / 代码 -> HTML
|
|
markdown_editor.py # Markdown 编辑器、分屏预览、草稿恢复
|
|
style_dialog.py # 文档样式管理和图形化编辑
|
|
settings_dialog.py # 应用设置
|
|
code_structure.py # Python / C/C++ 目录提取
|
|
docx_exporter.py # DOCX 导出
|
|
text_io.py # 文本编码回退读取
|
|
resources/
|
|
reader.css
|
|
reader.js
|
|
vendor/
|
|
tests/
|
|
test_app.py
|
|
test_renderer.py
|
|
gui_smoke.py
|
|
requirements.txt
|
|
README.md
|
|
todo.md
|
|
MDHelper.spec
|
|
```
|
|
|
|
## 5. 当前界面结构
|
|
|
|
```text
|
|
+---------------------------------------------------------------+
|
|
| 菜单栏:文件 编辑 书签 工具 主题 样式 关于 |
|
|
+----------------------+--------------------------+-------------+
|
|
| 文档栏 | 多标签阅读区 | 当前文档目录 |
|
|
| - 打开/刷新/查找按钮 | QWebEngineView / 编辑器 | QTreeWidget |
|
|
| - 搜索框 | Markdown 转换后的 HTML | 当前标题高亮 |
|
|
| - 搜索结果 | 图片/音频/视频/代码/公式 | |
|
|
| - 文件树 | | |
|
|
+----------------------+--------------------------+-------------+
|
|
| 状态栏:当前路径、链接目标、阅读进度 QProgressBar |
|
|
+---------------------------------------------------------------+
|
|
```
|
|
|
|
当前阅读模式中,正文在 `QWebEngineView` 内滚动;阅读进度条和右侧文档目录仍是 Qt 控件。滚动时页面通过 WebChannel 把进度和当前标题回传给 Python,再由 Python 更新 Qt 状态栏和目录树。
|
|
|
|
## 6. 当前渲染流程
|
|
|
|
```text
|
|
打开 md 文件或代码文件
|
|
-> 判断文件类型和编码
|
|
-> MarkdownRenderer 渲染为完整 HTML 字符串
|
|
Markdown: markdown-it-py + 自定义规则
|
|
代码文件: Pygments 高亮 + 行号锚点
|
|
公式: KaTeX / MathJax
|
|
图表: Mermaid
|
|
媒体: 图片 / 音频 / 视频标签
|
|
-> 拼接 reader.css / reader.js
|
|
-> QWebEngineView.setHtml(html, baseUrl=文件所在目录)
|
|
-> loadFinished 后恢复锚点、查找命中或历史滚动位置
|
|
```
|
|
|
|
文件变化、主题变化、文档样式变化、手动刷新时,会重新读取源文件并重新生成 HTML。正常滚动浏览时不会重新转译,也不会重新 `setHtml`。
|
|
|
|
## 7. 自动刷新设计
|
|
|
|
自动刷新目标是外部工具修改文档后,已打开的标签页能更新,同时避免本软件读取文件导致其他程序无法修改。
|
|
|
|
当前策略:
|
|
|
|
- 使用 `QFileSystemWatcher` 监听当前项目、已打开文档和引用资源所在目录。
|
|
- 文件变化后先延迟合并,再读取文件签名确认真实变化。
|
|
- 对受影响的已打开文档标签重新渲染。
|
|
- 本软件保存文件时记录内部保存路径,避免重复刷新和闪屏。
|
|
- 刷新只读取文件,不长期占用文件句柄。
|
|
|
|
## 8. 编辑模式设计
|
|
|
|
编辑模式以标签页形式打开 Markdown 源文件,默认提供源码 / 预览 / 分屏视图。
|
|
|
|
关键原则:
|
|
|
|
- 源码编辑和阅读页是两个不同模式,不强制共享同一套滚动逻辑。
|
|
- 预览刷新使用防抖,避免每次按键都完整重建 HTML。
|
|
- 保存前检查磁盘文件签名,发现外部修改时提醒用户,避免静默覆盖。
|
|
- 草稿只写入配置中的恢复数据,不直接覆盖正式文件。
|
|
- 分屏滚动同步按比例近似同步,标题点击用于精确定位。
|
|
|
|
## 9. 0.2.0 阅读体验重构方案
|
|
|
|
### 9.1 背景
|
|
|
|
当前滚动不够跟手的主要原因不是 Markdown 转译,而是滚动过程中仍存在 WebChannel 回传和 Qt 控件更新:
|
|
|
|
```text
|
|
WebEngine 滚动
|
|
-> reader.js 计算滚动进度和当前标题
|
|
-> WebChannel 调用 Python
|
|
-> Python 更新 QProgressBar
|
|
-> Python 查找并更新 QTreeWidget 当前目录项
|
|
```
|
|
|
|
即使已经做了节流和缓存,这条链路仍然比浏览器内部 DOM 更新更重。
|
|
|
|
### 9.2 目标架构
|
|
|
|
0.2.0 目标是把“当前文档目录”和“阅读进度”作为阅读页 HTML 的一部分生成。
|
|
|
|
```text
|
|
Markdown / 代码源文件
|
|
-> 渲染正文 HTML
|
|
-> 同时生成 in-page TOC HTML
|
|
-> 同时生成 in-page progress HTML
|
|
-> QWebEngineView 显示完整阅读页面
|
|
-> reader.js 在页面内部处理滚动进度和目录高亮
|
|
-> Python 只接收低频保存滚动位置、打开链接、保存图片等必要事件
|
|
```
|
|
|
|
### 9.3 预期收益
|
|
|
|
- 滚动时不再频繁更新 Qt 右侧目录树。
|
|
- 阅读进度条由网页内部 CSS/JS 更新,减少 Python 主线程压力。
|
|
- 目录高亮、滚动进度和正文滚动在同一个浏览器上下文中完成,更接近浏览器手感。
|
|
- 导出的 HTML 可以复用类似结构,后续更容易做自包含 HTML 或离线分享。
|
|
|
|
### 9.4 分阶段实现
|
|
|
|
1. 在 `MarkdownRenderer` 中生成标题列表数据,避免主窗口重复提取。
|
|
2. 在 HTML 模板中增加阅读页外壳:正文区、页面内目录、页面内进度条。
|
|
3. 在 `reader.css` 中实现内嵌目录和进度条的浅色/深色主题样式。
|
|
4. 在 `reader.js` 内部完成目录点击跳转、滚动高亮和进度条更新。
|
|
5. 阅读模式关闭或弱化 Qt 右侧目录树和状态栏进度条。
|
|
6. WebChannel 滚动上报降为低频保存阅读位置,不参与每次视觉更新。
|
|
7. 编辑模式保留源码目录定位能力,预览内目录点击通过离散事件回传源码定位。
|
|
8. 增加设置项:是否显示网页内目录、是否保留外部目录栏。
|
|
9. 补充 GUI smoke:目录点击、滚动进度、主题切换、编辑模式定位。
|
|
|
|
### 9.5 风险与约束
|
|
|
|
- 网页内目录会占用阅读区宽度,需要在窄窗口下自动折叠或隐藏。
|
|
- 很长文档的大纲 DOM 可能较大,需要虚拟化或折叠策略作为后续优化。
|
|
- 编辑模式不能丢失源码定位能力,不能简单删除 Qt 目录栏。
|
|
- 外部目录栏和网页内目录同时存在时可能造成重复,需要明确默认策略。
|
|
- WebEngine 的滚动手感仍受页面复杂度影响,Mermaid、公式和大图片仍可能造成局部卡顿。
|
|
|
|
## 10. 导出设计
|
|
|
|
当前导出:
|
|
|
|
- PDF:通过 `QWebEnginePage.printToPdf()` 导出当前页面。
|
|
- HTML:保存当前渲染 HTML。
|
|
- MHTML:将当前 HTML 打包为 MHTML 文本。
|
|
- DOCX:提供 `pandoc` 和内置 `python-docx` 相关实现作为用户可选项。
|
|
|
|
0.2.0 后如果阅读页引入内嵌目录和进度条,需要区分“阅读用 HTML”和“导出用 HTML”:
|
|
|
|
- 导出 HTML 默认应保留正文、样式、代码高亮和媒体引用。
|
|
- 是否导出网页内目录应作为选项或使用导出专用模板。
|
|
- 阅读进度条通常不应出现在导出文档中。
|
|
|
|
## 11. 打包设计
|
|
|
|
PyInstaller 使用 `MDHelper.spec`。必须包含:
|
|
|
|
- `mdhelper/resources`,包括 reader CSS/JS、Mermaid、KaTeX、MathJax 资源。
|
|
- 示例文档、docs、media。
|
|
- PySide6 QtQml hook,避免 WebEngine/QML 相关依赖漏打包。
|
|
- 图标文件。
|
|
|
|
推荐打包命令:
|
|
|
|
```powershell
|
|
.\mdhelper_env\Scripts\python.exe -m PyInstaller .\MDHelper.spec --noconfirm --clean
|
|
.\dist\MDHelper.exe --check --project-root .
|
|
``` |