规避ProseMirror React渲染差异带来的BUG

在 React 项目中使用 ProseMirror（如通过 Tiptap、Remirror 或自定义封装）时，由于 ProseMirror 的命令式 DOM 更新机制 与 React 的声明式虚拟 DOM 渲染机制存在根本差异，若处理不当，极易引发以下问题：

• 编辑器内容闪烁或重置
• 光标跳转/丢失
• 内存泄漏（未正确销毁 EditorView）
• 状态不同步（React state 与 ProseMirror state 不一致）
• 自定义节点（NodeView）渲染异常

---

✅ 核心原则：让 ProseMirror 完全控制编辑区域的 DOM

这是避免渲染冲突的根本前提。React 不应尝试渲染或更新 ProseMirror 所管理的 DOM 子树。

---

🛠️ 具体实践策略

1. 正确挂载和卸载 EditorView

确保在 useEffect 中创建，在清理函数中销毁，防止多次初始化或内存泄漏。

import { useEffect, useRef } from 'react';
import { EditorState } from 'prosemirror-state';
import { EditorView } from 'prosemirror-view';
import { schema } from './schema';

export default function ProseMirrorEditor() {
  const editorRef = useRef<HTMLDivElement>(null);
  const viewRef = useRef<EditorView | null>(null);

  useEffect(() => {
    if (!editorRef.current) return;

    const state = EditorState.create({ schema });
    const view = new EditorView(editorRef.current, { state });
    viewRef.current = view;

    return () => {
      view.destroy(); // 👈 关键：释放事件监听、定时器等资源
      viewRef.current = null;
    };
  }, []);

  return <div ref={editorRef} />;
}

❗ 避免在每次 render 时重建 EditorView（如放在组件顶层或依赖频繁变化的 deps）。

---

2. 不要用 React 控制编辑器内容

❌ 错误做法：

// 危险！React 会尝试 reconciliation，与 ProseMirror 冲突
<div contentEditable={true} dangerouslySetInnerHTML={{ __html: htmlFromState }} />

✅ 正确做法：

// 仅提供一个"容器"，由 ProseMirror 接管其子 DOM
<div ref={editorRef} />

---

3. 避免将 ProseMirror State 同步到 React State（除非必要）

频繁将 state.doc 转为 JSON/HTML 并存入 useState，会导致不必要的 React 重渲染，甚至触发循环更新。

✅ 建议：

• 仅在需要时（如保存、预览）读取内容。
• 工具栏状态可通过 ProseMirror 插件 + useCallback 监听状态变化，而非全量同步文档。

示例：监听选区变化更新工具栏

const updateToolbar = useCallback(() => {
  const { state } = viewRef.current!;
  setIsBold(state.schema.marks.strong.isInSet(state.selection.$from.marks()));
}, []);

useEffect(() => {
  const view = viewRef.current!;
  view.dispatch = (tr) => {
    view.updateState(view.state.apply(tr));
    updateToolbar(); // 在 dispatch 后同步 UI
  };
}, [updateToolbar]);

---

4. 自定义 NodeView：谨慎集成 React 组件

若需在 ProseMirror 节点中渲染 React 组件（如嵌入图表、评论），必须：

• 使用 createRoot().render()（React 18+）或 ReactDOM.render 挂载
• 在 destroy() 中正确卸载
• 避免在 React 组件内部修改 ProseMirror 状态（除非通过 dispatch）

class ReactComponentNodeView {
  dom: HTMLElement;
  contentDOM?: HTMLElement;

  constructor(node: Node, view: EditorView, getPos: () => number | false) {
    this.dom = document.createElement('div');
    
    const reactElement = <MyCustomWidget node={node} onUpdate={(attrs) => {
      const pos = getPos();
      if (pos !== false) {
        const tr = view.state.tr.setNodeMarkup(pos, undefined, attrs);
        view.dispatch(tr);
      }
    }} />;
    
    createRoot(this.dom).render(reactElement);
  }

  destroy() {
    unmountComponentAtNode(this.dom); // 或 root.unmount()
  }
}

⚠️ 注意：getPos() 可能返回 false（节点已删除），务必判空。

---

5. 避免 SSR / Hydration 冲突

ProseMirror 依赖浏览器 DOM API，不能在服务端渲染。

✅ 解决方案：

• 使用动态导入（next/dynamic 或 React.lazy）禁用 SSR
• 或在客户端 useEffect 中延迟初始化

Next.js 示例：

import dynamic from 'next/dynamic';

const ProseMirrorEditor = dynamic(
  () => import('../components/ProseMirrorEditor'),
  { ssr: false }
);

---

6. 不要手动操作编辑器 DOM

例如：

// ❌ 危险：直接修改 ProseMirror 管理的 DOM
document.querySelector('.ProseMirror').innerHTML = '...';

这会破坏 ProseMirror 的内部状态与 DOM 的一致性，导致崩溃或不可预测行为。

所有内容变更应通过 dispatch Transaction 完成。

---

7. 使用成熟封装库（推荐）

如非必要，建议使用经过验证的封装：

• Tiptap（最流行，React 友好）
• Remirror
• @nytimes/react-prosemirror

它们已处理大部分桥接细节，提供 useEditor、EditorContent 等 React-friendly API。

示例（Tiptap）：

const editor = useEditor({ ... });

return (
  <>
    <MenuBar editor={editor} />
    <EditorContent editor={editor} /> {/* 内部正确挂载 ProseMirror */}
  </>
);

但仍需理解其底层机制，以便调试。

---

🔍 常见 BUG 排查清单

现象	可能原因	解决方案
内容闪烁/重置	多次创建 EditorView	确保 useEffect 依赖项稳定，只初始化一次
光标跳到开头	React 强制更新容器 DOM	确保容器 div 无 children，不被 React 控制
自定义组件不更新	React 组件未响应 ProseMirror 状态	通过 props 传递最新 node 数据，或使用 context
内存泄漏	未调用 view.destroy()	在 useEffect 清理函数中销毁
Hydration failed	SSR 渲染了编辑器	禁用 SSR

---

总结：关键守则

1. 编辑区域 DOM 归 ProseMirror，其他归 React
2. 状态以 ProseMirror 为主，React 为辅
3. 所有内容变更走 Transaction，绝不直接改 DOM
4. 生命周期严格管理：init in effect, destroy on unmount
5. 复杂节点用 NodeView + React Portal，注意卸载

遵循这些原则，可极大降低因渲染机制差异导致的 bug。

如你有具体场景（如"如何实现带 React 表单的嵌入节点"或"协作编辑中的状态同步"），我可以提供针对性代码示例。