161 lines
6.3 KiB
Markdown
161 lines
6.3 KiB
Markdown
# MDHelper
|
||
|
||
当前版本:`0.2.0`
|
||
|
||
MDHelper 是一个本地 Markdown / 代码文档阅读器,使用 PySide6 构建桌面窗口,用 Qt WebEngine 展示由 Markdown 转换得到的 HTML 页面。它面向本地项目文档、技术手册、源码说明和离线帮助文件,重点是离线可用、多标签阅读、全文搜索、样式管理和导出。
|
||
|
||
## 当前能力
|
||
|
||
- 打开文件夹或单个文件,支持启动参数直接传入文件夹名或文件路径。
|
||
- 支持同时运行多个程序窗口,分别查看不同文件夹,互不影响。
|
||
- 浏览 Markdown、HTML/网页文件,并可在设置中选择展示 Python、C/C++ 等代码文件。
|
||
- Markdown 支持标题、表格、引用、任务列表、提示块、链接、图片、GIF、音频、视频、代码块、Mermaid 图表和数学公式。
|
||
- 数学公式支持 KaTeX 和 MathJax,可在菜单中切换。
|
||
- 代码块和代码文件使用 Pygments 高亮,代码块支持行号、复制、展开/收起。
|
||
- Python 文件可提取类/函数作为目录;C/C++ 文件可提取基础函数、类、结构体目录。
|
||
- 多标签页阅读,支持后退/前进、书签、最近文件和恢复滚动位置。
|
||
- 左侧文件树支持按用户选择的文件类型过滤,搜索支持标题、文件名和正文全文搜索。
|
||
- 当前页查找支持上一个/下一个命中并显示命中数量。
|
||
- 自动刷新当前文档、已打开文档和引用资源;外部修改后会重新读取并渲染。
|
||
- 可配置主题颜色、主题背景、正文字号倍率、鼠标滚轮速度、纸张宽度、自动刷新策略和非预览文件打开策略。
|
||
- 提供“样式”菜单,支持内置文档样式和自定义样式文件,样式可配置字体、缩进、行距、段前段后间距等。
|
||
- 导出支持 PDF、HTML、DOCX、MHTML;DOCX 可选择 `pandoc` 或 `python-docx` 相关实现。
|
||
- 图片点击放大,支持缩放、旋转、适应窗口、原始大小、保存图片和在文件夹中显示。
|
||
- 表格支持横向滚动和一键复制。
|
||
- 支持导入/导出配置 JSON,便于迁移主题、书签、最近文件、阅读位置、样式和外部程序映射。
|
||
- 提供文档检查命令,用于扫描缺失的本地链接和媒体资源。
|
||
- 运行日志保存到用户可写目录,打包 exe 后也能记录启动和运行状态。
|
||
|
||
## 当前渲染路径
|
||
|
||
阅读模式下,当前实现路径是:
|
||
|
||
```text
|
||
打开 .md / 代码文件
|
||
-> 读取源文件文本
|
||
-> MarkdownRenderer 转换为完整 HTML 字符串
|
||
-> 拼接 reader.css、reader.js、公式/图表资源引用
|
||
-> QWebEngineView.setHtml(html, baseUrl) 可视化
|
||
-> 文件变化、样式变化、主题变化或手动刷新时重新生成 HTML 并 setHtml
|
||
```
|
||
|
||
正常滚动浏览时不会重新转译 Markdown,也不会重新生成 HTML。滚动阶段主要由 Qt WebEngine 内部的 Chromium 渲染;当前仍会低频把滚动进度和当前章节通过 WebChannel 回传给 Python,用于更新状态栏进度和 Qt 目录树。
|
||
|
||
## 0.2.0 重点方向
|
||
|
||
`0.2.0` 的主线目标是提升阅读流畅度,让阅读模式更接近浏览器打开网页的手感。
|
||
|
||
计划将“当前文档大纲”和“阅读进度”从外部 Qt 控件逐步迁移进 HTML 阅读页:
|
||
|
||
```text
|
||
当前方案:
|
||
QWebEngineView 正文滚动
|
||
-> JS 计算滚动位置
|
||
-> WebChannel 回传 Python
|
||
-> Python 更新 QProgressBar 和 QTreeWidget
|
||
|
||
0.2.0 目标方案:
|
||
QWebEngineView 内部同时包含正文、大纲和进度条
|
||
-> JS 在网页内部更新目录高亮和进度条
|
||
-> Python 只接收低频滚动位置保存、链接打开、图片保存等必要事件
|
||
```
|
||
|
||
预期收益:
|
||
|
||
- 滚动时减少 Python / Qt 控件更新,降低 WebChannel 往返。
|
||
- 大纲高亮、阅读进度和正文滚动都由浏览器内部处理,交互更轻。
|
||
- 阅读模式和导出的 HTML 更接近同一套页面结构,便于调试和后续导出增强。
|
||
|
||
需要保留的边界:
|
||
|
||
- 左侧文件树、全文搜索、多标签、菜单、设置仍由 Qt 提供。
|
||
- 编辑模式保留源码定位能力;预览内大纲点击需要能回传到编辑器定位标题。
|
||
- 自动刷新仍以源文件为准,文件变化后重新 Markdown -> HTML。
|
||
- 对大文档可以评估“临时 HTML 文件 + load(file://)”作为可选路径,但它不是滚动流畅度的首要优化。
|
||
|
||
## 编辑模式注意事项
|
||
|
||
编辑模式和阅读模式会区别处理:
|
||
|
||
- 阅读模式优先追求浏览器式流畅滚动,大纲和进度条可内嵌到 HTML。
|
||
- 编辑模式保留源码编辑、源码目录、分屏预览和保存冲突检测。
|
||
- 编辑预览刷新需要防抖,避免每次输入都完整重建 HTML 和大纲。
|
||
- 预览中的大纲点击如果要定位源码,需要通过 WebChannel 发送离散事件,而不是持续同步滚动位置。
|
||
|
||
## 快捷键
|
||
|
||
| 快捷键 | 功能 |
|
||
|---|---|
|
||
| `Ctrl+O` | 打开文件夹或文件 |
|
||
| `Ctrl+P` | 导出当前文档为 PDF |
|
||
| `Ctrl+D` | 添加当前文档/章节为书签 |
|
||
| `Ctrl+F` | 查找当前页 |
|
||
| `Ctrl+Shift+F` | 全文搜索 |
|
||
| `Ctrl+E` | 编辑当前 Markdown |
|
||
| `Ctrl+S` | 编辑模式保存 |
|
||
| `F5` | 刷新当前文档 |
|
||
|
||
## 运行
|
||
|
||
在项目根目录执行:
|
||
|
||
```powershell
|
||
.\mdhelper_env\Scripts\python.exe -m mdhelper
|
||
```
|
||
|
||
启动时直接打开指定文件或文件夹:
|
||
|
||
```powershell
|
||
.\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md
|
||
.\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject
|
||
```
|
||
|
||
也可以执行:
|
||
|
||
```powershell
|
||
.\mdhelper_env\Scripts\python.exe .\run_mdhelper.py
|
||
```
|
||
|
||
检查文档中的本地链接和媒体文件:
|
||
|
||
```powershell
|
||
.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .
|
||
```
|
||
|
||
运行测试:
|
||
|
||
```powershell
|
||
.\mdhelper_env\Scripts\python.exe -m pytest
|
||
.\mdhelper_env\Scripts\python.exe .\tests\gui_smoke.py
|
||
```
|
||
|
||
打包为单文件 exe:
|
||
|
||
```powershell
|
||
.\mdhelper_env\Scripts\python.exe -m PyInstaller .\MDHelper.spec --noconfirm --clean
|
||
```
|
||
|
||
生成文件位于 `dist\MDHelper.exe`。打包后建议执行:
|
||
|
||
```powershell
|
||
.\dist\MDHelper.exe --check --project-root .
|
||
```
|
||
|
||
## 依赖
|
||
|
||
核心依赖已写入 `requirements.txt`:
|
||
|
||
```text
|
||
PySide6==6.11.1
|
||
markdown-it-py==4.2.0
|
||
Pygments==2.20.0
|
||
Pillow==12.2.0
|
||
python-docx==1.2.0
|
||
PyInstaller==6.20.0
|
||
```
|
||
|
||
外部可选工具:
|
||
|
||
- `pandoc`:用于增强 DOCX 导出。
|
||
- 系统默认浏览器 / 默认文件关联:用于打开外部链接和非预览文件。
|