Outline 项目中的标题折叠功能缺陷分析与修复方案

在 Outline 文档编辑器中，标题折叠功能是提升用户体验的重要特性之一。然而，近期发现了一个影响多级标题折叠行为的缺陷，本文将深入分析该问题的技术背景、产生原因以及解决方案。

问题现象

当用户尝试折叠高级别标题（如 h2 或 h1）时，如果文档中已经存在被折叠的低级别标题（如 h3 或 h4），则高级别标题的折叠功能会失效。具体表现为：

1. 第一个 h3 标题被折叠后
2. 后续的 h2 标题无法正常折叠其包含的内容
3. 但同一 h2 下的 h3 和 h4 标题仍可正常折叠
4. 当展开第一个 h3 标题后，h2 标题的折叠功能又恢复正常

技术背景

Outline 编辑器基于 ProseMirror 构建，其标题折叠功能通过以下机制实现：

1. 每个标题节点存储一个 collapsed 属性
2. 编辑器维护一个折叠状态查询系统
3. 渲染时根据折叠状态决定是否显示子内容

根本原因分析

问题出在 findCollapsedNodes.ts 文件中的折叠节点查询逻辑。原实现使用单个变量 withinCollapsedHeading 来跟踪当前折叠级别，这种设计存在明显缺陷：

1. 当遇到一个折叠标题时，会记录其级别
2. 后续遇到同级或更高级标题时，会清除该标记
3. 但无法正确处理嵌套折叠场景，导致状态管理混乱

具体来说，当第一个 h3 被折叠后，系统会记录当前折叠级别为 3。当遇到 h2 标题时，由于 2 < 3，系统会错误地认为应该退出折叠状态，而实际上 h2 应该能够包含并控制其所有子标题的折叠状态。

解决方案

采用栈数据结构来管理折叠级别是更合理的方案。栈的特性完美匹配标题的嵌套关系：

1. 初始化一个空栈来跟踪折叠状态
2. 遇到折叠标题时，将其级别压入栈顶
3. 遇到同级或更高级标题时，弹出栈顶元素
4. 如果当前标题也是折叠状态，则将其压入栈
5. 非标题节点或深层次节点会被正确识别为应折叠内容

这种改进后的算法能够正确处理各种嵌套折叠场景：

1. 多个 h2 标题可以独立折叠
2. 每个 h2 下的 h3 标题可以单独折叠
3. 折叠高级别标题会自动包含所有子标题
4. 展开操作也能正确恢复文档结构

实现细节

核心算法改进如下：

const collapsedStack: number[] = [];
for (const block of blocks) {
  if (collapsedStack.length) {
    let top = collapsedStack[collapsedStack.length - 1];
    if (block.node.type.name === "heading" && block.node.attrs.level <= top) {
      collapsedStack.pop();
      if (block.node.attrs.collapsed) {
        collapsedStack.push(block.node.attrs.level);
      }
    }
    else {
      nodes.push(block);
    }
  }
  else {
    if (block.node.type.name === "heading" && block.node.attrs.collapsed) {
      collapsedStack.push(block.node.attrs.level);
    }
  }
}

总结

Outline 文档编辑器中的标题折叠功能通过这次改进，解决了多级标题嵌套折叠时的状态管理问题。采用栈结构替代单一状态变量的方案，不仅修复了现有缺陷，还为未来可能增加的更复杂文档结构处理打下了良好基础。这种改进体现了在富文本编辑器开发中，数据结构选择对功能实现的关键影响。