Plate 插件

PreviousNext

Plate 插件的 API 参考文档。

Plate 插件是通过 Plate 组件的 plugins 属性传递的对象。

插件属性

Attributes

  • key REQUIRED C['key']

    Plate 用于在 editor.plugins 中按 key 存储插件的唯一标识符。

  • api Record<string, Function>

    插件提供的 API 函数对象。这些函数可通过 editor.api[key] 访问。

  • transforms Record<string, Function>

    插件提供的用于修改编辑器状态的转换函数。可通过 editor.tf[key] 访问。

  • options Record<string, any>

    插件使用的扩展选项属性。

  • handlers { onChange?: (editor: PlateEditor) => void } & Record<string, Function>

    编辑器事件的事件处理器，包括 onChange。

  • inject object

    定义插件如何向其他插件或编辑器注入功能。

  • node object

    定义插件的节点特定配置。

  • override object

    允许按 key 覆盖组件和插件。

  • parser Nullable<Parser<WithAnyKey<C>>>

    定义插件如何解析内容。

  • parsers object

    定义各种格式的序列化和反序列化器。

  • render object

    定义插件如何渲染组件。

  • shortcuts Shortcuts

    定义插件的键盘快捷键。

  • useOptionsStore StoreApi<C['key'], C['options']>

    用于管理插件选项的 Zustand store。

  • dependencies string[]

    此插件依赖的插件 key 数组。

  • enabled optional boolean

    启用或禁用插件。Plate 使用此属性决定是否使用该插件。

  • plugins any[]

    递归插件支持，允许在单个插件中包含多个插件。

  • priority number

    定义插件注册和执行的顺序。

    • 默认值: 100

  • decorate optional Decorate<WithAnyKey<C>>

    Plate 用于装饰编辑器范围的属性。

  • extendEditor optional ExtendEditor<WithAnyKey<C>>

    扩展编辑器实例的函数。主要用于集成需要直接编辑器变异的旧版 Slate 插件。每个插件只允许一个 extendEditor。

    extendEditor: ({ editor }) => {
  // 示例：集成旧版 Slate 插件
  return withYjs(editor);
}

  • useHooks optional () => void

    编辑器初始化时调用的钩子。

  • editOnly optional boolean | EditOnlyConfig

    配置哪些插件功能仅在编辑器非只读时激活。

    可以是布尔值或对象配置：

    type EditOnlyConfig = {
  render?: boolean;      // 默认: true
  handlers?: boolean;    // 默认: true
  inject?: boolean;      // 默认: true
  normalizeInitialValue?: boolean;  // 默认: false
}

    当设置为 true（布尔值）时：

    • render、handlers 和 inject.nodeProps 仅在编辑器非只读时激活
    • normalizeInitialValue 无论只读状态如何都保持激活

    当设置为对象时：

    • 每个属性可以单独配置
    • 属性默认是仅编辑的（true），除了 normalizeInitialValue 默认始终激活（false）
    • 将属性设置为 false 使其始终激活，无论只读状态如何
    • 对于 normalizeInitialValue，设置为 true 使其仅在编辑时激活

    示例：

    // 所有功能（除 normalizeInitialValue 外）都是仅编辑的
editOnly: true
 
// normalizeInitialValue 是仅编辑的，其他保持默认行为
editOnly: { normalizeInitialValue: true }
 
// render 始终激活，其他遵循默认行为
editOnly: { render: false }

插件方法

Methods

Collapse all

  • configure (config: PlatePluginConfig | ((ctx: PlatePluginContext) => PlatePluginConfig)) => PlatePlugin

    创建一个具有更新选项的新插件实例。

    (config: PlatePluginConfig<C['key'], InferOptions<C>, InferApi<C>, InferTransforms<C>> | ((ctx: PlatePluginContext<C>) => PlatePluginConfig<C['key'], InferOptions<C>, InferApi<C>, InferTransforms<C>>)) => PlatePlugin<C>

  • extend (config: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin

    创建一个具有额外配置的新插件实例。

    (extendConfig: Partial<PlatePlugin> | ((ctx: PlatePluginContext<AnyPluginConfig>) => Partial<PlatePlugin>)) => PlatePlugin

  • extendPlugin (key: string, config: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin

    扩展现有嵌套插件或在未找到时添加新插件。支持深层嵌套。

    (key: string, extendConfig: Partial<PlatePlugin> | ((ctx: PlatePluginContext<AnyPluginConfig>) => Partial<PlatePlugin>)) => PlatePlugin

  • withComponent function

    设置或替换与插件关联的组件。

    (component: NodeComponent) => PlatePlugin<C>

  • overrideEditor function

    创建一个具有重写编辑器方法的新插件实例。通过 tf 和 api 参数提供对原始方法的访问。可以多次调用以叠加不同的重写。

    overrideEditor(({ editor, tf: { deleteForward }, api: { isInline } }) => ({
  transforms: {
    // 重写 transforms
    deleteForward(options) {
      deleteForward(options);
    },
  },
  api: {
    // 重写 API 方法
    isInline(element) {
      return isInline(element);
    },
  },
})) => PlatePlugin<C>
    • 修改编辑器行为的首选方法
    • 类型安全的原始方法访问
    • transforms 和 API 的清晰分离
    • 可以多次链式调用

  • extendApi (api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

    扩展插件的 API。

    (api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

  • extendEditorApi (api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

    使用插件特定方法扩展编辑器的 API。

    (api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

  • extendTransforms (transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

    扩展插件的 transforms。

    (transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

  • extendEditorTransforms (transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

    使用插件特定方法扩展编辑器的 transforms。

    (transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin

  • extendSelectors (options: (ctx: PlatePluginContext) => Record<string, any>) => PlatePlugin

    扩展插件的选择器。

    (options: (ctx: PlatePluginContext) => Record<string, any>) => PlatePlugin

插件上下文

Attributes

Collapse all

  • editor PlateEditor

    当前编辑器实例。

  • plugin EditorPlatePlugin<C>

    当前插件实例。

  • getOption function

    获取特定选项值的函数。

  • getOptions function

    获取插件所有选项的函数。

  • setOption function

    设置特定选项值的函数。

  • setOptions function

    设置多个选项的函数。

有关 Plate 插件特定方面的更详细信息，请参阅 插件配置、插件方法、插件上下文、插件组件 和 插件快捷键 的单独指南。

泛型类型

Attributes

Collapse all

  • C AnyPluginConfig = PluginConfig

    表示插件配置。此类型扩展了 PluginConfig，包括 key、options、api 和 transforms。

使用示例：

type MyPluginConfig = PluginConfig<
  'myPlugin',
  { customOption: boolean },
  { getData: () => string },
  { customTransform: () => void }
>;
 
const MyPlugin = createPlatePlugin<MyPluginConfig>({
  key: 'myPlugin',
  // 插件实现
});
Plate EditorPlate Plugin