fix: protect editor content and harden document exports

Protect pending edits on window close, keep save-as paths and drafts consistent,
copy relative image resources, reject oversized table imports without truncation,
and preserve independent preview scrolling during refresh.

Archive rendered MHTML resources with portable references and embedded local
fonts. Preserve existing outputs on export cancellation or failure. Convert
editor match positions and filter directory results in linear passes.

Include the previously completed editor image/table/history improvements,
undoable replacement, export snapshots, shared page settings, and cancellable
PDF/Word export workflow. Update documentation and version to 0.3.1.

Validation: 142 pytest cases passed; GUI smoke, improvements integration, and
offline MHTML/scroll reliability smoke checks passed.
This commit is contained in:
2026-10-29 18:22:42 +08:00
parent fac5cbb011
commit 8dae91c2ca
26 changed files with 2722 additions and 385 deletions
+28 -2
View File
@@ -2,7 +2,7 @@
MDHelper 是一个本地 Markdown / 代码文档阅读器,适合阅读项目说明、技术手册、源码旁文档和离线帮助文件。它使用 PySide6 提供桌面窗口,用 Qt WebEngine 渲染 Markdown 转换后的 HTML 页面,并在本地完成全文搜索、样式管理、导出和自动刷新。
当前版本:`0.2.3`
当前版本:`0.3.1`
## 1. 适用场景
@@ -121,6 +121,24 @@ Markdown 支持:
- 自动保存草稿和恢复草稿。
- 保存前检测磁盘文件是否被外部程序修改,避免覆盖外部编辑。
“全部替换”支持一次撤销,并保留此前的编辑记录。替换文本中的反斜杠按普通字符处理,可直接填写 Windows 路径。
关闭软件时,会先记录所有编辑标签的最新草稿,再提供“保存 / 放弃 / 取消”。选择保存但写入失败时窗口保持打开;选择取消会保留草稿;选择放弃会清除相应草稿。即使尚未等到定时保存草稿,也会检查当前编辑内容。
另存为成功后,后续草稿归属于新文件。若保存失败,编辑器继续使用原路径。另存为到其他文件夹时,相对引用的 Markdown 图片和 HTML `img src` 图片会复制到新文档旁的资源文件夹并更新引用;原文件和原资源保留。引用式图片会转换为等价的行内图片,代码示例不改动。找不到图片或无法复制时会提示,并保留当前编辑内容和原路径。
保存采用完整写入后替换原文件的方式。每个文件路径保留最近 20 个保存前版本,位于 `%LOCALAPPDATA%\MDHelper\history`。从“文件 → 历史版本”或编辑器工具栏打开,可查看与当前内容的差异,再恢复到编辑区;恢复可撤销,只有再次保存才覆盖磁盘文件。历史版本属于本机,不随文档或配置导出。
图片可通过工具栏选择、从文件管理器拖入,或直接粘贴截图。程序自动复制到文档旁的“文档名.assets”文件夹,插入相对路径;相同图片复用资源。移动或分享文档时,请同时携带该资源文件夹。撤销图片插入不会删除已保存的图片资源。
点击“表格”可设置行列数、增删当前行列、调整列对齐,并通过“从 Excel 粘贴”转换复制的单元格。第一行为表头。光标位于普通 Markdown 表格中时编辑原表格;引用或列表中的嵌套表格仍请使用源码编辑。应用整个表格后可一次撤销。
图形表格最多支持 1000 行(含表头)、100 列。粘贴或编辑超限表格会明确提示,不截断内容;原表格保持不变。更大的表格请拆分,或通过源码编辑。
分屏的“同步滚动”按标题、段落和代码块对应位置双向同步,支持自动换行的源码与大图片。取消勾选后两侧独立滚动。同步只在编辑预览中按滚动事件运行,阅读窗口不增加持续扫描。
关闭同步滚动后,编辑引起的预览刷新也会保留预览原来的滚动位置。
编辑时左侧大纲可点击定位源码标题。预览刷新使用防抖机制,避免每次按键都重新渲染。
## 9. 样式管理
@@ -203,7 +221,15 @@ MDHelper 读取文档时不会独占文件,外部程序仍可修改文件。
- DOCX
- MHTML
PDF 导出前会显示设置窗口,可分别设置上、下、左、右页边距。导出文件固定使用白色纸张背景,自动移除阅读页大纲和进度条,并在正文前生成带真实页码的目录;正文从目录后的新页面开始。
MHTML 会等待图片、公式和 Mermaid 图表渲染完成,再将页面与样式、图片和本地字体封装到单文件中。导出时显示进度并支持取消;取消或失败不会覆盖已有输出。缺失图片、加载超时或无法封装的远程样式资源会提示失败,请先修复路径或改用本地资源。离线归档用于保存静态显示效果,音视频、外部链接及需要联网的交互内容不属于静态归档范围。
PDF 和 Word 共用导出页面设置:A4 / A3 / Letter、纵向或横向、四个方向页边距、目录开关及 1–6 级目录、页眉、页脚和页码。设置会自动记住。页眉或页脚启用时,对应页边距至少为 12 mm,避免遮挡正文。
PDF 使用白色纸张背景,按所选层级生成带真实页码的目录;启用目录时正文从新页面开始。Word 使用目录域,打开文件后如未自动生成目录,可右键目录提示文字并选择“更新域”;页码由 Word 的实际分页决定。
四种格式均导出当前编辑区内容,包括尚未保存的修改;导出不会代替保存源文件。导出开始后使用固定内容,切换标签不会改变正在导出的文档或图片路径。
导出前检查会提示缺失的本地图片/链接、远程图片依赖,以及当前 Word 导出方式对公式、多级列表、Mermaid、内嵌 HTML 和扩展 CSS 的限制。可返回编辑或继续导出核对。Word 和 PDF 的耗时生成阶段提供进度状态及取消;成功后才替换目标文件,失败或取消不会覆盖已有输出。
DOCX 导出可选择 `pandoc` 或 `python-docx` 相关实现。正式安装版已包含 Pandoc,无需用户另行下载或配置 PATH。导出的 HTML 与阅读页一样不包含阅读进度控件。