Files
MDHelper/docs/architecture.md
T

9.1 KiB

MDHelper 架构

界面与启动

  • reader_widgets.py:阅读页面、浏览器视图、固定的阅读标签容器与桥接信号。
  • video_player.py:视频播放控件。
  • ui_theme.py 与 resources/ui_*.qss:配色、样式模板及 Windows 标题栏设置。
  • main_window.py:应用窗口、菜单事件以及功能之间的协调。

控件模块导入时不创建窗口或浏览器。欢迎页不启动 WebEngine;首次显示阅读器时使用固定的 ReaderTabHost,页面准备好后才切换内容。拆分模块时必须保留控件的父子关系、创建时机和显示顺序,不通过重新创建主窗口或重新挂载已显示浏览器来刷新内容。

文档、标签与资源

WorkspaceStore 按项目保存经过验证的标签状态。启动恢复在主窗口显示前准备当前文档,后台标签使用不含浏览器的 ReaderTabHost 占位,激活时加载;命令行指定文件优先于会话恢复。会话只保存界面状态,内容仍由草稿与文档保存流程管理。

  • DocumentSession 是编辑中文档路径、保存基准和磁盘签名的唯一来源;修改状态由当前文本与保存基准比较得出。Qt 标签属性只是界面适配数据。
  • DocumentStore 负责读取、文件签名和历史版本保存;DraftStore 负责草稿持久化。
  • DocumentCloseController 统一关闭标签、关闭项目和退出软件的保存 / 放弃 / 取消流程。TabController 只在确认成功后移除控件,保留阅读器复用逻辑。
  • document_resources.py 统一解析 Markdown 与 HTML 引用,提供 URL、源码位置及安全修改片段。文档检查、导出检查、文件监听和图片迁移共用该结果;代码和注释不作为资源引用。
  • 图片迁移先生成 ImageRelocation 计划,读取和验证全部资源,再复制文件并保存文档。保存成功后才更新文档会话。

导出边界

MainWindow 持有 ExportController,不再继承导出实现。控制器通过 ExportContext 获取明确的快照、渲染、页面读取、浏览器配置和状态通知接口;不会自行访问标签页或窗口的字体、样式等内部字段。

ExportSnapshot 同时保存文本与 RenderOptions,导出期间的标签或外观变化不改变当前任务。PDF 和 MHTML 各有独立任务对象,共用 ExportLifecycle 的进度窗口、截止计时和页面资源就绪检查。mhtml_archive.py 只处理归档数据,不创建 Qt 对象。

配置与迁移

style_catalog.py 定义稳定的语义标识、类型、名称、同类型继承及 Markdown 使用情况。格式声明仍以 style_sync.py 解析的核心 CSS 为准,名称与基准单独保存在 rules._metadata,通过原有配置和项目预设路径持久化。旧 list、code、table 作为兼容基准,细分对象未设置时继承它们。

从内置样式复制时,rules._preset 保留原默认值来源;绝对首行/悬挂缩进使用 indent_unit,缺省仍为旧版的字符单位。图形编辑器对比控件加载快照,只写回实际编辑的组,避免范围限制和显示精度改写未编辑的 CSS。

style_panel.py 仅在用户打开时创建,按文档版本缓存语法分析,隐藏时停止刷新;style_dialog.py 的实际阅读预览也只在切换到该页时创建。启动路径不创建这些浏览器,不重建主窗口。

docx_style.py 负责格式字段与 OOXML 属性的转换及属性顺序;docx_semantic.py 识别各引擎输出的语义、生成命名段落/字符/表格样式,并按属性保留继承。保留编号、公式、关系和书签;除用于防止 Word 反向切换的明确字符字形(加粗、斜体、删除线)外,不重复写入直接字体、字号、颜色和段落格式。组合字符采用命名样式。tests/word_styles_smoke.ps1 使用本机 Word 的独立隐藏实例,验证打开文件、样式修改传播及继承,关闭时不保存测试修改。

preferences.py 定义 ReaderPreferences 和 ApplicationConfiguration。本地设置与 JSON 导入共用字段、取值检查和旧版迁移规则;ConfigurationStore 负责持久化。页面设置保留旧版 PDF 页边距的读取方式。窗口几何状态和草稿仍由各自的界面、文档组件管理。内置文档样式集中在 style_presets.py。

编辑器边界

