feat(editor): add markdown presets, heading folding and external file refresh

2026-09-06 12:57:09 +08:00
parent 415efc4444
commit 8ad1db33f7
43 changed files with 901 additions and 54 deletions
@@ -0,0 +1,52 @@
+# 标题折叠与样式开发说明
+
+日期：2026-09-06。范围为工作区写作模式的章节折叠，以及正文标题外观偏好。
+
+## 1. 章节边界与交互
+
+H1–H6 标题旁在悬停时显示统一折叠箭头；键盘聚焦也显示，触摸设备保持可见。章节从标题之后开始，结束于同一容器内下一个同级或更高级标题；末尾没有后续内容的标题不显示按钮。引用等容器中的标题只影响所在容器，不折叠外部正文。
+
+- 工具栏提供“折叠所有章节”和“展开所有章节”。
+- 折叠父章节不会清空子章节的折叠状态。
+- 折叠时若选区在将隐藏的正文中，光标先移到标题。
+- 从大纲、查找或键盘跳到隐藏内容时，展开包含目标的章节，避免隐藏光标。
+- 折叠只影响当前编辑器视图，不修改 Markdown，不触发文档脏状态，也不占用撤销历史。重开文件恢复展开；源码模式与静态预览不进行章节折叠。
+
+实现位于 `headingFolding.ts`：插件状态保存标题位置，通过事务映射跟随文档编辑；删除或改成正文的标题会从状态中清理。Decoration 隐藏完整块，widget 提供可聚焦的折叠按钮。章节范围按标题栈计算，并按不可变文档缓存；隐藏范围合并后遍历节点，避免每个节点重复扫描全部标题。
+
+## 2. 标题样式设置
+
+入口为“设置 → 编辑器 → 标题样式”，主题页“编辑器外观”中也提供同一组件。
+
+- 默认跟随当前主题，不覆盖主题字号、字体与粗细。
+- 启用自定义后，分别调整 H1–H6 字号（12–72 px）和字重（400–800 的五个档位）。
+- 标题字体可跟随正文，或使用系统衬线、无衬线、等宽字体。
+- 面板即时预览，工作区正文和静态 Markdown 预览使用同一偏好。
+- 不影响笔记属性栏的标题、侧栏大纲字号或页面标题，不改写源文件中的标题级别。
+- “恢复跟随主题”清除自定义覆盖；主题页“恢复默认”也重置标题设置。
+
+偏好由 `headingAppearance` store 保存到本机 `editor-heading-appearance`。读取时校验字体枚举、字重与字号范围；应用 CSS 前再次规范化，避免空输入、无效存储或异常大数影响布局。刷新后恢复设置，切换主题保留自定义偏好。用户显式启用的覆盖只作用于 Markdown 标题，优先于主题规则；颜色继续跟随主题。
+
+## 3. 桌面命令预留
+
+既有 `editorCommandService` v1 增加三个可执行 ID：
+
+| 命令 | 行为 |
+| --- | --- |
+| editor.heading.toggle-fold | 切换选区所在章节的折叠状态 |
+| editor.heading.fold-all | 折叠所有有内容的章节 |
+| editor.heading.unfold-all | 展开所有章节 |
+
+均不需要参数，沿用活动文档、模式与冲突检查。原生快捷键仍由第三阶段容器绑定，此处不注册系统级快捷键。
+
+## 4. 验证
+
+```sh
+cd frontend
+npm run test -- src/features/editor/headingFolding.spec.ts src/features/editor/VisualMarkdownEditor.spec.ts src/features/editor/HeadingStyleSettings.spec.ts src/stores/headingAppearance.spec.ts
+npm run build
+```
+
+自动检查覆盖章节边界、嵌套容器、隐藏选区迁移、父子折叠状态、大纲目标展开、序列化保持、设置保存恢复、输入校验和面板恢复默认。
+
+手动检查：打开“功能演示 / 01 Markdown 与大纲”，依次折叠 H2 与 H1，再从大纲跳转；确认隐藏内容重新显示。打开设置调整 H1 字号与 H2 粗细，返回笔记检查外观，刷新后检查偏好仍在；关闭自定义后依次切换六个主题核对主题原有样式。