Tiptap Pro版TableOfContents扩展在自定义滚动容器中的问题解析

问题背景

Tiptap Pro版本中的TableOfContents扩展在开发富文本编辑器时非常实用，它能够自动生成文档目录并跟踪用户在文档中的位置。然而，当开发者尝试在非window滚动容器中使用该扩展时，遇到了一个关键问题：onUpdate回调函数在滚动时不会被触发，导致无法获取正确的锚点状态信息。

问题现象

在标准配置下（使用window作为滚动容器），TableOfContents扩展能够正常工作，onUpdate回调会随着用户滚动文档而触发，提供最新的isScrolledOver和isActive状态。但当开发者指定了一个自定义的滚动容器（如一个设置了overflow-y: auto的div元素）时，发现：

1. onUpdate回调不再响应滚动事件
2. 即使通过某些方式触发了回调，返回的锚点状态信息也是基于视口(window)计算的，而不是基于自定义滚动容器

技术分析

根本原因

该问题的核心在于TableOfContents扩展的滚动事件监听机制。在默认情况下，扩展会监听window对象的滚动事件，但当指定了自定义滚动容器后：

1. 扩展没有正确绑定到新容器的滚动事件
2. 位置计算逻辑仍然默认使用window的视口坐标系统
3. 状态更新机制没有适应自定义容器的滚动特性

解决方案演进

根据项目维护者的反馈，解决方案经历了以下演进：

1. 初始方案：通过直接修改扩展实例的scrollParent选项

   const tableOfContentsExtension = editor.extensionManager.extensions.find(...);
   tableOfContentsExtension.options.scrollParent = scrollParent;
   

   这种方法不够可靠，因为扩展可能没有正确重新初始化事件监听

2. 推荐方案：在编辑器初始化时通过配置方式指定scrollParent

   TableOfContents.configure({
     scrollParent: () => scrollRef.current
   })
   

   这种方法更为可靠，因为它确保扩展从一开始就使用正确的滚动容器

3. 完整解决方案：结合编辑器依赖项更新

   const editor = useEditor({
     extensions: [...ExtensionsKit, TableOfContents.configure({
       scrollParent: () => editorScrollParent
     })],
     // 其他配置
   }, [editorScrollParent]);
   

   这种方法确保了当滚动容器引用变化时，编辑器会重新初始化

实现细节

正确的配置方式

要实现TableOfContents扩展在自定义滚动容器中的正常工作，需要注意以下几点：

1. 动态引用：使用函数形式返回滚动容器引用，确保总是获取最新的DOM元素
2. 依赖管理：将滚动容器引用添加到编辑器的依赖数组中，确保引用变化时重新初始化
3. CSS准备：确保滚动容器具有正确的CSS样式

   .scroll-container {
     overflow-y: auto;
     height: 100vh; /* 或其他适当的高度 */
     position: relative;
   }
   

完整示例代码

const MyEditorComponent = () => {
  const scrollRef = useRef(null);
  
  const editor = useEditor({
    extensions: [
      StarterKit,
      TableOfContents.configure({
        scrollParent: () => scrollRef.current,
        onUpdate: (data, isCreate) => {
          // 现在可以正确获取基于滚动容器的锚点状态
          console.log('Active headings:', data);
        }
      })
    ],
    content: '<h1>标题</h1><p>内容...</p>'
  }, [scrollRef.current]);

  return (
    <div ref={scrollRef} className="scroll-container">
      <EditorContent editor={editor} />
    </div>
  );
};

常见问题排查

如果按照上述方案实现后仍然遇到问题，可以检查以下几点：

1. 滚动容器引用：确保scrollRef.current确实指向了正确的DOM元素
2. CSS样式：验证滚动容器是否确实可以滚动（检查overflow和height属性）
3. 生命周期：确认编辑器初始化时滚动容器已经存在于DOM中
4. 扩展顺序：确保TableOfContents扩展在编辑器扩展列表中正确配置

最佳实践建议

1. 单一滚动容器：尽量保持文档只有一个主要的滚动容器
2. 性能考虑：对于长文档，考虑对onUpdate回调进行防抖处理
3. 响应式设计：在响应式布局中，注意处理滚动容器尺寸变化的情况
4. 错误边界：添加适当的错误处理，防止滚动容器未定义时出现异常

通过正确理解和应用这些解决方案，开发者可以充分利用Tiptap Pro版的TableOfContents扩展功能，即使在自定义滚动容器环境下也能获得良好的用户体验。