从 Slate 迁移到 Plate

学习如何从 Slate 迁移到 Plate。

Plate 是基于 Slate 构建的，所以从纯 Slate 实现迁移到 Plate 相对简单。本指南将帮助你将基于 Slate 的编辑器转换为 Plate。

1. 安装 Plate

First, install the necessary Plate packages. If you're new to Plate, you might want to start by reading the Introduction to get an overview of the library.

npm install @udecode/plate

2. 替换 Slate 导入

将你的 Slate 导入替换为 Plate 导入。Plate 重新导出了大多数 Slate 类型和函数：

// Before
import { createEditor } from 'slate';
import { Slate, Editable, withReact } from 'slate-react';
 
// After
import { createPlateEditor, Plate, PlateContent } from '@udecode/plate/react';

3. 创建 Plate 编辑器

将 createEditor, withHistory 和 withReact 替换为 createPlateEditor:

// Before
const editor = useMemo(() => withReact(withHistory(createEditor()))), []);
 
// After
const editor = createPlateEditor({
  value,
  plugins: [
    // Additional plugins here
  ],
});

有关编辑器配置的更多详细信息，请查看 Editor Configuration guide.

4. 替换 Slate 和 Editable 组件

将 Slate 和 Editable 组件替换为 Plate 的 Plate 组件：

// Before
<Slate editor={editor} value={value}>
  <Editable className="p-4" />
</Slate>
 
// After
<Plate editor={editor}>
  <PlateContent className="p-4" />
</Plate>

5. 转换自定义元素和叶子

对于自定义元素和叶子，创建 Plate 插件：

// Before
const renderElement = useCallback(({ attributes, children, element }) => {
  switch (element.type) {
    case 'paragraph':
      return <p {...attributes}>{children}</p>;
    // ... other cases
  }
}, []);
 
// After
import { withCn, type PlateElement } from '@udecode/plate/react';
 
const ParagraphElement = withRef<typeof PlateElement>(
  ({ children, className, ...props }, ref) => {
    return (
      <PlateElement
        asChild
        className={cn('py-1', className)}
        ref={ref}
        {...props}
      >
        <p>{children}</p>
      </PlateElement>
    );
  }
);
 
const ParagraphPlugin = createPlatePlugin({
  key: 'p',
  node: {
    isElement: true,
    type: 'paragraph',
    component: ParagraphElement,
  },
});

有关创建插件的更多详细信息，请查看 Plugin Configuration guide 和 Plugin Components guide.

6. 转换 Slate 插件为 Plate 插件

如果你有自定义的 Slate 插件，将它们转换为 Plate 插件：

// Before
const withMyPlugin = (editor) => {
  const { insertText } = editor;
  editor.insertText = (text) => {
    // Custom logic
    insertText(text);
  };
  return editor;
};
 
// After
const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
  extendEditor: ({ editor }) => {
    const { insertText } = editor;
    editor.insertText = (text) => {
      // Custom logic
      insertText(text);
    };
    return editor;
  },
});

有关使用插件上下文的工作原理，请查看 Plugin Context guide.

7. 更新事件处理程序

更新你的事件处理程序以使用 Plate 的插件系统：

// Before
const onKeyDown = (event) => {
  if (event.key === 'Tab') {
    // Handle tab
  }
};
 
// After
const TabPlugin = createPlatePlugin({
  key: 'tab',
  handlers: {
    onKeyDown: ({ editor, event }) => {
      if (event.key === 'Tab') {
        // Handle tab
      }
    },
  },
});

你也可以使用 Plate 强大的快捷键系统：

const TabPlugin = createPlatePlugin({
  key: 'tab',
  shortcuts: {
    indent: {
      handler: ({ editor }) => {
        // Handle tab
      },
      keys: ['Tab'],
    },
  },
});

有关使用快捷键的更多详细信息，请查看 Plugin Shortcuts guide.

8. 适应 Plate 的 API

熟悉 Plate 的 API 并使用其工具和钩子：

// Using Plate's transforms
editor.tf.toggle.mark({ key: 'bold' });
 
// Using Plate's debug API
editor.api.debug.log('Hello, Plate!');

有关编辑器方法的详细列表，请查看 Editor Methods guide.

9. 利用 Plate 的内置插件

Plate 有许多内置插件，你可以在侧边栏中看到。使用它们快速添加功能：

import { BoldPlugin, ItalicPlugin, UnderlinePlugin } from '@udecode/plate/react';
 
const plugins = [
  BoldPlugin,
  ItalicPlugin,
  UnderlinePlugin,
  // ... other plugins
];
 
const editor = createPlateEditor({ plugins });

10. 测试和优化

迁移后，彻底测试你的编辑器，确保所有功能按预期工作。使用 Plate 的功能和最佳实践优化你的实现。

有关调试提示和策略，请查看我们的 调试指南.

ComponentsPlugin Configuration