React怎么封装Slate.js富文本编辑器并开发自定义插件

一、Slate.js 的底层设计哲学与分层架构

许多传统富文本编辑器（如 CKEditor、TinyMCE 乃至 Quill）通常将 DOM 结构、数据管理与编辑指令紧密耦合，开发者定制样式或扩展业务逻辑时，往往需要穿透到原生 DOM 进行事件拦截。与这类框架不同，Slate.js 采用了彻底的数据驱动思想。它的文档本质上是一棵由纯 JavaScript 对象组成的抽象语法树（AST），所有的编辑动作（键盘输入、删除、粘贴、格式切换）最终都会被解构为一系列标准的不可变原子操作（Operations）。

整个 Slate 体系在 React 项目中可清晰地划分为三个层次：

• Slate Core（数据内核层）：提供 Editor、Transforms、Node、Path 等纯逻辑 API，完全不依赖浏览器环境和 DOM API，可以在 Node.js 等服务端无缝运行。
• slate-react（视图适配层）：充当数据模型与浏览器 contenteditable 之间的翻译官。它负责监听真实 DOM 事件、维护 React 选区与 Slate 内部 Range 的双向映射，并将 JSON 节点树渲染为 React 虚拟 DOM。
• 自定义插件增强层（Plugins）：通过函数式组合，对 editor 实例上的方法（如 insertText、isVoid、isInline）进行拦截与扩展，赋予编辑器针对特定业务语法的解析与响应能力。

二、在 React 中封装基础编辑器组件

要在项目中稳定复用 Slate，我们需要先封装一个基础的 RichTextEditor 组件。这一步的关键在于处理好编辑器实例的生命周期、初始状态的不可变性以及 React 上下文的挂载。

1. 依赖安装

Slate 的模块化设计将其拆分为多个包。在典型的 React 业务项目中，我们需要安装以下三个基础库：

npm install slate slate-react slate-history

其中 slate 为核心逻辑，slate-react 为 React 绑定，slate-history 提供了开箱即用的撤销/重做（Undo/Redo）历史记录支持。

2. 编辑器实例的创建原则

在组件内部实例化 editor 时，必须且只能使用 useMemo 并在依赖项中传入空数组 []。这是初学者极易踩坑的地方：如果将 createEditor() 直接放在函数组件体内，每次组件重新渲染都会创建一个新的编辑器对象，导致底层的 DOM 选区完全失联，出现输入一个字符就失去焦点的严重 Bug。

3. 基础组件封装示例代码

下面是一个功能完备的受控基础编辑器组件 RichTextEditor.jsx。它提供了工具栏、初始值渲染以及对外部 value 和 onChange 的标准化接入：

import React, { useMemo, useCallback } from 'react';
import { createEditor } from 'slate';
import { Slate, Editable, withReact } from 'slate-react';
import { withHistory } from 'slate-history';

// 初始默认数据节点树
const DEFAULT_INITIAL_VALUE = [
  {
    type: 'paragraph',
    children: [{ text: '欢迎使用 Slate.js 富文本编辑器，请在此处开始输入...' }],
  },
];

export function RichTextEditor({ value = DEFAULT_INITIAL_VALUE, onChange, placeholder = '请输入正文...' }) {
  // 1. 组合插件管道，创建稳定的 Editor 实例单例
  const editor = useMemo(() => withHistory(withReact(createEditor())), []);

  // 2. 自定义块级元素渲染器
  const renderElement = useCallback((props) => {
    const { attributes, children, element } = props;
    switch (element.type) {
      case 'heading-one':
        return <h1 {...attributes}>{children}</h1>;
      case 'heading-two':
        return <h2 {...attributes}>{children}</h2>;
      case 'block-quote':
        return <blockquote {...attributes}>{children}</blockquote>;
      case 'code-block':
        return (
          <pre {...attributes}>
            <code>{children}</code>
          </pre>
        );
      default:
        return <p {...attributes}>{children}</p>;
    }
  }, []);

  // 3. 自定义行内标记渲染器 (Leaf)
  const renderLeaf = useCallback((props) => {
    let { children } = props;
    const { attributes, leaf } = props;

    if (leaf.bold) {
      children = <strong>{children}</strong>;
    }
    if (leaf.italic) {
      children = <em>{children}</em>;
    }
    if (leaf.code) {
      children = <code>{children}</code>;
    }

    return <span {...attributes}>{children}</span>;
  }, []);

  return (
    <div className="slate-editor-container">
      {/* Slate 上下文负责管理 editor 实例与状态更新广播 */}
      <Slate editor={editor} value={value} onChange={onChange}>
        {/* 编辑区容器 */}
        <Editable
          renderElement={renderElement}
          renderLeaf={renderLeaf}
          placeholder={placeholder}
          spellCheck
          autoFocus
        />
      </Slate>
    </div>
  );
}

