Plate 核心

\@platejs/core 的 API 参考文档。

API

`createPlateEditor`

生成一个新的 PlateEditor 实例，使用一组插件及其配置进行初始化。

OptionsCreatePlateEditorOptions

id optional any
编辑器的唯一标识符。
editor optional E
未应用 withPlate 的初始编辑器。
plugins optional P[]
编辑器插件数组。
value optional V
编辑器的初始值。
autoSelect optional 'end' | 'start' | boolean
初始化后是否选中编辑器。
- 默认值: false
- true | 'end': 选中编辑器末尾
- false: 不选中任何内容
- 'start': 选中编辑器开头
maxLength optional number
指定编辑器中允许的最大字符数。
nodeId optional object | boolean
自动节点 ID 生成和管理的配置。
selection optional TSelection
编辑器的初始选区。
shouldNormalizeEditor optional boolean
当 true 时，将规范化传递给 editor 的初始 value。
- 默认值: false
rootPlugin optional (plugin: AnyPlatePlugin) => AnyPlatePlugin
配置根插件的函数。
api optional object
编辑器的 API 方法。
decorate optional function
编辑器的装饰函数。
extendEditor optional function
扩展编辑器的函数。
handlers optional object
编辑器的事件处理器。
inject optional object
编辑器的注入配置。
normalizeInitialValue optional function
规范化初始值的函数。
options optional object
编辑器的附加选项。
override optional object
编辑器的覆盖配置。
priority optional number
编辑器插件的优先级。
readOnly optional boolean
编辑器的只读初始状态。对于动态值，使用 Plate.readOnly 属性。
render optional object
编辑器的渲染函数。
shortcuts optional object
编辑器的键盘快捷键。
transforms optional object
编辑器的转换函数。
useHooks optional function
与编辑器一起使用的钩子。

ReturnsPlateEditor

应用了插件和配置的编辑器实例。

有关编辑器配置的更多详情，请参阅编辑器配置指南。

`createPlatePlugin`

使用给定配置创建一个新的 Plate 插件，支持扩展、嵌套插件操作和运行时配置。

Parameters

Collapse all

config PlatePluginConfig | ((editor: PlateEditor) => PlatePluginConfig)

插件的配置对象，或返回配置的函数。如果提供函数，将在解析插件时使用编辑器执行该函数。

有关 PlatePluginConfig 类型的详情，请参阅PlatePlugin API。

ReturnsPlatePlugin

一个新的插件实例。

`createTPlatePlugin`

createPlatePlugin 的显式类型版本。

Parameters

Collapse all

config TPlatePluginConfig<C> | ((editor: PlateEditor) => TPlatePluginConfig<C>)

插件的配置对象，或返回配置的函数。此版本需要显式类型参数 C 扩展 AnyPluginConfig。

有关 TPlatePluginConfig 类型的详情，请参阅PlatePlugin API。

ReturnsPlatePlugin<C>

一个新的插件实例。

`toPlatePlugin`

扩展 SlatePlugin 以创建 React PlatePlugin。

Parameters

Collapse all

basePlugin SlatePlugin

要扩展的基础 SlatePlugin。

extendConfig optional PlatePluginConfig | ((ctx: PlatePluginContext<C>) => PlatePluginConfig)

提供扩展配置的函数或对象。如果是函数，它接收插件上下文并应返回部分 PlatePlugin。如果是对象，它应是部分 PlatePlugin 配置。

ReturnsPlatePlugin

一个新的插件实例，结合了基础 SlatePlugin 功能和扩展配置中定义的 React 特定特性。

`toTPlatePlugin`

toPlatePlugin 的显式类型版本。

Parameters

Collapse all

basePlugin SlatePlugin<TContext>

要扩展的基础 SlatePlugin。

extendConfig optional ExtendPluginConfig<C> | ((ctx: PlatePluginContext<TContext>) => ExtendPluginConfig<C>)

提供扩展配置的函数或对象。此版本需要为基本插件配置(TContext)和扩展配置(C)提供显式类型参数。

ReturnsPlatePlugin<C>

具有精确类型控制的新插件实例。

`useEditorContainerRef`

ReturnsReact.RefObject<HTMLDivElement>

编辑器容器的 DOM 引用。

`useEditorScrollRef`

ReturnsReact.RefObject<HTMLDivElement>

