# 标题折叠与样式开发说明

日期：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 粗细，返回笔记检查外观，刷新后检查偏好仍在；关闭自定义后依次切换六个主题核对主题原有样式。