8dae91c2ca
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.
144 lines
5.0 KiB
Markdown
144 lines
5.0 KiB
Markdown
# MDHelper 常见问题
|
||
|
||
## 找不到文档大纲
|
||
|
||
大纲已经移到左侧导航栏:
|
||
|
||
1. 点击左侧的 `大纲` 页签。
|
||
2. 点击标题即可跳转。
|
||
3. 如果列表为空,请确认当前文档包含 Markdown 标题,必要时刷新当前文档。
|
||
|
||
大纲不会跟随正文滚动选中当前章节,这是为了避免持续定位和界面同步。
|
||
|
||
## 每行文字太少或太多
|
||
|
||
打开 `工具 - 设置 - 纸张宽度`:
|
||
|
||
- 默认 `A4(x1)`:适合普通阅读。
|
||
- `A4 × 1.25` / `A4 × 1.5`:适合宽屏。
|
||
- `A4 × 1.75` / `A4 × 2`:适合代码、宽表格和技术文档。
|
||
|
||
纸张宽度只改变正文最大宽度,不改变字号。
|
||
|
||
## 滚动不够流畅
|
||
|
||
可尝试:
|
||
|
||
- 将鼠标滚轮速度保持在 `1.0` 附近。
|
||
- 对超大代码文件,避免同时启用过多文件类型。
|
||
- Mermaid、公式、大图片和超长代码块很多的文档会更依赖 WebEngine 渲染性能。
|
||
|
||
## 文件夹很大时卡顿
|
||
|
||
建议:
|
||
|
||
- 默认只展示 Markdown / 网页文件。
|
||
- 只在需要时启用 Python、C/C++ 或 Fortran。
|
||
- 避免把构建目录、依赖目录、虚拟环境目录作为阅读根目录。
|
||
- 使用左侧搜索定位目标文件。
|
||
|
||
MDHelper 会跳过超大代码文件的全文索引和部分高亮处理,以减少卡顿。
|
||
|
||
## 文件被外部修改后没有刷新
|
||
|
||
检查 `工具 - 设置 - 自动刷新`:
|
||
|
||
- 推荐选择 `当前文档、资源和目录`。
|
||
- 推荐刷新延迟为 `标准(1 秒)`。
|
||
- 若关闭自动刷新,需要手动点击刷新按钮或按 `F5`。
|
||
|
||
MDHelper 读取文档时不会锁定文件,外部编辑器仍可保存。
|
||
|
||
## 图片或媒体打不开
|
||
|
||
检查:
|
||
|
||
- Markdown 中的相对路径是否正确。
|
||
- 文件是否仍在原位置。
|
||
- 文件名大小写是否一致。
|
||
- 视频格式是否被 Qt 内置播放器支持。
|
||
|
||
对不支持的媒体格式,可选择用系统默认程序打开,也可以记住指定播放器。
|
||
|
||
## DOCX 导出失败
|
||
|
||
检查:
|
||
|
||
- 是否安装 python-docx。
|
||
- 当前文档路径和输出目录是否可写。
|
||
- 文档中引用的图片路径是否存在。
|
||
|
||
正式安装版 MDHelper 已包含 Pandoc,无需用户安装或配置 PATH。如果提示“未找到程序内置的 Pandoc”,说明程序文件可能不完整,请重新获取完整版本。也可临时切换到 python-docx 或内置基础导出;复杂 Markdown 的 DOCX 版式通常 Pandoc 更稳定。
|
||
|
||
## PDF 导出失败
|
||
|
||
检查:
|
||
|
||
- 当前文档是否能正常阅读。
|
||
- 输出路径是否可写。
|
||
- 文件名是否包含系统不允许的字符。
|
||
- WebEngine 是否已完成页面加载。
|
||
|
||
可先导出 HTML,确认内容渲染正常,再导出 PDF。
|
||
|
||
## 导出的 Word 目录仍显示提示文字
|
||
|
||
Word 目录使用可更新的目录域。打开文件后,在目录提示文字处右键选择“更新域”,由 Word 按实际页面生成页码。PDF 的目录页码在导出时自动生成。
|
||
|
||
## 修改已经保存,想恢复旧内容
|
||
|
||
使用“文件 → 历史版本”,查看版本差异后恢复到编辑区。确认无误再保存;恢复操作本身可以撤销。本机每个文件路径保留最近 20 个保存前版本,重命名后的路径有独立记录。
|
||
|
||
## 分享文档后图片无法显示
|
||
|
||
粘贴或拖入的图片保存在文档旁的“文档名.assets”文件夹。移动或分享 Markdown 时,请将该文件夹一起带走,并保持相对位置不变。
|
||
|
||
## 代码文件不显示
|
||
|
||
打开 `工具 - 设置 - 展示文件类型`,勾选需要的类型:
|
||
|
||
- Python
|
||
- C / C++
|
||
- Fortran
|
||
|
||
设置后文件树、搜索索引和自动刷新监听会随之更新。
|
||
|
||
## 设置后没有变化
|
||
|
||
多数设置会立即刷新当前文档。若仍未变化:
|
||
|
||
1. 按 `F5` 刷新。
|
||
2. 切换标签页再切回。
|
||
3. 关闭旧 exe,重新启动最新版本。
|
||
|
||
## 打包版提示缺少 PySide6
|
||
|
||
说明 PyInstaller 打包时没有正确带上 PySide6 或 WebEngine 资源。请使用项目根目录下的 `MDHelper.spec` 打包:
|
||
|
||
```powershell
|
||
.\pack\_installer.cmd
|
||
```
|
||
|
||
打包后执行:
|
||
|
||
```powershell
|
||
.\dist\MDHelper\MDHelper.exe --check --project-root .
|
||
```
|
||
|
||
## 另存为失败或图片无法复制
|
||
|
||
另存为到其他目录会同时复制相对引用的图片。请确认源图片存在且目标目录可写。失败时编辑内容、原文档路径和草稿仍保留;只有全部保存成功才切换到新路径。
|
||
|
||
## 从 Excel 粘贴表格提示超限
|
||
|
||
图形表格上限为 1000 行(含表头)、100 列。超限时不导入任何单元格,以免静默截断。可拆分后粘贴,或直接编辑 Markdown 源码。
|
||
|
||
## MHTML 导出失败
|
||
|
||
离线归档需要先加载文档中的实际图片、公式及图表。请根据提示修复资源路径,或将未能封装的远程样式资源改为本地资源。取消和失败均保留原有输出文件。成功导出的归档可单独移动,不需要原图片目录。
|
||
|
||
## 如何定位日志
|
||
|
||
MDHelper 会把日志写到用户可写目录。若启动或打开文档异常,优先查看最近的运行日志,并把错误堆栈和打开的文件路径一起记录下来。
|
||
|