docs

udecode · Jan 9, 2025 · f37dbd1 · f37dbd1
1 parent 8ce560d
commit f37dbd1
Show file tree

Hide file tree

Showing 9 changed files with 255 additions and 130 deletions.
diff --git a/apps/www/content/docs/cn/api/core.mdx b/apps/www/content/docs/cn/api/core.mdx
@@ -455,7 +455,7 @@ description: udecode/plate-core的 API 参考。
 
 有关更多详细信息，请参阅[调试](/docs/debugging)。
 
-### SlateNextPlugin
+### SlateExtensionPlugin & SlateReactExtensionPlugin
 扩展核心 API 并改进默认功能。
 
 ### DOMPlugin & ReactPlugin
@@ -485,9 +485,6 @@ description: udecode/plate-core的 API 参考。
 ### EventEditorPlugin
 管理编辑器事件，如焦点和模糊。
 
-### PlateApiPlugin
-提供 Plate 编辑器功能的核心 API。
-
 ## Utils
 
 ### isType

diff --git a/apps/www/content/docs/cn/api/core/plate-editor.mdx b/apps/www/content/docs/cn/api/core/plate-editor.mdx
@@ -36,55 +36,55 @@ description: Plate 编辑器的 API 参考。
 ## API Methods
 
 <APIParameters>
-  <APIItem name="getApi" type="<C extends AnyPluginConfig = PluginConfig>(plugin?: WithRequiredKey<C>) => InferApi<C>">
+  <APIItem name="getApi" type="(plugin: PlatePlugin) => EditorApi & PlatePlugin['api']">
     获取插件的类型化 API。
   </APIItem>
-  <APIItem name="getTransforms" type="<C extends AnyPluginConfig = PluginConfig>(plugin?: WithRequiredKey<C>) => InferTransforms<C>">
+  <APIItem name="getTransforms" type="(plugin: PlatePlugin) => EditorTransforms & PlatePlugin['transforms']">
     获取插件的类型化变换。
   </APIItem>
-  <APIItem name="getPlugin" type="<C extends AnyPluginConfig = PluginConfig>(plugin: WithRequiredKey<C>) => C extends { node: any } ? C : EditorPlatePlugin<C>">
+  <APIItem name="getPlugin" type="(plugin: PlatePlugin) => PlatePlugin">
     通过键或基础插件获取编辑器插件实例。
   </APIItem>
-  <APIItem name="getType" type="(plugin: WithRequiredKey) => string">
+  <APIItem name="getType" type="(plugin: PlatePlugin) => string">
     获取插件的节点类型。
   </APIItem>
 </APIParameters>
 
 ## Option Methods
 
 <APIParameters>
-  <APIItem name="getOption" type="<C extends AnyPluginConfig, K extends keyof InferOptions<C>, F extends InferOptions<C>[K]>(plugin: WithRequiredKey<C>, optionKey: K, ...args: F extends (...args: infer A) => any ? A : never) => F extends (...args: any[]) => infer R ? R : F">
+  <APIItem name="getOption" type="(plugin: PlatePlugin, optionKey: string) => any">
     获取插件的特定选项值。
   </APIItem>
-  <APIItem name="getOptions" type="<C extends AnyPluginConfig = PluginConfig>(plugin: WithRequiredKey<C>) => InferOptions<C>">
+  <APIItem name="getOptions" type="(plugin: PlatePlugin) => any">
     获取插件的所有选项。
   </APIItem>
-  <APIItem name="setOption" type="<C extends AnyPluginConfig, K extends keyof InferOptions<C>>(plugin: WithRequiredKey<C>, optionKey: K, value: InferOptions<C>[K]) => void">
+  <APIItem name="setOption" type="(plugin: PlatePlugin, optionKey: string, value: any) => void">
     设置插件的特定选项值。
   </APIItem>
-  <APIItem name="setOptions" type="<C extends AnyPluginConfig>(plugin: WithRequiredKey<C>, options: Parameters<SetImmerState<InferOptions<C>>>[0] | Partial<InferOptions<C>>) => void">
+  <APIItem name="setOptions" type="(plugin: PlatePlugin, options: (draft: object) => void | Partial<object>) => void">
     设置插件的多个选项。
   </APIItem>
-  <APIItem name="getOptionsStore" type="<C extends AnyPluginConfig>(plugin: WithRequiredKey<C>) => StoreApi<C['key'], InferOptions<C>>">
+  <APIItem name="getOptionsStore" type="(plugin: PlatePlugin) => any">
     获取插件的 zustand-x 选项存储。
   </APIItem>
 </APIParameters>
 
 ## React Hooks
 
 <APIParameters>
