12 KiB
12 KiB
MDHelper TODO
0. 阅读导航精简
目标:左侧在文件目录和文档大纲之间切换;删除阅读进度和网页内大纲,使正文滚动不再触发标题定位或界面同步。
文档与版本:
- 将应用版本号更新为
0.2.0。 - 更新 README,说明当前渲染路径、现有能力和 0.2.0 主线目标。
- 更新设计文档,明确左侧目录/大纲切换和静态大纲方案。
- 在 TODO 中建立 0.2.0 任务清单。
实现任务:
- 梳理阅读模式和编辑模式中目录、进度、滚动位置保存的边界。
- 删除状态栏和网页内阅读进度条。
- 删除网页内大纲及其 CSS、JS 和编辑预览桥接。
- 删除滚动时的进度计算、当前标题定位和 WebChannel 上报。
- 将文件目录和当前文档大纲合并为左侧两个切换页签。
- 大纲只在用户点击标题时执行跳转,不随滚动更新选中项。
- 保留低频滚动坐标保存,用于恢复阅读位置。
- 补充单元测试和 GUI smoke,覆盖左侧切换和无页面导航装饰的 HTML。
风险与注意事项:
- 编辑模式保留源码目录和标题定位能力。
- 大纲只在打开、切换或编辑内容变化时重建,不参与正文滚动。
- WebEngine 滚动流畅度仍受 Mermaid、公式、大图片和超长代码块影响,保留现有异步解码和重型块优化。
1. Markdown 编辑功能
- 增加基础编辑模式:打开当前
.md/.markdown源文件,使用QPlainTextEdit编辑。 - 支持快捷键:
Ctrl+E进入编辑,Ctrl+S保存。 - 保存后刷新当前阅读页、右侧目录、左侧文档树和全文搜索索引。
- 避免保存触发
QFileSystemWatcher后重复刷新或状态抖动。
风险与注意事项:
- 内置保存和外部编辑器保存都会触发文件监听:使用
internal_save_paths区分本软件保存和外部变更。 - 当前多标签页可以打开同一个文件:保存和自动刷新会同步刷新已打开的同一文档标签、目录、文档树和搜索索引。
- 编辑时关闭窗口或切换文件要防止未保存内容丢失:编辑标签关闭前调用
confirm_close(),未保存时要求用户确认。 - 非 UTF-8 编码文件可能读取失败:编辑和阅读渲染路径均捕获
UnicodeDecodeError并显示友好提示。
2. 分屏编辑与预览
- 增加“源码 / 预览 / 分屏”视图模式。
- 编辑时使用防抖刷新预览,避免每次按键都完整渲染。
- 分屏模式下保持预览滚动位置尽量稳定。
风险与注意事项:
- WebEngine 渲染较重,实时预览需要节流:预览刷新使用 350ms 单次
QTimer防抖。 - 标题 slug、Mermaid、公式和媒体资源依赖完整渲染:预览和阅读页保持完整渲染流程,不做不可靠的局部刷新。
- 分屏会改变主界面布局:编辑器已嵌入标签页,并同步主题、目录栏和多标签状态。
3. 编辑体验增强
- 增加 Markdown 语法高亮。
- 增加行号、当前行高亮、查找/替换。
- 增加未保存标记,并在关闭标签页/窗口时询问保存。
- 支持自动保存或恢复草稿。
风险与注意事项:
- 自动保存可能覆盖用户不想保存的临时改动:自动保存只写入草稿,不直接覆盖正式文件,恢复前需要用户确认。
- 查找/替换要区分“源码编辑器内查找”和“阅读页页内查找”:源码编辑器和阅读页使用独立查找控件和状态。
- 行号和大文件语法高亮可能影响性能:行号只绘制可见块,超大源码自动关闭 Markdown 语法高亮。
4. 文件打开与链接策略继续完善
- 本地非预览文件支持记住用户选择的打开程序,例如
.mp4 -> VLC.exe。 - 同类文件下次自动使用记住的程序打开。
- 提供管理已记住程序的入口。
风险与注意事项:
- 记住的程序路径可能被移动或卸载:打开前校验路径,缺失或启动失败时自动清除记录并提示。
- 不应强行在标签页内展示所有媒体:非预览文件沿用询问/默认程序/用户指定程序策略,视频提供内置播放和外部打开两种入口。
5. GUI 自动化测试
- 覆盖本地链接在本标签页/新标签页打开的路由。
- 补充右键菜单动作信号测试。
- 覆盖本地文件打开策略的程序记忆、HTML 导出辅助路径。
- 补充真实 PDF 导出和外部程序选择动作测试。
- 覆盖书签恢复、滚动位置恢复、主题切换、编辑保存刷新。
风险与注意事项:
- Qt WebEngine 在无界面环境下偶发不稳定:保留
tests/gui_smoke.py离屏烟雾测试,并使用明确等待条件。 - 涉及系统默认程序的测试应避免真的启动外部播放器:GUI smoke 中替换外部启动函数,只验证路由和参数。
6. 发布与打包
- 功能稳定后再重新执行 PyInstaller 打包。
- 打包前确认 WebEngine、资源文件、媒体示例和日志路径正常。
- 打包后运行
dist/MDHelper.exe --check或等价检查。
风险与注意事项:
- WebEngine 资源和离线 Mermaid/KaTeX/MathJax 文件容易漏打包:
MDHelper.spec明确包含mdhelper/resources、示例文档和媒体资源,并保留 PyInstaller hook 路径。 - 单文件 exe 首次启动会解压,启动日志路径要能写入:日志目录优先使用用户可写目录,并提供临时目录兜底。
7. Markdown 编辑器继续完善
- 将编辑器类拆分到独立模块,降低主窗口复杂度。
- 将 Markdown 编辑器嵌入标签栏,默认以分屏模式打开。
- 点选“编辑当前 Markdown”时用编辑标签原位替换原阅读标签。
- 编辑器顶部不再单独显示文档路径,路径由标签标题表达。
- 编辑器控制栏合并“视图、查找源码、替换、大小写、全词”等控件。
- 保存前检测磁盘文件是否被外部修改,避免覆盖外部编辑。
- 增加“另存为”功能,并刷新文档树和搜索索引。
- 草稿记录补充保存时间、文件修改时间、文件大小等信息。
- 查找/替换增加命中数量、当前位置、区分大小写、全词匹配和
Ctrl+H。 - 分屏模式增加源码和预览的滚动同步。
- 增加插入工具栏:标题、加粗、斜体、代码块、表格、链接、图片、提示块、Mermaid、公式。
- 编辑器颜色跟随应用主题,深色主题下保持可读。
- 补充编辑器专项测试:外部修改冲突、另存为、查找替换、草稿元数据、插入模板。
- 补充编辑器标签页测试:默认分屏、标签内保存、保存后不关闭。
8. 目录跳转稳定性
- 点击目录标题时仅在阅读标签页执行跳转,避免编辑标签页误用旧阅读页。
- 锚点跳转改为多次重试,兼容 WebEngine 页面尚未完全就绪的情况。
- 跳转时更新页面 hash 并触发滚动状态上报,提升目录高亮一致性。
- 编辑标签页中目录栏展示当前源码标题,并支持点击定位到源码标题。
9. 启动与项目目录
- 默认启动不再自动打开内置示例文件夹和
sample.md。 - 首次无记录时提示用户选择文件夹或文件。
- 选择 Markdown 文件时自动把文件所在目录作为当前文件夹。
- 记录上次打开的文件夹,下次启动自动恢复该文件夹。
- 记录窗口大小和位置,下次启动按上次窗口几何恢复,不再启动后强制固定大小。
10. 欢迎页与文件树
- 标签栏没有文档时自动显示只读欢迎标签。
- 打开任意文档时自动关闭欢迎标签。
- 所有文档标签关闭后自动恢复欢迎标签。
- 打开文件夹后左侧文档栏按目录结构展示当前文件夹下的文件。
- 从“打开文件”选择文件时,自动把文件所在目录作为当前文件夹,并打开该文件内容。
- 左侧文件树点击 Markdown/网页文件在标签页打开,其他文件沿用本地程序打开策略。
- 默认仅展开当前文件夹根节点,子文件夹保持折叠,减少大目录下的视觉噪音。
- 为文件夹和文件设置相近但不同的文字颜色,文件按类型显示图标,接近 VSCode 的文件树识别体验。
- 文件树仅展示 Markdown 和网页文档,文件夹优先并按名称排序。
- 文件树右键支持切换 Markdown 显示为文档标题或文件名。
- 优化文件夹折叠/展开箭头,提高目录层级可见性。
11. 工具栏与分屏预览
- 编辑 Markdown 时,分屏预览按源码滚动比例跟随编辑区上下移动。
- 删除工具栏首页按钮,将后退、前进、打开、刷新改为图标按钮。
- 将工具栏 A-/A+ 改为文档字号下拉框,并增加文档字体下拉框。
- 编辑模式下调整文档字号时,同时调整预览窗口和源码编辑窗口字号。
- 编辑模式下在保存、另存为、取消前补充回退/前进按钮。
- 强化阅读/编辑模式目录连续点击跳转,避免首次正常后后续失效。
- 主工具栏移除页内查找框,将搜索/上一个/下一个移动到文档列表栏搜索框上方。
- 文档列表栏搜索框高度压缩为约当前字体 1.5 倍,并修复深色主题下字体/字号标签颜色。
12. 主题背景
- 默认主题颜色改为彩色。
- 删除旧主题背景选项,新增无、中国结、祥云、如意、毛笔、牡丹、竹、回纹。
- 为新增主题背景提供离线 SVG 纹样资源,并兼容旧配置中的背景值。
- 限制主题背景仅在主题颜色为彩色时可选,其他颜色自动使用“无”。
- 修改主题背景时同步刷新窗口图标和 MDHelper 标题栏颜色。
风险与注意事项:
- 冲突检测要避免误判,也要避免静默覆盖外部工具已经保存的内容:保存前比较文件签名,检测到外部变更时要求用户确认。
- “另存为”后要同步文档树、最近文件、搜索索引、当前标签页标题和文件监听:另存为保存后统一走刷新与标签状态更新流程。
- 草稿不能直接覆盖正式文件,只能在用户确认后恢复:草稿恢复通过确认框选择,拒绝后清理草稿。
- 分屏同步滚动只能做近似同步,Mermaid、公式和图片会让源码高度与预览高度不一致:按滚动比例同步,并保留标题目录精确跳转。
- 插入工具栏要操作选区,不能破坏已有文本:插入模板通过当前选区替换,并保留无选区占位内容。
13. 可选代码文档展示
- 增加“展示文件类型”设置,支持 Markdown、Python、C/C++ 分组开关。
- 将文档发现逻辑改为按用户选择的扩展名过滤,默认只展示 Markdown/网页文档。
- Python、C/C++ 文件在阅读页中用 Pygments 高亮展示,不再只作为普通文本预览。
- Python 使用 AST 提取类、函数作为右侧目录;C/C++ 先用轻量正则提取函数/类/结构体。
- 搜索索引和自动刷新监听跟随当前展示文件类型更新。
- 补充单元测试和 GUI smoke,覆盖配置过滤、代码高亮、代码目录。
风险与注意事项:
- 大型源码目录容易让文件树和搜索索引变慢:代码文件展示默认关闭,并跳过超大代码文件,搜索索引只读取安全大小内的文本。
- 代码文件编码可能不是 UTF-8:统一使用
utf-8-sig、utf-8、gbk、latin-1回退读取。 - C/C++ 结构目录用正则只能做基础识别:按“基础结构目录”处理,避开明显声明和控制语句,不承诺完整语法解析。