三、格式定制：区分 Element 块节点与 Leaf 行内标记

在扩展富文本功能之前，必须清晰区分 Slate 中的两类渲染单元：Element 与 Leaf。它们分别对应文档树中的不同层级，混淆两者会导致数据结构失真或命令应用失效。

编写通用格式工具方法

为了让外部工具栏（Toolbar）或快捷键能够优雅地控制选区格式，我们需要封装标准的操作函数：

import { Editor, Transforms, Element as SlateElement } from 'slate';

// 检查当前选区是否具有指定的 Mark (如加粗)
export const isMarkActive = (editor, format) => {
  const marks = Editor.marks(editor);
  return marks ? marks[format] === true : false;
};

// 切换 Mark 格式
export const toggleMark = (editor, format) => {
  const isActive = isMarkActive(editor, format);
  if (isActive) {
    Editor.removeMark(editor, format);
  } else {
    Editor.addMark(editor, format, true);
  }
};

// 检查当前所在 Block 的类型 (如 heading-one)
export const isBlockActive = (editor, format) => {
  const { selection } = editor;
  if (!selection) return false;

  const [match] = Array.from(
    Editor.nodes(editor, {
      at: Editor.unhangRange(editor, selection),
      match: n => !Editor.isEditor(n) && SlateElement.isElement(n) && n.type === format,
    })
  );
  return !!match;
};

// 切换 Block 类型
export const toggleBlock = (editor, format) => {
  const isActive = isBlockActive(editor, format);
  const newType = isActive ? 'paragraph' : format;

  Transforms.setNodes(
    editor,
    { type: newType },
    { match: n => SlateElement.isElement(n) && Editor.isBlock(editor, n) }
  );
};

四、开发自定义插件：以 Markdown 快捷语法为例

理解了基础封装后，接下来进入核心环节——如何为 Slate 编写自定义业务插件。

以常见的需求场景为例：当用户在段落开头输入 # 时，自动将当前行转换为一级标题；输入 > 时转换为引用块；输入 ``` 时转换为代码块。这种行为无需用户点击工具栏，极大提升了输入效率。

1. 插件实现的拦截策略

要实现这一功能，插件需要拦截用户输入空格的瞬间。我们在插件函数中重写 editor.insertText 方法：

1. 首先检查传入的 text 是否为触发字符（即空格 ' '）。
2. 如果当前选区折叠在文本中，提取光标所在段落起点到当前光标之间的全部字符。
3. 匹配特定的 Markdown 前缀字符（如 #、>、```）。
4. 若匹配成功，选定并删除该前缀文本，然后通过 Transforms.setNodes 将所在块级节点转换为对应的 block 类型。
5. 若未匹配，或者输入的不是触发字符，则无缝调用原有的 insertText(text) 保证正常文字输入。

2. 编写 withMarkdownShortcuts 完整插件

import { Editor, Transforms, Range, Point, Element as SlateElement } from 'slate';

// 定义快捷语法映射表
const SHORTCUTS = {
  '#': 'heading-one',
  '##': 'heading-two',
  '>': 'block-quote',
  '```': 'code-block',
};

export const withMarkdownShortcuts = (editor) => {
  // 1. 缓存被包装前的原始方法
  const { insertText } = editor;

  // 2. 重写 insertText
  editor.insertText = (text) => {
    const { selection } = editor;

    // 当输入为空格且当前有折叠光标时进入判断
    if (text === ' ' && selection && Range.isCollapsed(selection)) {
      const { anchor } = selection;
      // 获取当前块级元素的起始位置
      const block = Editor.above(editor, {
        match: (n) => SlateElement.isElement(n) && Editor.isBlock(editor, n),
      });
      const path = block ? block[1] : [];
      const start = Editor.start(editor, path);
      const range = { anchor, focus: start };
      const beforeText = Editor.string(editor, range);
      const type = SHORTCUTS[beforeText];

      if (type) {
        // 选中前缀标记文本（如 "#"）
        Transforms.select(editor, range);
        // 删除前缀文本
        Transforms.delete(editor);
        // 修改当前段落节点为对应的新类型
        Transforms.setNodes(
          editor,
          { type },
          { match: (n) => SlateElement.isElement(n) && Editor.isBlock(editor, n) }
        );
        return; // 命中快捷语法，直接返回，不再插入空格
      }
    }

    // 未命中规则时，必须调用原始方法，保证默认文字输入正常进行
    insertText(text);
  };

  // 返回增强后的 editor 实例
  return editor;
};