-  <APIItem name="useOption" type="<C extends AnyPluginConfig, K extends keyof InferOptions<C>, F extends InferOptions<C>[K], Args extends Parameters<((...args: any[]) => any) & F>>(plugin: WithRequiredKey<C>, optionKey: K, ...args: Args) => F extends (...args: any[]) => any ? ReturnType<F> : F">
+  <APIItem name="useOption" type="(plugin: PlatePlugin, optionKey: string) => any">
     在 React 组件中订阅特定选项值。
   </APIItem>
-  <APIItem name="useOptions" type="<C extends AnyPluginConfig, U>(plugin: WithRequiredKey<C>, selector?: (s: InferOptions<C>) => U, equalityFn?: EqualityChecker<U>) => U | InferOptions<C>">
+  <APIItem name="useOptions" type="(plugin: PlatePlugin) => any">
     在 React 组件中订阅插件选项或派生自选项的值。
   </APIItem>
 </APIParameters>
 
 ## Plate Store Methods
 
 <APIParameters>
-  <APIItem name="setPlateState" type="<K extends (typeof EXPOSED_STORE_KEYS)[number]>(optionKey: K, value: PlateStoreState[K]) => void">
+  <APIItem name="setPlateState" type="(optionKey: string, value: PlateStoreState[K]) => void">
     更新全局 Plate 状态。
   </APIItem>
 </APIParameters>
@@ -108,17 +108,6 @@ description: Plate 编辑器的 API 参考。
   </APIItem>
 </APIParameters>
 
-### SlateNextPlugin
-
-<APIParameters>
-  <APIItem name="editor.tf.toggle.block" type="(options: ToggleBlockOptions) => void">
-    切换一个块元素。
-  </APIItem>
-  <APIItem name="editor.tf.toggle.mark" type="(options: ToggleMarkOptions) => void">
-    切换选中文本上的标记。
-  </APIItem>
-</APIParameters>
-
 ### HtmlPlugin
 
 <APIParameters>
@@ -135,7 +124,7 @@ description: Plate 编辑器的 API 参考。
   </APIItem>
 </APIParameters>
 
-### PlateApiPlugin
+### SlateReactExtensionPlugin
 
 <APIParameters>
   <APIItem name="editor.api.redecorate" type="() => void">