编辑器滚动容器的 DOM 引用。

`useScrollRef`

ReturnsReact.RefObject<HTMLDivElement>

编辑器滚动容器引用。如果存在滚动引用则返回它，否则返回容器引用。

`useEditorPlugin`

获取编辑器和插件上下文。

Parameters

Collapse all

p WithRequiredKey<P>

具有必需键的插件或插件配置。

ReturnsPlatePluginContext

Collapse all

editor PlateEditor

当前编辑器实例。

plugin PlatePlugin

插件实例。

getOption function

获取特定选项值的函数。

getOptions function

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

setOption function

设置特定选项值的函数。

setOptions function

设置多个选项的函数。

store PlateStore

编辑器的 Plate 存储。

`useEditorRef`

获取 Plate 编辑器引用而不重新渲染。返回的编辑器对象增强了 store 属性，提供对 Plate 存储的访问。

Parameters

Collapse all

id optional string

用于访问嵌套编辑器的编辑器 ID。未提供时，返回 React 树中最近的编辑器实例。仅在处理嵌套编辑器时使用此参数以定位特定范围。

ReturnsPlateEditor & { store: PlateStore }

带有附加存储的编辑器引用。

`useEditorSelector`

订阅编辑器的特定属性。

Parameters

Collapse all

selector (editor: PlateEditor<V>, prev?: T) => T

选择器函数。

deps DependencyList

选择器函数的依赖项列表。

options optional UseEditorSelectorOptions<T>

选择器函数的选项。

Options

Collapse all

id optional string

plate 编辑器的 ID。仅在嵌套编辑器时有用。默认使用最近的编辑器 id。

equalityFn optional (a: T, b: T) => boolean

确定选择器函数结果是否已更改的相等性函数。默认为 (a, b) => a === b。

ReturnsT

选择器函数的返回值。

`useEditorState`

获取带重新渲染的 Plate 编辑器引用。

Parameters

Collapse all

id optional string

plate 编辑器的 ID。默认使用最近的编辑器 id。

ReturnsPlateEditor

编辑器引用。

`useEditorComposing`

获取编辑器的 composing 状态。

Parameters

Collapse all

id optional string

plate 编辑器的 ID。

Returnsboolean

编辑器是否正在组合。

`useEditorReadOnly`

获取编辑器的 readOnly 状态。

Parameters

Collapse all

id optional string

plate 编辑器的 ID。

Returnsboolean

编辑器是否为只读。

`useEditorMounted`

获取编辑器的 isMounted 状态。

Parameters

Collapse all

id optional string

plate 编辑器的 ID。

Returnsboolean

编辑器是否已挂载。

`useEditorSelection`

获取编辑器的选区。已记忆化，如果范围相同则不会重新渲染。

Parameters

Collapse all

id optional string

plate 编辑器的 ID。

ReturnsTRange | null

编辑器中的当前选区。

`useEditorVersion`

获取编辑器值的版本。每次编辑器更改时该版本都会递增。

Parameters

Collapse all

id optional string

plate 编辑器的 ID。

Returnsnumber

编辑器值的当前版本。

`useSelectionVersion`

获取编辑器选区的版本。每次选区更改(范围不同)时该版本都会递增。

Parameters

Collapse all

id optional string

plate 编辑器的 ID。

Returnsnumber

编辑器选区的当前版本。

`useSelectionCollapsed`

Returnsboolean

当前选区是否折叠。

`useSelectionExpanded`

Returnsboolean

当前选区是否展开。

`useSelectionWithinBlock`

Returnsboolean

当前选区是否在单个块内。

`useSelectionAcrossBlocks`

Returnsboolean

当前选区是否跨越多个块。

`useSelectionFragment`

返回当前选区的片段，可选择解构结构节点。

ReturnsTElement[]

当前选区的片段。如果选区未展开或未找到片段，则返回空数组。

`useSelectionFragmentProp`

返回从当前选区片段派生的属性值。

OptionsGetSelectionFragmentOptions & GetFragmentPropOptions

Collapse all

key optional string

要从每个节点提取的属性键。

defaultValue optional string

如果未找到有效属性则返回的默认值。

getProp optional (node: TElement | TText) => any

从节点提取属性值的自定义函数。

mode optional 'all' | 'block' | 'text'

确定如何遍历片段:

