Files
MDHelper/MDHelper_design.md
T

216 lines
8.6 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 目录式程序打包;Inno Setup 制作安装 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 / 编辑器 |
| - 大纲:标题点击跳转 | Markdown 转换后的 HTML |
| | 图片/音频/视频/代码/公式 |
+----------------------+----------------------------------------+
| 状态栏:当前路径、链接目标 |
+---------------------------------------------------------------+
```
当前阅读模式中,正文在 `QWebEngineView` 内滚动。左侧 `QTabWidget` 在文件目录与当前文档大纲间切换;大纲仅在点击时跳转,不随滚动选中标题。状态栏不显示阅读进度。
程序在主窗口显示前,在固定阅读容器中创建 `QWebEngineView` 并等待空白页加载完成;这一阶段允许增加启动耗时,但不会让用户看到 Chromium 初始化造成的界面重绘。随后主窗口一次性显示轻量 Qt 欢迎页。首次打开文档时,标签页对象、容器和 WebEngine 父子关系均保持不变;文档加载完成后只切换容器内部页面。关闭全部阅读标签后会保留一个隐藏阅读容器,避免同一进程内再次承担 Chromium 冷启动成本。
## 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. 阅读导航与滚动性能
### 9.1 背景
为避免长文档滚动时的额外计算,阅读滚动不再驱动导航界面:
```text
WebEngine 滚动
-> Chromium 自行绘制正文
-> 固定低频定时器只读取 window.scrollY
-> 保存阅读位置
```
滚动过程中不计算百分比、不搜索当前标题、不更新大纲选中项,也不发送持续的 WebChannel 滚动事件。
### 9.2 目标架构
大纲保持在 Qt 左侧导航中,与文件目录共用一个位置:
```text
左侧导航
-> 目录页签:搜索、文件树
-> 大纲页签:当前文档标题层级
-> 用户点击标题
-> Python 执行一次锚点或源码跳转
```
### 9.3 预期收益
- 阅读区不被网页内大纲占用,正文宽度稳定。
- 滚动不触发标题定位、进度计算或 Qt 目录更新。
- 文件目录和文档大纲都在左侧,用户可明确切换。
- 阅读、编辑和代码文件仍保留按需标题跳转能力。
### 9.4 分阶段实现
1. 删除状态栏进度条和网页内进度条。
2. 删除网页内大纲及其 CSS、JS 与预览桥接。
3. 删除滚动时的进度计算、当前标题二分定位和 WebChannel 上报。
4. 将文件目录和当前文档大纲合并到左侧切换页签。
5. 保留固定低频滚动坐标保存,用于历史返回和重新打开恢复。
6. 补充单元测试和 GUI smoke,覆盖左侧切换、标题跳转和无导航装饰的 HTML。
### 9.5 风险与约束
- 大纲列表在文档打开或内容刷新时重建,不在滚动时重建。
- 编辑模式的大纲点击直接定位源码标题。
- 阅读位置保存仍是异步低频调用,不参与逐帧渲染。
- WebEngine 的滚动手感仍受页面复杂度影响,Mermaid、公式和大图片仍可能造成局部卡顿。
## 10. 导出设计
当前导出:
- PDF:通过 `QWebEnginePage.printToPdf()` 导出当前页面。
- HTML:保存当前渲染 HTML。
- MHTML:将当前 HTML 打包为 MHTML 文本。
- DOCX:提供 `pandoc` 和内置 `python-docx` 相关实现作为用户可选项。
阅读页本身不包含大纲或进度条,因此导出 HTML 无需额外剥离阅读导航控件。
## 11. 打包设计
PyInstaller 使用 `MDHelper.spec`。必须包含:
- `mdhelper/resources`,包括 reader CSS/JS、Mermaid、KaTeX、MathJax 资源。
- 示例文档、docs、media。
- PySide6 QtQml hook,避免 WebEngine/QML 相关依赖漏打包。
- 图标文件。
推荐打包命令:
```powershell
.\pack\_installer.cmd
.\dist\MDHelper\MDHelper.exe --check --project-root .
```