markdown_editor.py 组装编辑界面并连接文档会话。editor_widgets.py 负责源码控件、行号和语法高亮;EditorFindController 管理查找位置及可撤销替换;EditorPreviewController 管理预览刷新、滚动映射、桥接信号和计时器。预览控制器接收明确的控件与渲染回调,不读取主窗口或文档存储。关闭编辑器时同时停止预览刷新与滚动计时器。

项目目录与文件监听

ProjectCatalog 管理文档列表、目录签名和搜索索引。主窗口只负责把结果放到目录树中,仍在接收后台扫描结果时检查项目与代次,避免旧结果覆盖新项目。

FileWatchService 管理监听路径、变更签名和合并刷新计时器,通过 WatchContext 请求界面刷新。它不访问标签控件。内部保存完成后更新监听签名;切换或关闭项目会清理待处理事件和计时器。编辑中的内容仍由窗口的文档会话规则保护,不被磁盘刷新覆盖。

CSS 与离线归档

CSS 同步按三个步骤处理:_collect_cascade 决定生效的声明,_CoreRuleReader 转换可表达的字体和段落属性,analyze_css 汇总结果。无法映射的 CSS 继续保留原文,不改写级联规则或 Word 的支持范围。

明确无效的声明在级联选择前忽略;简写中任一无效组件使整条简写失效,有效但不支持的表达式仍遮盖前面的值。普通 p 同时映射引用段落及 rules._list_paragraph 上下文;各引擎通过临时段落标记区分宽松列表和紧凑列表。表格文字使用独立内容容器承载段间距,表格边框和单元格内边距保持原位置。

render_css 使用与图形写入相同的字体变量表达继承,并生成列表层级缩进及独立文字修饰的辅助规则。显式取消列表基准时会恢复该语义类型的默认格式,旧配置缺少元数据时仍保留兼容基准。

docx_inline.py 定义转换阶段的临时字符样式标记,记录 Markdown 从外到内的语义顺序。两个基础引擎直接记录解析栈;Pandoc 使用随包资源 word_inline_styles.lua 记录同一顺序。最终样式处理替换并删除临时标记,脚注仍保留原段落样式、编号和关系;导出文件不需要脚本或宏。

MHTML 的浏览器加载与归档转换分开。mhtml_archive.py 分别处理资源标识、CSS 依赖、HTML 引用和 MIME 编码;入口 portable_archive 只组织这些步骤,保留原有本地字体嵌入与缺失资源检查。

验证约定

每个重构阶段独立提交。运行单元测试,并按改动范围运行 gui_smoke.py、improvements_smoke.py 和 reliability_smoke.py。涉及浏览器生命周期的调整必须检查欢迎页、首次打开文件、标签切换以及预览滚动;涉及保存的调整必须检查保存失败、取消、另存为和后台标签。

startup_smoke.py 验证从启动到首次打开文件只有一次主窗口显示、没有隐藏或窗口句柄变化,阅读器保持固定父容器。设置 MDHELPER_SMOKE_NATIVE=1 可在真实 Windows 窗口后端执行。pdf_export_smoke.py 检查实际 PDF 输出。

文档检查

doc_check.py 使用统一资源分析器检查全项目本地引用和实际渲染锚点;调用者可传入编辑器快照、取消信号和进度回调。document_check_dialog.py 只在用户打开时启动后台扫描,通过主窗口的源码定位入口打开结果,不参与启动流程。

rename_references.py 分离重命名计划、差异确认和文件事务。资源编辑复用源区间分析器,保护代码块和引用标题;提交前验证原文件,备份到本地应用数据目录,失败后逆序回滚。主窗口仅同步标签、草稿和导航记录。

save_conflict.py 将逐段合并算法与保存冲突对话框封装在一起。编辑器保存流程传入原始、编辑和磁盘版本;确认后再次核对磁盘字节,再交给现有带历史版本的原子保存流程。取消或二次冲突均保留编辑区。

batch_documents.py 负责跨文件资源路径、章节锚点命名和成组输出事务。batch_export_dialog.py 持有不可变的文档/样式快照,在工作线程执行 Word 转换,在 Qt 主线程串行驱动已有 PDF 控制器。只有全队列完成后才发布输出;取消和失败可恢复原有目标。Word 合并采用显式章节标识,PDF 使用同一组标识。

project_presets.py 管理全局默认、每个项目的独立副本及显式保存的模板库。预设仅包含文档样式和页面参数,使用现有配置规范化器;不携带项目路径、书签、草稿。主窗口在构建界面前应用项目默认,导出控制器通过回调取得同一份页面设置,不引入启动后切换窗口或浏览器的操作。