3. 插件的组合与装配

由于 Slate 插件是标准的函数式管道，我们可以非常自然地将多个插件串联起来。在组件初始化时：

// 链式复合插件：自定义插件直接包裹在最外层
const editor = useMemo(() => {
  return withMarkdownShortcuts(withHistory(withReact(createEditor())));
}, []);

调用顺序决定了拦截优先级：越位于外层的插件，其重写的方法越先被调用；外层插件在执行完自身逻辑后，决定是否调用 next（即上一层包装的方法），这正是经典且强大的洋葱模型。

五、进阶场景：Void 不可编辑元素与复杂插件设计

富文本编辑器中不仅有文字，还经常需要嵌入图片、视频、图表、卡片甚至附件。在 Slate 中，这类无法直接被键盘光标进入编辑、整体作为一个独立实体的节点被称为 Void 元素。

1. 为什么必须在插件中重写 isVoid？

浏览器的 contenteditable 默认会试图将光标放置在任何子 DOM 元素之间。如果直接在 renderElement 中渲染一个 <img> 标签而不声明 Void 属性，用户在按下回退键、方向键移动光标或进行选区拖选时，浏览器原生行为会破坏 Slate 的节点树，导致崩溃报错。

Slate 的内部逻辑会依据 editor.isVoid(element) 的返回值来做选区纠正。对于 Void 节点，Slate 会在节点后插入隐式的空文本，并将焦点限制在节点整体，避免光标进入其内部。

2. 编写 withImages 插件示例

export const withImages = (editor) => {
  const { isVoid } = editor;

  // 重写 isVoid 判断
  editor.isVoid = (element) => {
    return element.type === 'image' ? true : isVoid(element);
  };

  return editor;
};

3. 渲染 Void 元素时的关键规范

在编写 Void 元素的 React 渲染组件时，必须遵守以下两项规范：

• 必须挂载 contentEditable={false}：告诉浏览器该 DOM 节点内部不接受原生输入法光标。
• 必须在最底层渲染 {children}：虽然 Void 元素看似没有文本子节点，但 Slate 必须在虚拟 DOM 中挂载其自带的空 Text 占位符，否则选区无法正确计算坐标。

import { useSelected, useFocused } from 'slate-react';

export const ImageElement = ({ attributes, children, element }) => {
  const selected = useSelected();
  const focused = useFocused();

  return (
    <div {...attributes}>
      <div
        contentEditable={false}
        style={{
          boxShadow: selected && focused ? '0 0 0 2px #8A9478' : 'none',
          padding: '4px',
          display: 'inline-block',
        }}
      >
        <img src={element.url} alt={element.alt || ''} style={{ maxWidth: '100%' }} />
      </div>
      {/* 必须保留 children 占位 */}
      {children}
    </div>
  );
};

六、生产环境避坑指南与架构全景

在将 Slate.js 投入生产业务时，开发者通常会面临一些容易被忽视但影响深远的技术陷阱。以下是核心排查与防护清单：

1. 中文输入法（IME 合成事件）与快捷键冲突

在中文、日文等需要通过 IME 拼音输入法的场景下，用户在敲击按键时会产生 compositionstart、compositionupdate 和 compositionend。如果插件仅根据键盘字符监听便急于执行 AST 转换，很容易将用户正在打的拼音中间码误当作正文截断或转换，引发选区错乱。建议：复杂的结构性变换应在输入法完成上屏之后（即判定非合成中）才介入，或者优先绑定在显式的操作动作（如回车换行、空格）上。

2. attributes 展开与 DOM 引用失联

所有通过 renderElement 和 renderLeaf 返回的最外层 React DOM 节点，必须完整展开 {...props.attributes}。Slate-React 正是通过这些注入的 data-slate-node、data-slate-leaf 属性在底层建立真实 DOM 与内存 AST 的双向映射。如果遗漏了 attributes，选区同步和光标定位将彻底失效。

3. Selection 规范化与判空保护

富文本编辑器处于失焦状态、或者通过外部抽屉/弹窗点击操作按钮时，editor.selection 可能为 null。在编写任何插件或工具栏函数时，第一行代码必须对 selection 进行有效性校验，避免直接读取 anchor 导致抛出未捕获的空指针异常。