'all': 检查块节点和文本节点
'block': 仅检查块节点
'text': 仅检查文本节点
默认值: 'block'

Returns

从片段节点派生的值，如果在指定节点中未找到一致值则为 undefined。

`useNodePath`

返回编辑器中节点的路径。

Parameters

Collapse all

node TNode

要查找路径的节点。

Returns

表示节点在编辑器树结构中位置的记忆化 Path 数组。

`usePath`

获取最近元素的记忆化路径。

Parameters

Collapse all

pluginKey optional string

要获取路径的插件键。

Returns

元素的路径，如果在节点组件上下文之外使用则返回 undefined。

`usePluginOption`

用于从插件存储访问插件选项的 Hook。用于 <Plate> 内部。

Parameters

Collapse all

plugin PlatePlugin

要获取选项的插件。

key keyof (InferOptions<C> | InferSelectors<C>) | 'state'

要访问的选项或选择器的键。

...args optional any[]

附加参数:

对于选择器: 选择器参数
最后一个参数可以是相等函数 (a: T, b: T) => boolean

ReturnsT

选项或选择器结果的值:

对于 'state': 返回整个状态对象
对于选择器键: 返回选择器的返回值
对于选项键: 返回选项值

// 访问简单选项
const value = usePluginOption(plugin, 'value');
// 使用参数访问选择器
const doubleValue = usePluginOption(plugin, 'doubleValue', 2);
// 使用相等函数访问
const value = usePluginOption(plugin, 'value', (a, b) => a === b);
// 访问整个状态
const state = usePluginOption(plugin, 'state');

`useEditorPluginOption`

用于从插件存储访问插件选项的 Hook。用于 <Plate> 外部。

Parameters

Collapse all

editor PlateEditor

编辑器实例。

plugin PlatePlugin

要获取选项的插件。

key keyof (InferOptions<C> | InferSelectors<C>) | 'state'

要访问的选项或选择器的键。

...args optional any[]

附加参数:

对于选择器: 选择器参数
最后一个参数可以是相等函数 (a: T, b: T) => boolean

ReturnsT

选项或选择器结果的值:

对于 'state': 返回整个状态对象
对于选择器键: 返回选择器的返回值
对于选项键: 返回选项值

// 访问简单选项
const value = useEditorPluginOption(editor, plugin, 'value');
// 使用参数访问选择器
const doubleValue = useEditorPluginOption(editor, plugin, 'doubleValue', 2);
// 使用相等函数访问
const value = useEditorPluginOption(editor, plugin, 'value', (a, b) => a === b);
// 访问整个状态
const state = useEditorPluginOption(editor, plugin, 'state');

`useElement`

通过插件键获取元素。

Parameters

Collapse all

pluginKey optional string

要获取元素的插件键。

默认值: 'element'

Returns

类型为 T extends TElement 的元素，如果在节点组件上下文之外使用则返回空对象。

核心插件

`DebugPlugin`

提供具有可配置日志级别和错误处理功能的调试功能。

查看调试了解更多详情。

`SlateExtensionPlugin & SlateReactExtensionPlugin`

扩展核心 API 并改进默认功能。

`DOMPlugin & ReactPlugin`

将 React 特定功能集成到编辑器中。

`HistoryPlugin`

为编辑器启用撤销和重做功能。

`InlineVoidPlugin`

管理编辑器中的内联和空元素。

`ParserPlugin`

处理编辑器内容的解析。

`LengthPlugin`

强制执行编辑器内容的最大长度限制。

`HtmlPlugin`

启用 HTML 序列化和反序列化。

`AstPlugin`

处理编辑器的抽象语法树(AST)操作。

`ParagraphPlugin`

提供段落格式化功能。

`EventEditorPlugin`

管理编辑器事件，如焦点和失焦。

工具函数

`isType`

检查节点是否匹配提供的类型。

Parameters

Collapse all

editor PlateEditor<V>

节点所在的编辑器。

node any

要检查的节点。

key optional string | string[]

要与节点匹配的类型或类型数组。可以是字符串或字符串数组。

Returns

表示节点的类型是否匹配提供的类型或类型的布尔值。

组件

`<PlateElement>`

用于渲染元素的通用组件。

Props

Collapse all

className optional string

应用于组件的 CSS 类。

editor E

编辑器实例。也可使用 useEditorRef hook 获取。

element TElement

