Files
MDHelper/MDHelper_design.md
T
2026-05-25 17:12:00 +08:00

209 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MDHelper 帮助文档阅读器设计方案
## 1. 项目目标
MDHelper 是一个用 Python 编写的本地帮助文档阅读器,文档主体由 Markdown 文件组成。项目默认读取根目录下的 `sample.md` 和 `docs/` 目录中的更多手册文件,并支持以下内容:
- 普通 Markdown 文本、标题、列表、引用、链接
- Markdown 表格
- 伪代码和代码块高亮
- 图片显示:PNG、JPG、JPEG、WEBP、BMP、GIF
- 音频播放:MP3、WAV、OGG
- 动画/视频播放:GIF、MP4、WEBM、MOV 等浏览器可播放格式
- 左侧文档目录、正文阅读区、搜索、历史导航
## 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。相比 `QTextBrowser`,它更适合做包含多媒体内容的帮助文档阅读器。
## 3. 软件框架和软件包清单
### 已在 `mdhelper_env` 中存在的核心包
| 软件包 | 当前环境版本 | 作用 |
|---|---:|---|
| Python | 3.13.13 | 运行环境 |
| PySide6 | 6.11.1 | GUI 框架,提供窗口、菜单、分栏、树形目录、WebEngine |
| PySide6-Addons | 6.11.1 | 包含 QtWebEngine、QtMultimedia 等附加模块 |
| PySide6-Essentials | 6.11.1 | Qt 基础控件和核心模块 |
| shiboken6 | 6.11.1 | PySide6 绑定依赖 |
| markdown-it-py | 4.2.0 | Markdown 解析器 |
| mdurl | 0.1.2 | Markdown 链接解析依赖 |
| Pygments | 2.20.0 | 代码块和伪代码高亮 |
| Pillow | 12.2.0 | 图片元信息读取、缩略图生成、格式检查 |
### 建议补充的可选包
| 软件包 | 是否必需 | 作用 |
|---|---|---|
| beautifulsoup4 | 可选 | 对生成后的 HTML 做二次处理,把音频/视频链接替换为播放器标签 |
| lxml | 可选 | 更快、更稳定的 HTML/XML 处理 |
| PyInstaller | 可选 | 打包为 Windows `.exe` |
| watchdog | 可选 | 监听 Markdown 文件变化,实现自动刷新 |
| rapidfuzz | 可选 | 模糊搜索文档标题和正文 |
| whoosh 或 sqlite FTS5 | 可选 | 建立全文搜索索引 |
| pymdown-extensions | 可选 | 如果改用 Python-Markdown,可增强代码块、任务列表、提示块等语法 |
最小可运行依赖建议:
```text
PySide6
markdown-it-py
Pygments
Pillow
```
如果需要更好的 HTML 后处理和打包:
```text
beautifulsoup4
lxml
PyInstaller
watchdog
rapidfuzz
```
## 4. 推荐项目结构
```text
MDHelper/
sample.md
docs/
README.md
user_manual.md
quick_start.md
...
media/
screenshot.png
animation.gif
demo.mp4
demo.mp3
mdhelper/
__init__.py
app.py # QApplication 入口
main_window.py # 主窗口、菜单、工具栏、分栏
document_tree.py # docs/sample.md 文件树
markdown_renderer.py # Markdown -> HTML
media.py # 媒体类型识别和路径处理
search.py # 标题/全文搜索
history.py # 前进后退和最近阅读
resources/
reader.css
reader.js
requirements.txt
README.md
```
## 5. 核心界面设计
主窗口建议分为三块:
```text
+-------------------------------------------------------+
| 工具栏:后退 前进 首页 搜索框 字号 主题 刷新 |
+----------------------+--------------------------------+
| 文档树 | QWebEngineView 阅读区 |
| - sample.md | |
| - docs/README.md | Markdown 转换后的 HTML |
| - docs/user_manual.md| 图片/音频/视频内嵌播放 |
+----------------------+--------------------------------+
| 状态栏:当前文件、链接地址、加载状态 |
+-------------------------------------------------------+
```
建议功能:
- 文档树:扫描 `sample.md` 和 `docs/**/*.md`。
- 阅读区:用 `QWebEngineView.setHtml(html, baseUrl)` 加载转换后的 HTML。
- 搜索框:先做文件名/标题搜索,后续扩展全文索引。
- 历史导航:记录打开过的 Markdown 文件和锚点。
- 主题切换:浅色/深色 CSS。
- 字号调节:通过注入 CSS 变量控制正文大小。
## 6. Markdown 到 HTML 的渲染流程
```text
打开 md 文件
-> 读取 UTF-8 文本
-> markdown-it-py 解析 Markdown
-> Pygments 处理 fenced code block
-> HTML 后处理:
图片扩展名 -> <img>
音频扩展名 -> <audio controls>
视频扩展名 -> <video controls>
GIF -> <img> 自动播放
-> 拼接 reader.css / reader.js
-> QWebEngineView.setHtml(html, baseUrl=项目根目录)
```
媒体类型判断建议:
| 类型 | 扩展名 | HTML 标签 |
|---|---|---|
| 图片 | `.png` `.jpg` `.jpeg` `.webp` `.bmp` `.svg` | `<img>` |
| GIF 动画 | `.gif` | `<img>` |
| 音频 | `.mp3` `.wav` `.ogg` `.m4a` | `<audio controls>` |
| 视频/动画 | `.mp4` `.webm` `.mov` `.avi` | `<video controls>` |
`sample.md` 当前使用了 Markdown 图片语法引用音频和视频,例如:
```markdown
![背景音乐](media/demo.mp3)
![演示视频](media/demo.mp4)
```
渲染器应识别扩展名:如果目标是音频或视频,就不要生成 `<img>`,而是替换为对应播放器。
## 7. 伪代码展示方案
伪代码建议继续使用 fenced code block:
````markdown
```pseudocode
BEGIN
SET sum = 0
FOR i = 1 TO 10 DO
sum = sum + i
END FOR
END
```
````
实现方式:
- 对 `pseudocode`、`pseudo`、`text` 使用 Pygments 的文本 lexer 或自定义 CSS。
- 给代码块加上 `language-pseudocode` class。
- CSS 中使用等宽字体、浅色背景、行距和边框,保证算法步骤清晰。
## 8. 链接和路径规则
建议约定:
- 文档链接使用相对路径:`[用户手册](docs/user_manual.md)`。
- 媒体资源放在 `media/` 或文档同级目录。
- 内部锚点使用标准 Markdown 锚点:`#2-表格示例`。
- 点击 `.md` 链接时由应用拦截,加载目标 Markdown。
- 点击外部 `http/https` 链接时调用系统浏览器打开。
## 9. 后续实现步骤
1. 建立 `mdhelper/` 包和 `requirements.txt`。
2. 实现主窗口:左侧 `QTreeView`,右侧 `QWebEngineView`。
3. 实现 Markdown 渲染器,先保证 `sample.md` 完整显示。
4. 实现媒体链接替换:图片、GIF、音频、视频。
5. 扫描 `docs/`,生成文档树。
6. 实现 Markdown 内链跳转和外部链接打开。
7. 增加搜索、主题、字号、最近阅读。
8. 用 PyInstaller 打包为独立桌面程序。