diff --git a/apps/www/content/docs/cn/api/core/plate-plugin.mdx b/apps/www/content/docs/cn/api/core/plate-plugin.mdx
@@ -39,27 +39,27 @@ const MyPlugin = createPlatePlugin<MyPluginConfig>({
 Plate 用于存储插件的唯一标识符，通过 `editor.plugins` 键。
 </APIItem>
 
-<APIItem name="api" type="UnionToIntersection<InferApi<C>>">
+<APIItem name="api" type="Record<string, Function>">
 插件提供的 API 函数对象。这些函数通过 `editor.api[key]` 访问。
 </APIItem>
 
-<APIItem name="transforms" type="UnionToIntersection<InferTransforms<C>>">
+<APIItem name="transforms" type="Record<string, Function>">
 插件提供的变换函数，用于修改编辑器状态。这些函数通过 `editor.tf[key]` 访问。
 </APIItem>
 
-<APIItem name="options" type="InferOptions<C>">
+<APIItem name="options" type="Record<string, any>">
 插件作为选项使用的扩展属性。
 </APIItem>
 
-<APIItem name="handlers" type="Nullable<DOMHandlers<WithAnyKey<C>> & { onChange?: OnChange<WithAnyKey<C>> }>">
+<APIItem name="handlers" type="{ onChange?: (editor: PlateEditor) => void } & Record<string, Function>">
 各种编辑器事件的事件处理程序，包括 `onChange`。
 </APIItem>
 
-<APIItem name="inject" type="Nullable<{...}>">
+<APIItem name="inject" type="object">
 定义插件如何将功能注入其他插件或编辑器。
 
 <APISubList>
-<APISubListItem parent="inject" name="nodeProps" type="InjectNodeProps<WithAnyKey<C>>" optional>
+<APISubListItem parent="inject" name="nodeProps" type="Record<string, any>" optional>
 Plate 用于将属性注入任何节点组件的属性。
 </APISubListItem>
 
@@ -84,7 +84,7 @@ Plate 用于将属性注入任何节点组件的属性。
 <APISubListItem parent="inject" name="maxLevel" type="number" optional>
 节点属性注入的最大嵌套级别。深度大于此级别的节点将不会接收注入的属性。
 </APISubListItem>
-<APISubListItem parent="inject" name="plugins" type="Record<string, Partial<EditorPlatePlugin<AnyPluginConfig>>>" optional>
+<APISubListItem parent="inject" name="plugins" type="Record<string, Partial<PlatePlugin>>" optional>
 插件可以使用的属性，用于允许其他插件注入代码。
 </APISubListItem>
 <APISubListItem parent="inject" name="targetPluginToInject" type="function" optional>
@@ -98,7 +98,7 @@ Plate 用于将属性注入任何节点组件的属性。
 </APISubList>
 </APIItem>
 
-<APIItem name="node" type="BasePluginNode">
+<APIItem name="node" type="object">
 定义插件的节点特定配置。
 
 <APISubList>
@@ -164,14 +164,14 @@ HTML React 序列化器配置。
 </APISubList>
 </APIItem>
 
-<APIItem name="render" type="Nullable<{...}>">
-定义编辑器各个部分的渲染函数。
+<APIItem name="render" type="object">
+定义插件如何渲染组件。
 
 <APISubList>
-<APISubListItem parent="render" name="aboveEditable" type="React.FC<{ children: React.ReactNode }>" optional>
+<APISubListItem parent="render" name="aboveEditable" type="Component" optional>
 在 `Editable` 组件上方但在 `Slate` 包装器内渲染组件。
 </APISubListItem>
-<APISubListItem parent="render" name="aboveNodes" type="NodeWrapperComponent<WithAnyKey<C>>" optional>
+<APISubListItem parent="render" name="aboveNodes" type="Component" optional>
 在所有其他插件的 `node` 组件上方渲染组件。
 </APISubListItem>
 <APISubListItem parent="render" name="aboveSlate" type="React.FC<{ children: React.ReactNode }>" optional>
@@ -222,30 +222,40 @@ HTML React 序列化器配置。
 Plate 用来装饰编辑器范围的属性。
 </APIItem>
 
-<APIItem name="useHooks" type="UseHooks<WithAnyKey<C>>" optional>
-Hook called when the editor is initialized.
+<APIItem name="extendEditor" type="ExtendEditor<WithAnyKey<C>>" optional>
+用于扩展编辑器实例的函数。主要用于集成需要直接编辑器变更的传统 Slate 插件。每个插件只允许一个 `extendEditor`。
+
+```ts
+extendEditor: ({ editor }) => {
+  // 示例：集成传统 Slate 插件
+  return withYjs(editor);
+}}
+</APIItem>
+
+<APIItem name="useHooks" type="() => void" optional>
+当编辑器初始化时调用的钩子。
 </APIItem>
 </APIAttributes>
 
 ## Plugin Methods
 
 <APIAttributes>
-<APIItem name="configure" type="function">
+<APIItem name="configure" type="(config: PlatePluginConfig | ((ctx: PlatePluginContext) => PlatePluginConfig)) => PlatePlugin">
 创建一个具有更新选项的新插件实例。
 
 ```ts
 (config: PlatePluginConfig<C['key'], InferOptions<C>, InferApi<C>, InferTransforms<C>> | ((ctx: PlatePluginContext<C>) => PlatePluginConfig<C['key'], InferOptions<C>, InferApi<C>, InferTransforms<C>>)) => PlatePlugin<C>
 ```
 </APIItem>
 
-<APIItem name="extend" type="function">
+<APIItem name="extend" type="(config: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin">
 创建一个具有附加配置的新插件实例。可以接受一个对象或一个函数。
 
 ```ts
 (extendConfig: Partial<PlatePlugin> | ((ctx: PlatePluginContext<AnyPluginConfig>) => Partial<PlatePlugin>)) => PlatePlugin
 ```
 </APIItem>
-<APIItem name="extendPlugin" type="function">
+<APIItem name="extendPlugin" type="(key: string, config: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin">
 扩展一个现有的嵌套插件或添加一个新的插件，如果未找到。支持深度嵌套。
 
 ```ts
@@ -261,45 +271,71 @@ Hook called when the editor is initialized.
 ```
 </APIItem>
 
-<APIItem name="extendApi" type="function">
+<APIItem name="extendApi" type="(api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
 扩展插件的 API。
 
 ```ts
 (api: (ctx: PlatePluginContext<AnyPluginConfig>) => any) => PlatePlugin<C>
 ```
 </APIItem>
 
-<APIItem name="extendEditorApi" type="function">
+<APIItem name="extendEditorApi" type="(api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
 使用插件特定的方法扩展编辑器的 API。
 
 ```ts
 (api: (ctx: PlatePluginContext<AnyPluginConfig>) => any) => PlatePlugin<C>
 ```
 </APIItem>
 
-<APIItem name="extendTransforms" type="function">
-使用插件特定的方法扩展插件的变换。
+<APIItem name="extendTransforms" type="(transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
+扩展插件的变换。
 
 ```ts
 (transforms: (ctx: PlatePluginContext<AnyPluginConfig>) => any) => PlatePlugin<C>
 ```
 </APIItem>
 
-<APIItem name="extendEditorTransforms" type="function">
+<APIItem name="extendEditorTransforms" type="(transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
 使用插件特定的方法扩展编辑器的变换。
 
 ```ts
 (transforms: (ctx: PlatePluginContext<AnyPluginConfig>) => any) => PlatePlugin<C>
 ```
 </APIItem>
 
-<APIItem name="extendOptions" type="function">
+<APIItem name="extendOptions" type="(options: (ctx: PlatePluginContext) => Record<string, any>) => PlatePlugin">
 使用选择器扩展插件选项。
 
 ```ts
 (options: (ctx: PlatePluginContext<AnyPluginConfig>) => any) => PlatePlugin<C>
 ```
 </APIItem>
+
+<APIItem name="overrideEditor" type="function">
+创建一个具有覆盖编辑器方法的新插件实例。通过 `tf` 和 `api` 参数提供对原始方法的访问。可以多次调用以层叠不同的覆盖。
+
+```ts
+overrideEditor(({ editor, tf: { deleteForward }, api: { isInline } }) => ({
+  transforms: {
+    // 覆盖 transforms
+    deleteForward(options) {
+      deleteForward(options);
+    },
+  },
+  api: {
+    // 覆盖 API 方法
+    isInline(element) {
+      return isInline(element);
+    },
+  },
+})) => PlatePlugin<C>
+```
+
+- 修改编辑器行为的首选方法
+- 对原始方法的类型安全访问
+- 在 transforms 和 API 之间清晰分离
+- 可以多次链式调用
+</APIItem>
 </APIAttributes>
 
 ## Plugin Context

diff --git a/apps/www/content/docs/cn/plugin-methods.mdx b/apps/www/content/docs/cn/plugin-methods.mdx
@@ -299,39 +299,53 @@ editor.tf.editorTransform();
 
 ```ts
 const CodeBlockPlugin = toPlatePlugin(createSlatePlugin({ key: 'code_block' }), {
-  extendEditor: ({ api, editor }) => {
-    api.plugin.getSyntaxState();
-    return editor;
-  },
   handlers: {},
   options: { hotkey: ['mod+opt+8', 'mod+shift+8'] },
 });
 ```
 
 ### .overrideEditor
 
-`overrideEditor` 方法专门用于覆盖现有的编辑器方法：
+`overrideEditor` 方法专门用于覆盖现有的编辑器方法，同时保持对原始实现的访问：
 
 ```ts
 const MyPlugin = createPlatePlugin({
   key: 'myPlugin',
 }).overrideEditor(({ editor, tf: { insertText }, api: { isInline } }) => ({
   transforms: {
     insertText(text) {
-      // 覆盖 insertText 行为
+      // 自定义逻辑
+      console.log('Inserting:', text);
+
+      // 调用原始方法
       insertText(text);
+
+      // 后续逻辑
+      console.log('Inserted:', text);
     },
   },
   api: {
     isInline(element) {
-      // 覆盖 isInline 行为
+      // 自定义内联元素检查
+      if (element.type === 'custom-inline') {
+        return true;
+      }
+
+      // 回退到原始行为
       return isInline(element);
     },
   },
 }));
 ```
 
-- 专门用于覆盖现有的编辑器方法
-- 返回的覆盖方法需要包装在 `transforms` 或 `api` 对象中
+- 修改编辑器行为的首选方法
+- 对原始方法的类型安全访问（通过 `tf` 和 `api` 参数）
+- 在 transforms 和 API 之间清晰分离
+- 可以多次链式调用以层叠不同的覆盖
 - 不能添加新方法（请改用 `extendEditorTransforms` 或 `extendEditorApi`）
-- 通过上下文提供对原始方法的访问
+
+<Callout>
+`extendEditor` 和 `overrideEditor` 的区别：
+- 使用 `extendEditor` 来集成需要直接编辑器变更的传统 Slate 插件，如 `withYjs`。每个插件只能有一个 `extendEditor`。
+- 优先使用 `overrideEditor` 来修改编辑器行为，因为它具有单一职责和更好的类型安全性。它可以多次调用以层叠不同的覆盖。
+</Callout>
diff --git a/apps/www/content/docs/en/api/core.mdx b/apps/www/content/docs/en/api/core.mdx
@@ -457,7 +457,7 @@ Provides debugging capabilities with configurable log levels and error handling.
 
 See [Debugging](/docs/debugging) for more details.
 
-### SlateNextPlugin
+### SlateExtensionPlugin & SlateReactExtensionPlugin
 Extend core apis and improve default functionality.
 
 ### DOMPlugin & ReactPlugin
@@ -487,9 +487,6 @@ Provides paragraph formatting functionality.
 ### EventEditorPlugin
 Manages editor events such as focus and blur.
 
-### PlateApiPlugin
-Provides the core API for Plate editor functionality.
-
 ## Utils
 
 ### isType