元素节点。也可使用 useElement hook 获取。

path Path

元素在编辑器树中的路径。也可使用 usePath hook 获取。

attributes HTMLAttributes<HTMLElement>

要应用到顶层元素的元素属性。

children any

渲染节点子元素所必需。

as optional React.ElementType

要渲染的组件类型。

默认值: 'div'

`<PlateLeaf>`

用于渲染叶节点的通用组件。

Props

Collapse all

className optional string

应用于组件的 CSS 类。

editor E

编辑器上下文。

children any

渲染节点子元素所必需。

leaf TText

叶节点。

text TText

文本节点。

attributes HTMLAttributes<HTMLElement>

要应用到顶层元素的叶节点属性。

as optional React.ElementType

要渲染的组件类型。

默认值: 'span'

`<PlateText>`

用于渲染文本的通用组件。

Props

Collapse all

className optional string

应用于组件的 CSS 类。

text TText

文本节点。

attributes HTMLAttributes<HTMLElement>

要应用到顶层元素的文本属性。

children any

渲染节点子元素所必需。

as optional React.ElementType

要渲染的组件类型。

默认值: 'span'

cn Plate Core

Plate 核心

API

createPlateEditor

OptionsCreatePlateEditorOptions

id optional any

editor optional E

plugins optional P[]

value optional V

autoSelect optional 'end' | 'start' | boolean

maxLength optional number

nodeId optional object | boolean

Show child attributes

selection optional TSelection

shouldNormalizeEditor optional boolean

rootPlugin optional (plugin: AnyPlatePlugin) => AnyPlatePlugin

api optional object

decorate optional function

extendEditor optional function

handlers optional object

inject optional object

normalizeInitialValue optional function

options optional object

override optional object

priority optional number

readOnly optional boolean

render optional object

shortcuts optional object

transforms optional object

useHooks optional function

ReturnsPlateEditor

createPlatePlugin

Parameters

config PlatePluginConfig | ((editor: PlateEditor) => PlatePluginConfig)

ReturnsPlatePlugin

createTPlatePlugin

Parameters

config TPlatePluginConfig<C> | ((editor: PlateEditor) => TPlatePluginConfig<C>)

ReturnsPlatePlugin<C>

toPlatePlugin

Parameters

basePlugin SlatePlugin

extendConfig optional PlatePluginConfig | ((ctx: PlatePluginContext<C>) => PlatePluginConfig)

ReturnsPlatePlugin

toTPlatePlugin

Parameters

basePlugin SlatePlugin<TContext>

extendConfig optional ExtendPluginConfig<C> | ((ctx: PlatePluginContext<TContext>) => ExtendPluginConfig<C>)

ReturnsPlatePlugin<C>

useEditorContainerRef

ReturnsReact.RefObject<HTMLDivElement>

useEditorScrollRef

ReturnsReact.RefObject<HTMLDivElement>

useScrollRef

ReturnsReact.RefObject<HTMLDivElement>

useEditorPlugin

Parameters

p WithRequiredKey<P>

ReturnsPlatePluginContext

editor PlateEditor

plugin PlatePlugin

getOption function

getOptions function

setOption function

setOptions function

store PlateStore

useEditorRef

Parameters

id optional string

ReturnsPlateEditor & { store: PlateStore }

useEditorSelector

Parameters

selector (editor: PlateEditor<V>, prev?: T) => T

deps DependencyList

options optional UseEditorSelectorOptions<T>

Options

id optional string

equalityFn optional (a: T, b: T) => boolean

ReturnsT

useEditorState

Parameters

`createPlateEditor`

`createPlatePlugin`

`createTPlatePlugin`

`toPlatePlugin`

`toTPlatePlugin`

`useEditorContainerRef`

`useEditorScrollRef`

`useScrollRef`

`useEditorPlugin`

`useEditorRef`

`useEditorSelector`

`useEditorState`

`useEditorComposing`

`useEditorReadOnly`

`useEditorMounted`

`useEditorSelection`

`useEditorVersion`

`useSelectionVersion`

`useSelectionCollapsed`

`useSelectionExpanded`

`useSelectionWithinBlock`

`useSelectionAcrossBlocks`

`useSelectionFragment`

`useSelectionFragmentProp`

`useNodePath`

`usePath`

`usePluginOption`

`useEditorPluginOption`