diff --git a/.ai/translate.md b/.ai/translate.md new file mode 100644 index 0000000000..67fc3ae856 --- /dev/null +++ b/.ai/translate.md @@ -0,0 +1,27 @@ +Convert all the content into Chinese, excluding any variables And key names, such as Plate. +The following JSX and markdown codeblock like ```tsx must not be translated. + +# Important Notice +1.DONOT remove any content. +2.You can translate the title markdown ## Plugin Context. +3.Please ensure that the number of lines in the translated file MATCHES the original. +4.DONOT translate the entry and entries + +For Example: + +xxxx content + +```ts +(api: (ctx: PlatePluginContext) => any) => PlatePlugin +``` + + +After translate: + +xxxx 内容 + +```ts +(api: (ctx: PlatePluginContext) => any) => PlatePlugin +``` + + diff --git a/apps/www/content/docs/cn/ai.mdx b/apps/www/content/docs/cn/ai.mdx new file mode 100644 index 0000000000..d506636a6f --- /dev/null +++ b/apps/www/content/docs/cn/ai.mdx @@ -0,0 +1,441 @@ +--- +title: AI +docs: + - route: https://pro.platejs.org/docs/examples/ai + title: AI +--- + + + + + +## 功能特性 + +- 预定义命令的组合框菜单： + - 生成：继续写作、添加摘要、解释 + - 编辑：改进写作、加长或缩短、修正拼写和语法、简化语言 +- 三种触发模式： + - 光标模式：在块末尾触发 + - 选择模式：使用选中的文本触发 + - 块选择模式：使用选中的块触发 +- 在预览或直接编辑器插入中流式响应 +- Markdown 支持 +- 内置支持 Vercel AI SDK chat API + + + +## 安装 + +```bash +npm install @udecode/plate-ai @udecode/plate-selection @udecode/plate-markdown @udecode/plate-basic-marks +``` + +## 使用方法 + +### 插件 + +```tsx +import { AIChatPlugin, AIPlugin } from '@udecode/plate-ai/react'; +import { + BaseBoldPlugin, + BaseCodePlugin, + BaseItalicPlugin, + BaseStrikethroughPlugin, + BaseUnderlinePlugin, +} from '@udecode/plate-basic-marks'; +import { BaseBlockquotePlugin } from '@udecode/plate-block-quote'; +import { + BaseCodeBlockPlugin, + BaseCodeLinePlugin, + BaseCodeSyntaxPlugin, +} from '@udecode/plate-code-block'; +import { BaseParagraphPlugin, createSlateEditor } from '@udecode/plate-common'; +import { BaseHeadingPlugin, HEADING_LEVELS } from '@udecode/plate-heading'; +import { BaseHorizontalRulePlugin } from '@udecode/plate-horizontal-rule'; +import { BaseIndentListPlugin } from '@udecode/plate-indent-list'; +import { BaseLinkPlugin } from '@udecode/plate-link'; +import { MarkdownPlugin } from '@udecode/plate-markdown'; +``` + +```tsx +export const createAIEditor = () => { + const editor = createSlateEditor({ + id: 'ai', + plugins: [ + BaseBlockquotePlugin, + BaseBoldPlugin, + BaseCodeBlockPlugin, + BaseCodeLinePlugin, + BaseCodePlugin, + BaseCodeSyntaxPlugin, + BaseItalicPlugin, + BaseStrikethroughPlugin, + BaseUnderlinePlugin, + BaseHeadingPlugin, + BaseHorizontalRulePlugin, + BaseLinkPlugin, + BaseParagraphPlugin, + BaseIndentListPlugin.extend({ + inject: { + targetPlugins: [ + BaseParagraphPlugin.key, + ...HEADING_LEVELS, + BaseBlockquotePlugin.key, + BaseCodeBlockPlugin.key, + ], + }, + options: { + listStyleTypes: { + todo: { + liComponent: TodoLiStatic, + markerComponent: TodoMarkerStatic, + type: 'todo', + }, + }, + }, + }), + MarkdownPlugin.configure({ options: { indentList: true } }), + ], + }); + + + return editor; +}; + +const systemCommon = `\ +You are an advanced AI-powered note-taking assistant, designed to enhance productivity and creativity in note management. +Respond directly to user prompts with clear, concise, and relevant content. Maintain a neutral, helpful tone. + +Rules: +- is the entire note the user is working on. +- is a reminder of how you should reply to INSTRUCTIONS. It does not apply to questions. +- Anything else is the user prompt. +- Your response should be tailored to the user's prompt, providing precise assistance to optimize note management. +- For INSTRUCTIONS: Follow the exactly. Provide ONLY the content to be inserted or replaced. No explanations or comments. +- For QUESTIONS: Provide a helpful and concise answer. You may include brief explanations if necessary. +- CRITICAL: Distinguish between INSTRUCTIONS and QUESTIONS. Instructions typically ask you to modify or add content. Questions ask for information or clarification. +`; + +const systemDefault = `\ +${systemCommon} +- is the current block of text the user is working on. +- Ensure your output can seamlessly fit into the existing structure. +- CRITICAL: Provide only a single block of text. DO NOT create multiple paragraphs or separate blocks. + +{block} + +`; + +const systemSelecting = `\ +${systemCommon} +- is the block of text containing the user's selection, providing context. +- Ensure your output can seamlessly fit into the existing structure. +- is the specific text the user has selected in the block and wants to modify or ask about. +- Consider the context provided by , but only modify . Your response should be a direct replacement for . + +{block} + + +{selection} + +`; + +const systemBlockSelecting = `\ +${systemCommon} +- represents the full blocks of text the user has selected and wants to modify or ask about. +- Your response should be a direct replacement for the entire . +- Maintain the overall structure and formatting of the selected blocks, unless explicitly instructed otherwise. +- CRITICAL: Provide only the content to replace . Do not add additional blocks or change the block structure unless specifically requested. + +{block} + +`; + +const userDefault = ` +CRITICAL: DO NOT use block formatting. You can only use inline formatting. +CRITICAL: DO NOT start new lines or paragraphs. +NEVER write . + +{prompt}`; + +const userSelecting = ` +If this is a question, provide a helpful and concise answer about . +If this is an instruction, provide ONLY the text to replace . No explanations. +Ensure it fits seamlessly within . If is empty, write ONE random sentence. +NEVER write or . + +{prompt} about `; + +const userBlockSelecting = ` +If this is a question, provide a helpful and concise answer about . +If this is an instruction, provide ONLY the content to replace the entire . No explanations. +Maintain the overall structure unless instructed otherwise. +NEVER write or . + +{prompt} about `; + +export const PROMPT_TEMPLATES = { + systemBlockSelecting, + systemDefault, + systemSelecting, + userBlockSelecting, + userDefault, + userSelecting, +}; + +const plugins = [ + // ...otherPlugins, + MarkdownPlugin.configure({ options: { indentList: true } }), + AIPlugin, + AIChatPlugin.configure({ + options: { + createAIEditor, + promptTemplate: ({ isBlockSelecting, isSelecting }) => { + return isBlockSelecting + ? PROMPT_TEMPLATES.userBlockSelecting + : isSelecting + ? PROMPT_TEMPLATES.userSelecting + : PROMPT_TEMPLATES.userDefault; + }, + systemTemplate: ({ isBlockSelecting, isSelecting }) => { + return isBlockSelecting + ? PROMPT_TEMPLATES.systemBlockSelecting + : isSelecting + ? PROMPT_TEMPLATES.systemSelecting + : PROMPT_TEMPLATES.systemDefault; + }, + }, + render: { afterEditable: () => }, + }), +]; +``` + +- [AIMenu](/docs/components/ai-menu) + +### AI SDK + +此插件依赖于 [ai](https://npmjs.com/package/ai) 包: + +- 使用 [streamText](https://sdk.vercel.ai/docs/ai-sdk-core/generating-text#streamtext) 设置一个[路由处理程序](https://sdk.vercel.ai/docs/getting-started/nextjs-app-router#create-a-route-handler)。 +- 在你的 [AI 菜单](/docs/components/ai-menu) 组件中连接 [useChat](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat)。 + +## 键盘快捷键 + + + + 在空白块中打开 AI 菜单（光标模式） + + + 打开 AI 菜单（光标或选择模式） + + 关闭 AI 菜单 + + +## 示例 + +### Plate UI + +参考上面的预览。 + +### Plate Plus + + + +## 插件 + +### AIPlugin + +使编辑器扩展 AI 转换功能。 + +### AIChatPlugin + +在编辑器中启用聊天操作和流式文本生成。 + + + + 由 [useChat](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat) 返回的聊天助手。 + + + + +创建预览模式编辑器实例的函数。 + +- **默认值：** 创建一个带有 id 'ai' 的基础编辑器 + + + + + +指定如何处理助手消息： + +- `'chat'`：显示带有接受/拒绝选项的预览（默认） +- `'insert'`：直接将内容插入编辑器 +- **默认值：** `'chat'` + + + + + +AI 聊天是否打开。 + +- **默认值：** `false` + + + + + +生成提示的模板。支持占位符： + +- `{block}`：选择中块的 Markdown +- `{editor}`：整个编辑器内容的 Markdown +- `{selection}`：当前选择的 Markdown +- `{prompt}`：实际用户提示 +- **默认值：** `'{prompt}'` + + + + + +系统消息的模板。支持与 `promptTemplate` 相同的占位符。 + +- **默认值：** `undefined` + + + + +## API + +### api.aiChat.accept() + +接受当前 AI 建议： + +- 从内容中移除 AI 标记 +- 隐藏 AI 聊天界面 +- 聚焦编辑器 + +### api.aiChat.insertBelow() + +在当前块下方插入 AI 内容。 + + + + 包含要插入内容的编辑器。 + + + +处理块选择和普通选择模式： + +- 在块选择中：在最后选择的块后插入 +- 在普通选择中：在当前块后插入 + +### api.aiChat.replaceSelection() + +用 AI 内容替换当前选择。 + + + + 包含要替换内容的编辑器。 + + + + + 当为 true 时，将第一个块的格式应用于所有插入的块。默认为 false。 + + + + + +处理不同的选择模式： + +- 单块选择：替换选中的块，将其格式应用于所有插入的内容 +- 多块选择：替换所有选中的块，除非启用 `forceUniformFormatting`，否则保留原始格式 +- 普通选择：替换当前选择，同时保持周围上下文 + +### api.aiChat.reset() + +重置聊天状态： + +- 停止任何正在进行的生成 +- 清除聊天消息 +- 从编辑器中移除所有 AI 节点 + +### api.aiChat.submit() + +提交提示以生成 AI 内容。 + + + + + + 要使用的模式。选择时默认为 'chat'，否则为 'insert'。 + + + 自定义提示。如果未提供则使用聊天输入。 + + + 自定义系统消息。 + + + + + +在插入模式下，在提交前撤销之前的 AI 更改。 + +## 转换 + +### tf.ai.insertNodes() + +插入带有 AI 标记的 AI 生成节点。 + + + + 要插入带有 AI 标记的节点。 + + + + + 目标路径。默认为当前选择。 + + + + + +### tf.ai.removeMarks() + +从指定位置的节点中移除 AI 标记。 + + + + + + 要移除标记的位置。默认为整个文档。 + + + + + +### tf.ai.removeNodes() + +移除带有 AI 标记的节点。 + + + + + + 要移除节点的路径。默认为整个文档。 + + + + + +### tf.ai.undo() + +AI 更改的特殊撤销操作： + +- 如果最后一个操作是 AI 生成的，则撤销它 +- 移除重做栈条目以防止重做 AI 操作 diff --git a/apps/www/content/docs/cn/alignment.mdx b/apps/www/content/docs/cn/alignment.mdx new file mode 100644 index 0000000000..1cceb2a4b4 --- /dev/null +++ b/apps/www/content/docs/cn/alignment.mdx @@ -0,0 +1,113 @@ +--- +title: Alignment +docs: + - route: /docs/components/align-dropdown-menu + title: Align Dropdown Menu +--- + + + + + +## Features + +- 提供文本对齐选项：左对齐、右对齐、居中对齐或两端对齐。 + + + +## 安装 + +```bash +npm install @udecode/plate-alignment +``` + +## Usage + +```tsx +// ... +import { createPlateEditor } from '@udecode/plate-common/react'; +import { AlignPlugin } from '@udecode/plate-alignment/react'; +import { ParagraphPlugin } from '@udecode/plate-common/react'; +import { HeadingPlugin } from '@udecode/plate-heading/react'; + +const editor = createPlateEditor({ + plugins: [ + HeadingPlugin, + AlignPlugin.configure({ + inject: { + targetPlugins: [ + ParagraphPlugin.key, + HeadingPlugin.key, + ], + }, + }), + ], +}); +``` + +## 插件 + +### AlignPlugin + +## API + +### setAlign + +设置指定块元素的对齐方式。 + + + +编辑器实例。 + + + + +对齐方式的值。 + + +`setNodes` 函数的选项。 + + + + + + +## API 组件 + +### useAlignDropdownMenuState + + + + 对齐方式的值。 + + + +### useAlignDropdownMenu + + + + 对齐方式的值。 + + + + + + 单选按钮组的属性。 + + + 对齐方式的值。 + + + 设置对齐方式值的回调函数。 + + + + diff --git a/apps/www/content/docs/cn/api/cn.mdx b/apps/www/content/docs/cn/api/cn.mdx new file mode 100644 index 0000000000..ac30dc97bc --- /dev/null +++ b/apps/www/content/docs/cn/api/cn.mdx @@ -0,0 +1,78 @@ +--- +title: cn +description: udecode/cn的 API 参考。 +--- + +`@udecode/cn` 包含用于 React 和 Tailwind 的实用函数。 + +### cn + +在不产生冲突的情况下有条件地添加 Tailwind CSS 类。 + + + + 使用 `clsx` 和 `tailwind-merge` 设置的类值。 + + + + +`className` 字符串。 + + + +### withCn + +为组件设置默认的 `className`。 + + + + 将要添加 props 的组件。 + + + 使用 `cn` 设置的默认 `className`。 + + + + +包含默认 `className` 的新组件。 + + + +### withProps + +为组件设置默认 props。 + + + + 将要添加 props 的组件。 + + + 要添加到组件的 props。 + + + + +包含默认 props 的新组件。 + + + +### withVariants + +使用 `class-variance-authority` 的变体为组件设置默认 `className`。 + + + + 将要添加 props 的组件。 + + + 作为默认 `className` 的变体。 + + + 从 `Component` 中排除的 props。设置仅用于变体的 props。 + + + + +包含默认 `className` 的新组件。 + + diff --git a/apps/www/content/docs/cn/api/common.mdx b/apps/www/content/docs/cn/api/common.mdx new file mode 100644 index 0000000000..d271b792e0 --- /dev/null +++ b/apps/www/content/docs/cn/api/common.mdx @@ -0,0 +1,11 @@ +--- +title: Plate Common +description: udecode/plate-common的 API 参考。 +--- + +`@udecode/plate-common` 包含 Plate 的常用类型和函数： + +- [Core](/docs/api/core) +- [Plate Utils](/docs/api/utils) +- [Slate](/docs/api/slate) +- [Slate React](/docs/api/slate-react) diff --git a/apps/www/content/docs/cn/api/core.mdx b/apps/www/content/docs/cn/api/core.mdx new file mode 100644 index 0000000000..1c497be31e --- /dev/null +++ b/apps/www/content/docs/cn/api/core.mdx @@ -0,0 +1,489 @@ +--- +title: Plate Core +description: udecode/plate-core的 API 参考。 +--- + +## API + +### createPlateEditor + +生成一个新的 `PlateEditor` 实例，使用一组插件及其配置进行初始化。 + + + + 创建 Plate 编辑器的选项。 + + + 编辑器的唯一标识符。 + + + 不带 `withPlate` 的初始编辑器。 + + + 编辑器插件数组。 + + + 编辑器的初始值。 + + + 初始化后选择编辑器。 + - **默认值：** `false` + - `true` | 'end'：选择编辑器末尾 + - `false`：不选择任何内容 + - `'start'`：选择编辑器开头 + + + 指定编辑器允许的最大字符数。 + + + 编辑器的初始选择。 + + + 当为 `true` 时，将规范化传递给 `editor` 的初始 `value`。 + - **默认值：** `false` + + + 配置根插件的函数。 + + + 编辑器的 API 方法。 + + + 编辑器的装饰函数。 + + + 扩展编辑器的函数。 + + + 编辑器的事件处理程序。 + + + 编辑器的注入配置。 + + + 规范化初始值的函数。 + + + 编辑器的其他选项。 + + + 编辑器的覆盖配置。 + + + 编辑器插件的优先级。 + + + 编辑器的渲染函数。 + + + 编辑器的键盘快捷键。 + + + 编辑器的转换函数。 + + + 与编辑器一起使用的钩子。 + + + + + + + 应用了指定插件和设置的 `PlateEditor` 实例。 + + +有关编辑器配置的更多详细信息，请参阅[编辑器配置](/docs/editor)指南。 + +### createPlatePlugin + +使用给定的配置创建一个新的 Plate 插件，支持扩展、嵌套插件操作和运行时配置。 + + + + 插件的配置对象，或返回配置的函数。如果提供函数，它将在插件与编辑器一起解析时执行。 + + 有关 `PlatePluginConfig` 类型的详细信息，请参阅 [PlatePlugin API](/docs/api/core/plate-plugin#plugin-properties)。 + + + + + 一个新的 `PlatePlugin>` 实例。 + + +### createTPlatePlugin + +`createPlatePlugin` 的显式类型版本。 + + + + 插件的配置对象，或返回配置的函数。此版本需要一个显式类型参数 `C` 扩展 `AnyPluginConfig`。 + + 有关 `TPlatePluginConfig` 类型的详细信息，请参阅 [PlatePlugin API](/docs/api/core/plate-plugin#plugin-properties)。 + + + + + 一个新的 `PlatePlugin` 实例。 + + +### toPlatePlugin + +扩展 SlatePlugin 以创建 React PlatePlugin。 + + + + 要扩展的基础 SlatePlugin。 + + + 提供扩展配置的函数或对象。如果是函数，它接收插件上下文并应返回部分 PlatePlugin。如果是对象，它应该是部分 PlatePlugin 配置。 + + + + + 一个新的 `PlatePlugin`，它结合了基础 SlatePlugin 功能和扩展配置中定义的 React 特定功能。 + + +### toTPlatePlugin + +`toPlatePlugin` 的显式类型版本。 + + + + 要扩展的基础 SlatePlugin。 + + + 提供扩展配置的函数或对象。此版本需要基础插件配置（`TContext`）和扩展配置（`C`）的显式类型参数。 + + + + + 具有精确类型控制的新 `PlatePlugin`。 + + +### useEditorContainerRef + +获取编辑器容器的 DOM 引用。 + +### useEditorScrollRef + +获取编辑器滚动容器的引用。 + +### useScrollRef + +获取编辑器滚动容器的引用。如果存在滚动引用则返回滚动引用，否则返回容器引用。 + +### useEditorPlugin + +获取编辑器和插件上下文。 + + + + 具有必需键的插件或插件配置。 + + + + + 包含以下内容的 `PlatePluginContext` 对象： + + + 当前编辑器实例。 + + + 插件实例。 + + + 获取特定选项值的函数。 + + + 获取插件所有选项的函数。 + + + 设置特定选项值的函数。 + + + 设置多个选项的函数。 + + + 在 React 组件中订阅特定选项值的钩子。 + + + + +### useEditorRef + +获取 Slate 编辑器引用而不重新渲染。 + + + + plate 编辑器的 ID。仅在嵌套编辑器时有用。默认使用最近的编辑器 id。 + + + + 一个 `PlateEditor` 对象，即 Slate 编辑器。 + + +### useEditorSelector + +订阅编辑器的特定属性。 + + + + 选择器函数。 + + + 选择器函数的依赖列表。 + + + + + plate 编辑器的 ID。仅在嵌套编辑器时有用。默认使用最近的编辑器 id。 + + + 用于确定选择器函数的结果是否已更改的相等函数。默认为 `(a, b) => a === b`。 + + + + + + 选择器函数的返回值。 + + +### useEditorState + +获取带重新渲染的 Slate 编辑器引用。 + + + + plate 编辑器的 ID。默认使用最近的编辑器 id。 + + + + 一个 `PlateEditor` 对象，即 Slate 编辑器。 + + +### useEditorReadOnly + +获取编辑器的 `readOnly` 状态。 + + + + plate 编辑器的 ID。 + + + + 编辑器的 `readOnly` 状态。 + + +### useEditorMounted + +获取编辑器的 `isMounted` 状态。 + + + + plate 编辑器的 ID。 + + + + 编辑器的 `isMounted` 状态。 + + +### useEditorSelection + +获取编辑器的选择。已记忆化，因此如果范围相同则不会重新渲染。 + + + + plate 编辑器的 ID。 + + +编辑器中的当前选择。 + +### useEditorVersion + +获取编辑器值的版本。该版本在每次编辑器更改时递增。 + + + + plate 编辑器的 ID。 + + +编辑器值的当前版本。 + +### useSelectionVersion + +获取编辑器选择的版本。该版本在每次选择更改时递增（范围不同）。 + + + + plate 编辑器的 ID。 + + +编辑器选择的当前版本。 + +### useSelectionCollapsed + +返回当前选择是否已折叠（即选择是单个点）。 + + + 一个布尔值，指示选择是否已折叠。 + + +### useSelectionExpanded + +返回当前选择是否已展开（即选择有非零范围）。 + + + 一个布尔值，指示选择是否已展开。 + + +### useSelectionWithinBlock + +返回当前选择是否在单个块内。 + + + 一个布尔值，指示选择是否在单个块内。 + + +### useSelectionAcrossBlocks + +返回当前选择是否跨越多个块。 + + + 一个布尔值，指示选择是否跨越多个块。 + + +### useSelectionFragment + +返回当前选择的片段，可选择解包结构节点。 + + + + 获取选择片段的选项。 + + + 要从片段中解包的结构类型数组。 + + + + + + + 表示当前选择片段的 `TElement` 数组。如果选择未展开或未找到片段，则返回空数组。 + + +### useSelectionFragmentProp + +返回从当前选择片段派生的属性值。 + + + + + + 要从片段中解包的结构类型数组。 + + + 要从每个节点提取的属性键。 + + + 如果未找到有效属性时返回的默认值。 + + + 从节点提取属性值的自定义函数。 + + + 确定如何遍历片段： + - 'all'：检查块节点和文本节点 + - 'block'：仅检查块节点 + - 'text'：仅检查文本节点 + 默认为 'block'。 + + + + + + + 从片段节点派生的值，如果在指定节点中未找到一致的值，则为 undefined。 + + +### useNodePath + +返回编辑器中节点的路径。 + + + + 要查找路径的节点。 + + + + + 表示节点在编辑器树结构中位置的记忆化 Path 数组。 + + +### usePath + +获取最近元素的记忆化路径。 + + + + 要获取路径的插件的键。 + + + + + 元素的路径，如果在节点组件上下文之外使用则为 `undefined`。 + + +### useElement + +通过插件键获取元素。 + + + + 要获取元素的插件的键。 + - **默认值：** `'element'` + + + + + 类型为 `T extends TElement` 的元素，如果在节点组件上下文之外使用则为空对象。 + + +## 核心插件 + +### DebugPlugin +提供具有可配置日志级别和错误处理的调试功能。 + +有关更多详细信息，请参阅[调试](/docs/debugging)。 + +### SlateNextPlugin +扩展核心 API 并改进默认功能。 + +### DOMPlugin & ReactPlugin +将 React 特定功能集成到编辑器中。 + +### HistoryPlugin +为编辑器启用撤销和重做功能。 + +### InlineVoidPlugin +管理编辑器中的内联和空元素。 + +### ParserPlugin +处理编辑器的内容解析。 + +### LengthPlugin +强制执行编辑器内容的最大长度。 + +### HtmlPlugin +启用 HTML 序列化和反序列化。 + +### AstPlugin +处理编辑器的抽象语法树（AST）操作。 + +### ParagraphPlugin +提供段落格式化功能。 + +### EventEditorPlugin +管理编辑器事件，如焦点和模糊。 + +### PlateApiPlugin +提供 Plate 编辑器功能的核心 API。 diff --git a/apps/www/content/docs/cn/api/core/plate-controller.mdx b/apps/www/content/docs/cn/api/core/plate-controller.mdx new file mode 100644 index 0000000000..f4f7bca908 --- /dev/null +++ b/apps/www/content/docs/cn/api/core/plate-controller.mdx @@ -0,0 +1,172 @@ +--- +title: PlateController +description: PlateController 组件的 API 参考。 +--- + +**`PlateController`** 是一个可选的 provider 组件，它可以让你从各自的 **`Plate`** 组件外部访问特定的 [Plate Stores](/docs/api/core/store)。 + +## PlateController Store + +### State + +PlateController Store 包含了根据 **`id`** 获取 Plate Store 所需的信息，以及确定当前哪个 **`id`** 处于活动状态。 + + + + +最近获得焦点的 Plate 编辑器的 **`id`**。 + +- **默认值:** `null` + + + + +所有主要 Plate 编辑器的 **`id`**。默认情况下，除非在 **`Plate`** 组件中传入 **`primary={false}`**，否则编辑器被视为主要编辑器。 + +- **默认值:** `[]` + + + + +从每个已挂载的 Plate 编辑器的 **`id`** 到对应该编辑器的 Plate Store 的 **`JotaiStore`** 的映射。 + +- **默认值:** `{}` + + + + +## 使用模式 + +### 通过 ID 访问特定编辑器 + +**`PlateController`** 可以用来通过 **`id`** 访问特定编辑器的 store。注意，如果找不到匹配的编辑器，将返回一个不可变的后备编辑器。 + +```tsx +const App = withHoc(PlateController, () => { + const mainEditor = useEditorRef('main'); + + useEffect(() => { + if (!mainEditor.isFallback) { + console.info('Editor mounted', mainEditor); + } + }, [mainEditor]); + + return ( + <> + + + + + + + + + ); +}); +``` + +### 当前活跃的编辑器 + +如果像 **`useEditorRef`** 这样的钩子在 **`PlateController`** 内部使用，但没有显式传入 **`id`**，它们将解析为当前活动的编辑器。 + +当前活动的编辑器确定如下： + +1. 如果某个编辑器已获得焦点，则返回最后一个这样的编辑器。 +2. 如果某个编辑器是主要编辑器，则返回第一个挂载的这样的编辑器。 +3. 否则，返回一个不可变的后备编辑器。 + +```tsx +const App = withHoc(PlateController, () => { + const activeEditorId = useEditorId(); + const isFallback = !useEditorMounted(); + + const message = isFallback + ? 'Please focus an editor' + : `Active editor: ${activeEditorId}`; + + return ( +
+

{message}

+ + + + + + + + +
+ ); +}); +``` + +## 处理后备编辑器 + +当一个钩子在 **`PlateController`** 内部调用时，如果无法找到匹配的 Plate Store，它将使用 Plate Store 的默认值。**`editor`** 的默认值是 **`createPlateFallbackEditor()`**。后备编辑器就像一个没有插件的空 Plate 编辑器，除了它会在收到 Slate 操作时抛出运行时错误（即它是不可变的，不能在变换中使用）。 + +这样做的原因是确保查询编辑器（例如确定工具栏按钮是否处于活动状态）的代码在失败时使用一个合理的默认值，而变换编辑器（例如按下工具栏按钮）的代码在失败时抛出错误。 + +有两种方法可以确定你正在处理后备编辑器还是真实编辑器： + +- **`useEditorMounted`** 返回 **`false`** 如果无法解析任何挂载的编辑器 +- **`editor.isFallback`** 对于后备编辑器返回 **`true`** + +当在 **`PlateController`** 内部使用像 **`useEditorRef`** 这样的钩子时，你应该采取防御性措施，以确保在出现后备编辑器时适当处理它们。例如，如果 **`useEditorMounted`** 返回 **`false`**，你可以禁用工具栏按钮，或者如果 **`editor.isFallback`** 是 **`true`**，你可以忽略事件。 + +```tsx +const App = withHoc(PlateController, () => { + const activeEditor = useEditorRef(); + + const toggleBold = () => { + if (activeEditor.isFallback) return; + toggleMark(activeEditor, { key: BoldPlugin.key }); + }; + + return ( +
+ + + + + + + + + +
+ ); +}); +``` + +```tsx +const App = withHoc(PlateController, () => { + const activeEditor = useEditorRef(); + const isFallback = !useEditorMounted(); + + const toggleBold = () => { + toggleMark(activeEditor, { key: BoldPlugin.key }); + }; + + return ( +
+ + + + + + + + + +
+ ); +}); +``` \ No newline at end of file diff --git a/apps/www/content/docs/cn/api/core/plate-editor.mdx b/apps/www/content/docs/cn/api/core/plate-editor.mdx new file mode 100644 index 0000000000..8da411f401 --- /dev/null +++ b/apps/www/content/docs/cn/api/core/plate-editor.mdx @@ -0,0 +1,150 @@ +--- +title: Plate Editor +description: Plate 编辑器的 API 参考。 +--- + +一个自定义的编辑器接口，扩展了基础的 **`TEditor`** 接口，并包含 Plate 库特有的属性和方法。 + +## Core Properties + + + + 编辑器的唯一标识符。 + + + 可以用来唯一标识编辑器的键。 + + + 当前正在处理的键盘事件，如果没有事件正在处理，则为 null。 + + + 是否是后备编辑器。 + + - **Default:** `false` + + + 编辑器中的上一个选择范围。 + + + 当前正在使用的插件列表。 + + + 一个插件键值对的记录。 + + + +## API Methods + + + + 获取插件的类型化 API。 + + + 获取插件的类型化变换。 + + + 通过键或基础插件获取编辑器插件实例。 + + + 获取插件的节点类型。 + + + +## Option Methods + + + + 获取插件的特定选项值。 + + + 获取插件的所有选项。 + + + 设置插件的特定选项值。 + + + 设置插件的多个选项。 + + + 获取插件的 zustand-x 选项存储。 + + + +## React Hooks + + + + 在 React 组件中订阅特定选项值。 + + + 在 React 组件中订阅插件选项或派生自选项的值。 + + + +## Plate Store Methods + + + + 更新全局 Plate 状态。 + + + +## Core Plugin APIs + +### DebugPlugin + + + + 在 'log' 级别打印一条消息。 + + + 在 'info' 级别打印一条消息。 + + + 在 'warn' 级别打印一条消息。 + + + 在 'error' 级别打印一条消息。 + + + +### SlateNextPlugin + + + + 切换一个块元素。 + + + 切换选中文本上的标记。 + + + +### HtmlPlugin + + + + 将 HTML 内容反序列化为 Slate 节点。 + + + +### ReactPlugin + + + + 重置编辑器状态，同时保持焦点（如果编辑器已聚焦）。 + + + +### PlateApiPlugin + + + + 重新装饰编辑器。此方法应被覆盖以确保正常功能。 + + + + + + 替换编辑器值。更多信息请参阅 [Controlled Value](/docs/controlled)。 + + diff --git a/apps/www/content/docs/cn/api/core/plate-plugin.mdx b/apps/www/content/docs/cn/api/core/plate-plugin.mdx new file mode 100644 index 0000000000..7aa97ac609 --- /dev/null +++ b/apps/www/content/docs/cn/api/core/plate-plugin.mdx @@ -0,0 +1,333 @@ +--- +title: PlatePlugin +description: Plate 插件的 API 参考。 +--- + +Plate 插件是传递给 `Plate` [plugins](/docs/api/core/plate#plugins) 属性的对象。 + +## 泛型类型 + +`PlatePlugin` 接口使用一个泛型类型： + + + +表示插件配置。此类型扩展了 `PluginConfig`，包括 `key`, `options`, `api`, 和 `transforms`。 + + + +示例： + +```typescript +type MyPluginConfig = PluginConfig< + 'myPlugin', + { customOption: boolean }, + { getData: () => string }, + { customTransform: () => void } +>; + +const MyPlugin = createPlatePlugin({ + key: 'myPlugin', + // plugin implementation +}); +``` + +## Plugin Properties + + + + +Plate 用于存储插件的唯一标识符，通过 `editor.plugins` 键。 + + + +插件提供的 API 函数对象。这些函数通过 `editor.api[key]` 访问。 + + + +插件提供的变换函数，用于修改编辑器状态。这些函数通过 `editor.tf[key]` 访问。 + + + +插件作为选项使用的扩展属性。 + + + +各种编辑器事件的事件处理程序，包括 `onChange`。 + + + +定义插件如何将功能注入其他插件或编辑器。 + + + +Plate 用于将属性注入任何节点组件的属性。 + + + + +要排除的插件键数组。 + + + +要排除的插件键数组。节点属性注入将排除任何这些插件类型的元素的后代节点。 + + +如果为 true，则仅匹配块元素。用于将属性注入块级节点。 + + + +如果为 true，则仅匹配元素节点。用于将属性注入元素节点。 + + +如果为 true，则仅匹配叶子节点。用于将属性注入叶子节点。 + + +节点属性注入的最大嵌套级别。深度大于此级别的节点将不会接收注入的属性。 + + +插件可以使用的属性，用于允许其他插件注入代码。 + + +返回一个插件配置，以注入到其他插件 `inject.plugins` 中指定的目标插件。 + + +`InjectNodeProps` 和 `targetPluginToInject` 函数使用的插件键。 + +- **Default:** `[ParagraphPlugin.key]` + + + + + +定义插件的节点特定配置。 + + + +指示此插件的节点是否应该被渲染为元素。 + + +指示此插件的元素是否应该被视为内联元素。 + + +指示此插件的节点是否应该被渲染为叶子节点。 + + +指示此插件的元素是否应该被视为空元素。 + + +指示此插件的空元素是否可以被标记。 + + +指定此插件节点的类型标识符。 + +- **默认值:** `plugin.key` + + +用于渲染此插件节点的 React 组件。 + + +要传递给节点组件的额外属性。 + + + + + +允许通过键覆盖组件和插件。 + + + +通过键替换插件的 `NodeComponent`。 + + +通过键扩展 `PlatePlugin`。 + + +启用或禁用插件。 + + + + + +定义插件如何解析内容。 + + + +定义各种格式的序列化器和反序列化器。 + + + +HTML 解析器配置。 + + +HTML React 序列化器配置。 + + + + + +定义编辑器各个部分的渲染函数。 + + + +在 `Editable` 组件上方但在 `Slate` 包装器内渲染组件。 + + +在所有其他插件的 `node` 组件上方渲染组件。 + + +在 `Slate` 包装器上方渲染组件。 + + +在 `Editable` 组件后渲染组件。 + + +在 `Editable` 组件前渲染组件。 + + +在所有其他插件的 `node` 组件下方但在其 `children` 上方渲染组件。 + + +渲染节点组件。 + + + + + +定义插件的键盘快捷键。 + + + +用于管理插件选项的存储。 + + + +此插件依赖的插件键数组。 + + + +启用或禁用插件。由 Plate 用来确定是否应该使用该插件。 + + + +递归插件支持，允许在单个插件中包含多个插件。 + + + +定义插件注册和执行的顺序。 + +- **默认值:** `100` + + + +Plate 用来装饰编辑器范围的属性。 + + + +Hook called when the editor is initialized. + + + +## Plugin Methods + + + +创建一个具有更新选项的新插件实例。 + +```ts +(config: PlatePluginConfig, InferApi, InferTransforms> | ((ctx: PlatePluginContext) => PlatePluginConfig, InferApi, InferTransforms>)) => PlatePlugin +``` + + + +创建一个具有附加配置的新插件实例。可以接受一个对象或一个函数。 + +```ts +(extendConfig: Partial | ((ctx: PlatePluginContext) => Partial)) => PlatePlugin +``` + + +扩展一个现有的嵌套插件或添加一个新的插件，如果未找到。支持深度嵌套。 + +```ts +(key: string, extendConfig: Partial | ((ctx: PlatePluginContext) => Partial)) => PlatePlugin +``` + + + +设置或替换与插件关联的组件。 + +```ts +(component: NodeComponent) => PlatePlugin +``` + + + +扩展插件的 API。 + +```ts +(api: (ctx: PlatePluginContext) => any) => PlatePlugin +``` + + + +使用插件特定的方法扩展编辑器的 API。 + +```ts +(api: (ctx: PlatePluginContext) => any) => PlatePlugin +``` + + + +使用插件特定的方法扩展插件的变换。 + +```ts +(transforms: (ctx: PlatePluginContext) => any) => PlatePlugin +``` + + + +使用插件特定的方法扩展编辑器的变换。 + +```ts +(transforms: (ctx: PlatePluginContext) => any) => PlatePlugin +``` + + + +使用选择器扩展插件选项。 + +```ts +(options: (ctx: PlatePluginContext) => any) => PlatePlugin +``` + + + +## Plugin Context + +大多数插件函数将 `PlatePluginContext` 对象作为其第一个参数。这个对象包括： + + + +当前编辑器实例。 + + +当前插件实例。 + + +获取特定选项值的函数。 + + +获取插件所有选项的函数。 + + +设置特定选项值的函数。 + + +设置多个选项的函数。 + + +订阅特定选项值的 React 组件的钩子。 + + + +有关 Plate 插件的更多详细信息，请参阅各个指南：[Plugin Configuration](/docs/plugin), [Plugin Methods](/docs/plugin-methods), [Plugin Context](/docs/plugin-context), [Plugin Components](/docs/plugin-components), 以及 [Plugin Shortcuts](/docs/plugin-shortcuts). \ No newline at end of file diff --git a/apps/www/content/docs/cn/api/core/plate.mdx b/apps/www/content/docs/cn/api/core/plate.mdx new file mode 100644 index 0000000000..28516f8809 --- /dev/null +++ b/apps/www/content/docs/cn/api/core/plate.mdx @@ -0,0 +1,86 @@ +--- +title: Plate +description: Plate 组件的 API 参考。 +--- + +`Plate` 是将编辑器状态加载到 store provider 中的根组件。 + +`PlateContent` 是渲染编辑器的组件。 + +## Plate Props + + + +子组件可以访问 plate store。 + + +一个受控的 `editor` 实例。这个属性是必需的。 + + +参见 [Slate 文档](https://docs.slatejs.org/concepts/09-rendering#decorations)。 + + +当编辑器状态改变时调用的受控回调。 + + +当编辑器选择改变时调用的回调。 + + +当编辑器值改变时调用的回调。 + + +控制在与 PlateController 一起使用时编辑器是否默认被视为活动状态。 + +- **Default:** `true` + + +如果为 true，编辑器处于只读模式。 + + +元素的自定义渲染函数。 + + +叶子节点的自定义渲染函数。 + + + +## PlateContent Props + +[Editable](https://docs.slatejs.org/libraries/slate-react/editable) 组件的属性。扩展自 `TextareaHTMLAttributes`。 + + + +当编辑器从只读模式转换为可编辑模式时（当 `readOnly` 从 `true` 变为 `false` 时）自动聚焦编辑器。 + + +自定义 `Editable` 节点。 + +- **Default:** `` + + + + + + + + + + + + + + + + + +## Plate 的工作原理 + +`Plate` 需要一个 `editor` 属性，它应该是 `PlateEditor` 的实例。如果 `editor` 为 `null`，`Plate` 将不会渲染任何内容。 + +`Plate` 组件不处理编辑器的创建或插件的管理。这些责任由 `createPlateEditor` 处理。 + +`Plate` 为编辑器状态提供一个 store 并渲染其子组件。它使用 `PlateStoreProvider` 使编辑器状态和相关函数对其子组件可用。 + +元素和叶子的渲染逻辑主要由插件系统处理，如果没有找到特定节点类型的插件，则使用 `renderElement` 和 `renderLeaf` 属性作为后备。 + +有关创建和配置编辑器的更多详细信息，请参阅[编辑器配置](/docs/editor)指南。 \ No newline at end of file diff --git a/apps/www/content/docs/cn/api/core/store.mdx b/apps/www/content/docs/cn/api/core/store.mdx new file mode 100644 index 0000000000..4391dd495f --- /dev/null +++ b/apps/www/content/docs/cn/api/core/store.mdx @@ -0,0 +1,188 @@ +--- +title: Store +description: Plate store 的 API 参考。 +--- + +`Plate` 使用 [jotai](https://github.com/pmndrs/jotai) 来存储编辑器的状态。 + + + **注意**：要在组件中使用 store hooks，需要在 `Plate` 内部渲染该组件。 + + +## Plate Store + +### Store + +PlateStoreState 对象存储 Plate 编辑器的状态。它包含有关编辑器 ID、当前值、插件和其他设置的信息。 + + + +Slate 编辑器引用。 + +- **Default:** `createPlateFallbackEditor()` + + + +一个用作提供者作用域的唯一 ID。如果在同一个 React 树中有多个 `Plate`，则需要使用它。 + +- **Default:** random id + + + +编辑器容器元素的引用。 + + + +用于装饰编辑器中范围的函数。 + +```ts +(options: { editor: PlateEditor; entry: TNodeEntry }) => Range[] +``` + + + +`Editable` 是否已渲染，以便 slate DOM 可解析。 + + + +用于控制回调，当编辑器状态发生变化时调用。 + +```ts +(options: { editor: PlateEditor; value: ValueOf }) => void +``` + + + +用于控制回调，当 editor.selection 发生变化时调用。 + +```ts +(options: { editor: PlateEditor; selection: TSelection }) => void +``` + + + +用于控制回调，当 editor.children 发生变化时调用。 + +```ts +(options: { editor: PlateEditor; value: ValueOf }) => void +``` + + + +Whether the editor is primary. If no editor is active, then PlateController will use the first-mounted primary editor. + +- **Default:** `true` + + + +编辑器是否为只读。 + + + +在编辑器中渲染元素的函数。 + + + +在编辑器中渲染叶节点的函数。 + + + +调用 `redecorate` 时递增的版本号。这是 `decorate` 函数的一个依赖项。 + + + +每次编辑器更改时递增的版本号。 + + + +每次编辑器.selection 更改时递增的版本号。 + + + +每次编辑器.children 更改时递增的版本号。 + + + +## Exposed Store Keys + +以下存储键在 `editor.setPlateState` 中被暴露： + +- `readOnly` +- `onChange` +- `decorate` +- `renderElement` +- `renderLeaf` + +## Selectors + +当你需要订阅一个值时，使用 `usePlateSelectors(id).()`。 + +- **示例：** `const value = usePlateSelectors(id).value()` 将订阅 `value` 的变化。 +- 它在底层使用 [useAtomValue](https://jotai.org/docs/utils/use-atom-value)。 + +## Actions + +当你需要一个存储属性的值和设置器时，使用 `usePlateStates(id).()`。 + +- **示例：** `const [value, setValue] = usePlateStates(id).value()` +- 它在底层使用 [useAtom](https://jotai.org/docs/basics/primitives#use-atom)。 + +### `useRedecorate` + +重新装饰编辑器。 + + + + 编辑器 ID。 + + + +## Event Editor Store + +此存储是一个对象，其属性键是事件名称（例如 `'focus'`），属性值是 [editor IDs](Plate#id)。 + +- 当有[多个编辑器](multiple-editors)时，这很有用，可以基于 DOM 事件获取一个（例如最后一个聚焦的编辑器）。 +- [Plate](Plate) 的一个核心插件将存储以下事件。 + +### State + + + + +最后一个失去焦点的编辑器 ID。 + + + + + +当前聚焦的编辑器 ID。 + + + + + +最后一个编辑器 ID。 + + + +### `useEventEditorSelectors` + +钩子选择器。 + +- **Example:** `useEventEditorSelectors().focus()` 将获取最后一个聚焦的编辑器 ID。 + +### `useEventPlateId` + +获取最后一个事件编辑器 ID。 + + + + +如果定义，返回的 ID。 + + + + + + 如果可用，从上下文中获取 plate id，否则获取最后一个事件编辑器 ID 或 `PLATE_SCOPE`。 + diff --git a/apps/www/content/docs/cn/api/floating.mdx b/apps/www/content/docs/cn/api/floating.mdx new file mode 100644 index 0000000000..f26f2a2b5c --- /dev/null +++ b/apps/www/content/docs/cn/api/floating.mdx @@ -0,0 +1,164 @@ +--- +title: Floating +description: 浮动 UI 组件和钩子的 API 参考。 +--- + + + +## 特性 + +- 跟随光标位置的虚拟浮动元素 +- 在文本选择时出现的浮动工具栏 +- 基于 Floating UI 构建 +- 可自定义的定位和行为 +- 在滚动和调整大小时自动更新 + + + +## 安装 + +```bash +npm install @udecode/plate-floating +``` + +## API Hooks + +### useVirtualFloating + +创建一个带有受控虚拟元素的浮动元素，通常用于跟随光标位置。 + + + + 虚拟浮动元素的选项。 + + + 获取边界客户端矩形的函数。 + - **默认值:** 返回一个零大小的矩形，位于 (0,0) + + + 控制浮动元素的可见性。 + + + 元素挂载时的回调函数。 + - **默认值:** `autoUpdate` (在滚动和调整大小时更新) + + + + + + + + 应用于浮动元素的样式对象。 + + + 虚拟元素的引用。 + + + 用于浮动 UI 定位的引用。 + + + 手动更新定位的函数。 + + + +### useFloatingToolbar + +创建一个浮动工具栏，当在编辑器中选择文本时出现。 + + + + 浮动工具栏的状态选项。 + + + 传递给 useVirtualFloating 的选项。 + + + 强制隐藏工具栏。 + + + 在只读模式下显示工具栏。 + + + + + + + + 用于检测工具栏外部点击的引用。 + + + 工具栏是否应该隐藏。 + + + 要传递给工具栏元素的属性。 + + + 要附加到工具栏元素的引用。 + + + +## API + +### getBoundingClientRect + +获取编辑器中位置或位置数组的边界客户端矩形。 + + + + 编辑器实例。 + + + 要获取边界矩形的位置。如果未提供，则使用当前编辑器选择。 + + + + + + 所有指定位置的合并边界客户端矩形，如果未找到有效矩形则为 undefined。 + + + +### getDOMSelectionBoundingClientRect + +获取当前 DOM 选择的边界客户端矩形。 + + + + DOM 选择的边界客户端矩形。如果不存在选择，则返回位于 (0,0) 的零大小矩形。 + + + +### getRangeBoundingClientRect + +获取特定 Slate 范围的边界客户端矩形。 + + + + 编辑器实例。 + + + 要获取边界矩形的 Slate 范围。 + + + + + + 范围的边界客户端矩形。如果范围为 null 或无效，则返回位于 (0,0) 的零大小矩形。 + + + +### getSelectionBoundingClientRect + +获取当前编辑器选择的边界客户端矩形。 + + + + 编辑器实例。 + + + + + + 选择的边界客户端矩形。如果选择未展开，则返回位于 (0,0) 的零大小矩形。 + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/api/react-utils.mdx b/apps/www/content/docs/cn/api/react-utils.mdx new file mode 100644 index 0000000000..59bcbb3357 --- /dev/null +++ b/apps/www/content/docs/cn/api/react-utils.mdx @@ -0,0 +1,81 @@ +--- +title: React Utils +description: udecode/react-utils的 API 参考。 +--- + +`@udecode/react-utils` 包含用于 React 的实用函数。 + +### PortalBody + +使用 portal 在 `document.body` 中渲染 React 组件。 + +### Text + +用于渲染 span 的通用组件。 + +### Box + +用于渲染 div 的通用组件。 + +### createPrimitiveComponent + +创建一个原始组件工厂，它使用钩子来管理状态、props，并将引用转发到子组件。 + + + + 基础组件或原生 HTML 元素。 + + + + 返回一个带有状态和 props 管理钩子的原始组件的函数。 + + +### createPrimitiveElement + +从元素类型创建组件。 + + + + 原生 HTML 元素。 + + + + 渲染指定元素的函数组件。 + + +### createSlotComponent + +创建一个 Slot 组件，当你想要一个组件表现得像它的子组件时很有用。 + + + + 基础组件或原生 HTML 元素。 + + + + +返回一个 Slot 组件的函数。 + + + +### withProviders + +将组件包装到多个 providers 中的函数。 + + + +用于包装组件的 providers。 + +如果你想让 provider 接收任何 props，你可以简单地传递一个数组。 + + + +要被包装的组件。 + + +要传递给被包装组件的 props。 + + + +一个被指定 providers 包装的新组件。 + diff --git a/apps/www/content/docs/cn/api/resizable.mdx b/apps/www/content/docs/cn/api/resizable.mdx new file mode 100644 index 0000000000..78aa22cf05 --- /dev/null +++ b/apps/www/content/docs/cn/api/resizable.mdx @@ -0,0 +1,206 @@ +--- +title: Resizable +--- + + + +## 特性 + +- 带有手柄的可调整大小的元素 +- 可配置的最小/最大宽度约束 +- 支持居中/左/右对齐 +- 在编辑器状态中保持宽度 + + + +## 安装 + +```bash +npm install @udecode/plate-resizable +``` + +## API + +### useResizableState + +管理可调整大小元素的状态。 + + + + + + 节点对齐方式。 + - **默认值：** `'center'` + + + 最大宽度约束。 + - **默认值：** `'100%'` + + + 最小宽度约束。 + - **默认值：** `92` + + + 元素在只读模式下是否可调整大小。 + + + + + + + + 当前对齐设置。 + + + 最大宽度约束。 + + + 最小宽度约束。 + + + 在编辑器状态中更新节点宽度。 + + + 在本地状态中更新宽度。 + + + 当前宽度值。 + + + +### useResizable + +为可调整大小的元素提供调整大小行为的 props 和处理程序。 + + + + 来自 useResizableState 的状态。 + + + + + + + + 调整大小事件的处理程序。 + + + + + 可调整大小元素的样式属性： + - maxWidth: 最大宽度约束 + - minWidth: 最小宽度约束 + - position: 'relative' + - width: 当前宽度 + + + 包装器元素的样式属性： + - position: 'relative' + + + 包装器元素的引用。 + + + +### useResizeHandleState + +管理调整大小手柄元素的状态。 + + + + + + 调整大小的方向。 + - **默认值：** `'left'` + + + 可调整大小元素的初始大小。 + + + 手柄悬停时的回调。 + + + 手柄悬停结束时的回调。 + + + 自定义鼠标按下处理程序。 + + + 自定义调整大小处理程序。如果未提供，则回退到存储处理程序。 + + + 自定义触摸开始处理程序。 + + + + + + + + 当前调整大小的方向。 + + + 初始光标/触摸位置。 + + + 元素的初始大小。 + + + 调整大小的方向是否为水平。 + + + 是否正在调整大小。 + + + 编辑器只读状态。 + + + 更新初始位置。 + + + 更新初始大小。 + + + 更新调整大小状态。 + + + 悬停回调。 + + + 悬停结束回调。 + + + 鼠标按下处理程序。 + + + 调整大小处理程序。 + + + 触摸开始处理程序。 + + + +### useResizeHandle + +为调整大小的句柄元素提供处理程序和 props。 + + + + 来自 useResizeHandleState 的状态。 + + + + + + 句柄是否应该隐藏（在只读模式下）。 + + + 要传递给句柄元素的 props： + - onMouseDown: 鼠标按下事件处理程序 + - onMouseOut: 鼠标移出事件处理程序 + - onMouseOver: 鼠标悬停事件处理程序 + - onTouchEnd: 触摸结束事件处理程序 + - onTouchMove: 触摸移动事件处理程序 + - onTouchStart: 触摸开始事件处理程序 + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/api/slate-react.mdx b/apps/www/content/docs/cn/api/slate-react.mdx new file mode 100644 index 0000000000..3cc11abbaf --- /dev/null +++ b/apps/www/content/docs/cn/api/slate-react.mdx @@ -0,0 +1,101 @@ +--- +title: Slate React +description: udecode/slate-react的 API 参考。 +--- + +`@udecode/slate-react` 使用泛型类型扩展了 Slate React API。 + +## React Editor + +在 [Slate React 文档](https://docs.slatejs.org/libraries/slate-react/react-editor) 中查找相应的文档。 + +### `SlateProps` + +### `blurEditor` + +### `deselectEditor` + +### `findEditorDocumentOrShadowRoot` + +### `findEventRange` + +### `findNodeKey` + +### `findPath` + +### `focusEditor` + +### `getEditorWindow` + +### `hasEditorDOMNode` + +### `hasEditorEditableTarget` + +### `hasEditorSelectableTarget` + +### `hasEditorTarget` + +### `insertData` + +### `isComposing` + +### `isEditorFocused` + +### `isEditorReadOnly` + +### `isTargetInsideNonReadonlyVoidEditor` + +### `setFragmentData` + +### `toDOMNode` + +### `toDOMPoint` + +### `toDOMRange` + +### `toSlateNode` + +### `toSlatePoint` + +### `toSlateRange` + +## Transforms + +### focusEditorEdge + +在指定的边缘（开始或结束）聚焦编辑器。 + + + + 编辑器实例。 + + + + + 要聚焦的边缘。 + - 'start': 在编辑器开始处聚焦。 + - 'end': 在编辑器结束处聚焦。 + 默认值为 'start'。 + + + + + +### setNode + +在编辑器中设置特定节点的属性。 + + + + 编辑器实例。 + + + 要更新的节点。 + + + 要在节点上设置的属性。 + + + 设置节点的选项，不包括 'at' 属性。 + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/api/slate-utils.mdx b/apps/www/content/docs/cn/api/slate-utils.mdx new file mode 100644 index 0000000000..0fc4bd41e9 --- /dev/null +++ b/apps/www/content/docs/cn/api/slate-utils.mdx @@ -0,0 +1,1018 @@ +--- +title: Slate Utils +description: udecode/slate-utils的 API 参考。 +--- + +`@udecode/slate-utils` 包含用于 Slate 的实用函数。 + +## 查询 + +### findDescendant + +遍历编辑器中的所有节点并返回第一个匹配项。如果没有找到匹配项，则返回 undefined。 + + + + 要搜索后代节点的编辑器。 + + + 查找节点的选项。它可以包含匹配条件、起始位置、是否反向遍历以及是否包含空节点。 + + + + 返回第一个匹配条件的节点entry，如果没有找到匹配项则返回 `undefined`。 + + +### getBlockAbove + +返回指定位置上方的块 + +- **默认值：** 选区。 + + + + 要搜索块的编辑器。 + + + 查找位置上方块的选项。 + + + + +返回指定位置上方的块。 + + + +### getBlocks + +从编辑器中检索块级节点entry。 + + + + 要搜索块级节点的编辑器。 + + + 获取节点entry的选项。 + + + + + 块级节点entry的数组。 + + +### getChildren + +返回节点entry的子节点entry。 + + + + 要获取其子节点的节点entry。 + + + + +返回子节点entry的数组。 + + + +### getEdgeBlocksAbove + +返回指定位置上方的边缘块。 + +- **默认值：** 选区。 + + + + 要搜索边缘块的编辑器。 + + + 查找位置上方边缘块的选项。 + + + + 返回包含指定位置上方的起始块和结束块的数组，如果未找到则返回 `null`。 + + +### getFragmentProp + +从节点片段中检索一个一致的属性值。 + + + + 要搜索属性的节点片段。 + + + + + 从每个节点提取的属性键。 + + + 如果未找到有效属性时返回的默认值。 + + + 从节点提取属性值的自定义函数。 + + + 确定如何遍历片段： + - 'all'：检查块节点和文本节点 + - 'block'：仅检查块节点 + - 'text'：仅检查文本节点 + 默认值为 'block'。 + + + + + + + 在片段中找到的一致属性值，如果没有找到一致的值则返回 undefined。 + + +### getFirstNodeText + +从节点获取第一个文本节点。 + + + + 要搜索文本节点的根节点。 + + + 获取节点文本的选项。 + + + + 返回第一个文本节点entry，如果未找到文本节点则返回 `undefined`。 + + +### getLastChild + +返回节点的最后一个子节点，如果没有子节点则返回 `null`。 + + + + 要获取其最后一个子节点的节点entry。 + + + + 返回节点的最后一个子节点，如果没有子节点则返回 `null`。 + + +### getLastNodeByLevel + +检索编辑器中指定层级的最后一个节点。 + + + + 要搜索最后一个节点的编辑器。 + + + 要查找最后一个节点的层级。 + + + + 返回指定层级的最后一个节点entry，如果未找到节点则返回 `undefined`。 + + +### getMark + +在编辑器中通过键检索选区标记的值。 + + + + 选区标记所在的编辑器。 + + + 要检索的选区标记的键。 + + + + 返回选区标记的值，如果未找到编辑器或标记则返回 `undefined`。 + + +### getNextNodeStartPoint + +检索编辑器中指定路径的下一个节点的起始点。 + + + + 要搜索下一个节点的编辑器。 + + + 要查找下一个节点的路径。 + + + + 返回下一个节点的起始点，如果未找到下一个节点则返回 `undefined`。 + + +### getNextSiblingNodes + +检索祖先节点中指定路径之后的兄弟节点。 + + + + 兄弟节点的祖先节点。 + + + 参考节点的路径。 + + + + 返回路径之后的兄弟节点数组，如果未找到兄弟节点则返回空数组。 + + +### getOperations + +检索编辑器的操作。 + + + + 要获取其操作的编辑器。 + + + + 返回编辑器的操作作为 `TOperation` 数组。 + + +### getPointBeforeLocation + +返回位置之前的点，并提供额外选项来自定义行为。如果未提供选项或者既未定义 **`match`** 也未定义 **`matchString`**，它将默认使用 **`getPointBefore`**。 + + + + 要在位置之前查找点的编辑器。 + + + 开始的位置。 + + + 定义如何执行搜索的选项。 + + + + 返回位置之前的点。如果未找到，则返回 `undefined`。 + + +### getPointFromLocation + +从位置返回点（**默认值：** 选区）。如果位置是范围，则获取锚点。如果位置是路径，则获取该路径上偏移量为 0 的点。 + + + +要查找点的编辑器。 + + + + + + +要获取点的位置。 + +- **默认值：** 选区。 + + + +如果为 true，返回焦点。否则，返回锚点。 + + + + + + + + + +返回位置的点。 + + + +### getPointNextToVoid + +如果起始点在内联空节点内，则返回其前面或后面的点。 + + + +要查找空节点旁边的点的编辑器。 + + + + + + +开始的点。 + + + +如果为 true，获取空节点后面的点。否则，获取前面的点。 + + + + + + + +返回空节点旁边的点。 + + + +### getPreviousBlockById + +通过 ID 查找块之前的块。如果未找到，则通过 ID 查找第一个块并返回 **`[null, 其前面的路径]`**。 + + + + 要查找前一个块的编辑器。 + + + 块的 ID。 + + + 节点查询的选项。 + + + + 如果找到，则返回前一个块的节点entry，否则返回 undefined。 + + +### getPreviousNodeEndPoint + +获取前一个节点的结束点。 + + + + 要查找前一个节点结束点的编辑器。 + + + 开始搜索的路径。 + + + + 如果找到，则返回前一个节点的结束点，否则返回 `undefined`。 + + +### getPreviousPath + +基于给定路径生成前一个路径。 + + + + 当前路径。 + + + + 前一个路径，如果没有前一个路径则返回 `undefined`。 + + +### getPreviousSiblingNode + +从给定路径获取前一个兄弟节点。 + + + + 编辑器实例。 + + + 当前路径。 + + + + 包含前一个兄弟节点及其路径的数组，如果没有前一个兄弟节点则返回 `undefined`。 + + +### getRangeBefore + +获取给定位置之前的点到位置结束点的范围。 + + + + 编辑器实例。 + + + 要考虑的位置。 + + + 获取位置之前点的选项。 + + + + 从位置之前的点到位置结束点的范围，如果不存在这样的点则返回 `undefined`。 + + +### getRangeFromBlockStart + +获取从位置上方块的开始到位置的范围。 + + + + 编辑器实例。 + + + 获取位置上方块的选项。 + + + + 从位置上方块的开始到位置的范围，如果不存在这样的块则返回 `undefined`。 + + +### getSelectionFragment + +检索当前选区的片段，可选择解包结构节点。 + + + + 要获取选区片段的编辑器。 + + + + + 要从片段中解包的结构类型数组。 + + + + + + + 表示当前选区片段的 `TElement` 数组。如果选区未展开或未找到片段，则返回空数组。 + + +### getSelectionText + +从编辑器获取选中的文本。 + + + + 编辑器实例。 + + + + 选中的文本，如果未选中文本则返回空字符串。 + + +### isAncestorEmpty + +检查祖先节点是否为空（具有空文本且没有内联子节点）。 + + + + 编辑器实例。 + + + 要检查的祖先节点。 + + + + +如果祖先节点为空则返回 true，否则返回 false。 + + + +### isBlockAboveEmpty + +检查选区上方的块是否为空。 + + + + 编辑器实例。 + + + + +如果选区上方的块为空则返回 true，否则返回 false。 + + + +### isBlockTextEmptyAfterSelection + +检查选区后块中的文本是否为空。 + + + + 编辑器实例。 + + + + +如果选区后块中的文本为空则返回 true，否则返回 false。 + + + +### isDocumentEnd + +检查选区是否在文档末尾。 + + + + 编辑器实例。 + + + + +如果选区在文档末尾则返回 true，否则返回 false。 + + + +### isFirstChild + +检查节点是否是其父节点的第一个子节点。 + + + + 要检查的节点的路径。 + + + + +如果节点是其父节点的第一个子节点则返回 true，否则返回 false。 + + + +### isMarkActive + +检查选区中是否激活了标记。 + + + + 编辑器实例。 + + + 标记键。 + + + + +如果选区中激活了标记则返回 true。 + + + +### isPointAtWordEnd + +检查点是否在单词末尾。 + + + + 编辑器实例。 + + + 要检查的点。 + + + + 如果点在单词末尾则返回 true，否则返回 false。 + + +### isRangeAcrossBlocks + +确定范围（**默认值：** 选区）是否跨越多个块。 + + + + 编辑器实例。 + + + 要检查的范围。如果未提供，则使用选区范围。 + + + + 如果范围跨越多个块则返回 true，如果在单个块内则返回 false，如果未找到块则返回 undefined。 + + +### isRangeInSameBlock + +确定范围是否在同一个块内。 + + + + 编辑器实例。 + + + 要检查的范围。如果未提供，则使用选区范围。 + + + + 如果范围在同一个块内则返回 true，否则返回 false。 + + +### isRangeInSingleText + +检查范围是否在单个文本路径内。 + + + + 要检查的范围。 + + + + 如果范围在单个文本路径内则返回 true，否则返回 false。 + + +### isSelectionAtBlockEnd + +检查选区焦点是否在其父块的末尾。 + + + + 编辑器实例。 + + + 选项对象。 + + + + 如果选区焦点在其父块的末尾则返回 true，否则返回 false。 + + +### isSelectionAtBlockStart + +检查选区锚点或焦点是否在其父块的开始。 + + + + 编辑器实例。 + + + 选项对象。 + + + + 如果选区锚点或焦点在其父块的开始则返回 true，否则返回 false。 + + +### isSelectionExpanded + +检查选区是否展开。 + + + + 编辑器实例。 + + + + +如果选区展开则返回 true，否则返回 false。 + + + +### isTextByPath + +检查给定路径的节点是否是文本节点。 + + + + 编辑器实例。 + + + 要检查的节点的路径。 + + + + +如果节点是文本节点则返回 true，否则返回 false。 + + + +### isWordAfterTrigger + +检查给定点的单词是否在触发器（标点符号）之后。 + + + + 编辑器实例。 + + + 要检查的点。 + + + 要检查的触发字符。 + + + + 一个对象，包含从前一个单词开始之前的点到给定点的范围，如果该范围的文本以触发器开始并以单词字符结束，则包含匹配项。 + + +### queryEditor + +查询编辑器状态。 + + + + 编辑器实例。 + + + 选项对象，可以包含过滤函数、selectionAtBlockStart、selectionAtBlockEnd、allow、exclude 和 at 属性。 + + + + 如果编辑器状态匹配查询则返回 true，否则返回 false。 + + +## 转换 + +### duplicateBlocks + +复制给定的块并将它们插入到选区中最后一个块之后。 + + + + 编辑器实例。 + + + 表示要复制的块的节点entry数组。 + + + +### insertElements + +在文档中的位置插入节点。 + + + + 编辑器实例。 + + + 要插入的节点。 + + + 选项对象。 + + + +### insertEmptyElement + +在文档中的位置插入空元素。 + + + + 编辑器实例。 + + + 要插入的元素的类型。 + + + 选项对象。 + + + +### moveChildren + +将节点的子节点移动到路径。 + + + + 编辑器实例。 + + + 选项对象，包括 `at`、`to`、`match` 和 `fromStartIndex` 属性。 + + + + +移动的子节点数量。 + + + +### removeEditorText + +从编辑器中删除所有非空文本节点。 + + + + 编辑器实例。 + + + 删除节点的选项。选项中的 `match` 函数将与文本长度检查组合。 + + + +### removeMark + +删除标记，如果选区折叠则触发 `onChange`。 + + + + 编辑器实例。 + + + 选项对象，包括 `key`、`at` 和 `shouldChange` 属性。 + + + +### removeNodeChildren + +删除节点的所有子节点。 + + + + 编辑器实例。 + + + 要删除子节点的节点的路径。 + + + 选项对象。 + + + +### removeSelectionMark + +从选区中删除所有标记。 + + + + 编辑器实例。 + + + +### replaceNodeChildren + +替换节点的子节点：先删除后插入。 + + + + 编辑器实例。 + + + 选项对象，包括 `at`、`nodes`、`insertOptions` 和 `removeOptions` 属性。 + + + +### selectEndOfBlockAboveSelection + +选择选区上方块的结束点。 + + + + 编辑器实例。 + + + +### selectNodes + +选择包含给定节点的范围。 + + + + 编辑器实例。 + + + 要选择的节点entry数组。 + + + +### setBlockAboveNode + +在当前选区上方的块上设置属性。 + + + + 编辑器实例。 + + + 要在块上设置的属性。 + + + 设置节点的选项，不包括 'at' 属性。 + + + +### setBlockAboveTexts + +在当前选区上方块内的最低级节点上设置属性。 + + + + 编辑器实例。 + + + 要在文本节点上设置的属性。 + + + 设置节点的选项，不包括 'at' 属性。 + + + +### setBlockNodes + +在所有匹配给定选项的块节点上设置属性。 + + + + 编辑器实例。 + + + 要在匹配的块节点上设置的属性。 + + + 获取要更新的节点entry的选项。 + + + +### setMarks + +在选中的文本上设置标记。 + + + + 编辑器实例。 + + + 要设置的标记。 + + + 要清除的标记。 + + + +### toggleMark + +在选区中添加或删除标记。 + + + + 编辑器实例。 + + + 选项对象，包含 `key` 和 `clear` 属性。 + + + +### toggleWrapNodes + +如果选区中存在该节点类型则解除包装，否则进行包装。 + + + + 编辑器实例。 + + + 节点的类型。 + + + +### wrapNodeChildren + +将节点的子节点包装到单个元素中。 + + + + 编辑器实例。 + + + 新的父元素。 + + + 选项对象，包含 `at` 属性。 + + + +## Utils + +### createDocumentNode + +创建一个新的文档节点。 + + + +节点的类型。 + +- **默认值：** `'p'` + + + +节点的文本。 + +- **默认值：** 空字符串。 + + + +剩余的节点。 + +- **默认值：** 空数组。 + + + + +一个 `TDescendant` 节点数组，以新创建的节点开始。 + + +### createNode + +创建一个新节点。 + + + +节点的类型。 + +- **默认值：** `'p'` + + + +节点的文本。 + +- **默认值：** 空字符串。 + + + + + +一个新的 `TElement` 节点。 + + diff --git a/apps/www/content/docs/cn/api/slate.mdx b/apps/www/content/docs/cn/api/slate.mdx new file mode 100644 index 0000000000..c9167ffd44 --- /dev/null +++ b/apps/www/content/docs/cn/api/slate.mdx @@ -0,0 +1,314 @@ +--- +title: Slate +description: udecode/slate的 API 参考。 +--- + +`@udecode/slate` 使用泛型类型扩展了 Slate API。 + +## 编辑器 + +在 [Slate 文档](https://docs.slatejs.org/api/transforms) 中查找相应的文档。 + +### `addMark` + +### `createPathRef` + +### `createPointRef` + +### `createRangeRef` + +### `deleteBackward` + +### `deleteForward` + +### `deleteFragment` + +### `deleteMerge` + +### `getAboveNode` + +### `getEdgePoints` + +### `getEditorString` + +### `getEndPoint` + +### `getFirstNode` + +### `getFragment` + +### `getLastNode` + +### `getLeafNode` + +### `getLevels` + +### `getMarks` + +### `getNextNode` + +### `getNodeEntries` + +### `getNodeEntry` + +### `getParentNode` + +### `getPath` + +### `getPathRefs` + +### `getPoint` + +### `getPointAfter` + +### `getPointBefore` + +### `getPointRefs` + +### `getPositions` + +### `getPreviousNode` + +### `getRange` + +### `getRangeRefs` + +### `getStartPoint` + +### `getVoidNode` + +### `hasBlocks` + +### `hasInlines` + +### `hasTexts` + +### `index` + +### `insertBreak` + +### `insertNode` + +### `isBlock` + +### `isEdgePoint` + +### `isEditor` + +### `isEditorNormalizing` + +### `isElementEmpty` + +### `isEndPoint` + +### `isInline` + +### `isStartPoint` + +### `isVoid` + +### `normalizeEditor` + +### `removeEditorMark` + +### `TEditor` + +### `unhangRange` + +### `withoutNormalizing` + +## Element + +在 [Slate 文档](https://docs.slatejs.org/api/nodes/element) 中查找相应的文档。 + +### `elementMatches` + +### `index` + +### `isElement` + +### `isElementList` + +### `TElement` + +## History + +在 [Slate 文档](https://docs.slatejs.org/libraries/slate-history) 中查找相应的文档。 + +### `isHistoryEditor` + +### `isHistoryMerging` + +### `isHistorySaving` + +### `withoutMergingHistory` + +### `withoutSavingHistory` + +## Node + +在 [Slate 文档](https://docs.slatejs.org/api/nodes/node) 中查找相应的文档。 + +### `TDescendant` + +### `getNodeDescendants` + +### `getNodeLastNode` + +### `getNodeString` + +### `getNodeFirstNode` + +### `hasNode` + +### `isNode` + +### `getNodeFragment` + +### `getNodeLeaf` + +### `getNodeLevels` + +### `isNodeList` + +### `getNodeProps` + +### `TAncestor` + +### `getNode` + +### `getNodeTexts` + +### `getNodes` + +### `getNodeChildren` + +### `getNodeAncestor` + +### `TNodeEntry` + +### `TNode` + +### `nodeMatches` + +### `getNodeChild` + +### `getNodeElements` + +### `getNodeAncestors` + +### `getNodeDescendant` + +### `getCommonNode` + +### `isAncestor` + +### `hasSingleChild` + +### `getNodeParent` + +## Range + +在 [Slate 文档](https://docs.slatejs.org/api/locations/range) 中查找相应的文档。 + +### `isCollapsed` + +### `isExpanded` + +## Text + +在 [Slate 文档](https://docs.slatejs.org/api/nodes/text) 中查找相应的文档。 + +### `isText` + +### `isTextList` + +### `textEquals` + +### `textMatches` + +### `TText` + +## Transforms + +在 [Slate 文档](https://docs.slatejs.org/api/transforms) 中查找相应的文档。 + +### `moveNodes` + +### `moveSelection` + +### `removeNodes` + +### `select` + +### `insertText` + +### `insertNodes` + +### `deleteText` + +### `setPoint` + +### `setNodes` + +### `unwrapNodes` + +### `deselect` + +### `mergeNodes` + +### `collapseSelection` + +### `unsetNodes` + +### `setSelection` + +### `splitNodes` + +### `insertFragment` + +### `wrapNodes` + +### `liftNodes` + +## Types + +### QueryNodeOptions + +用于查询节点entry的接口。 + + + + +用于过滤节点entry的函数。 + +- 该函数应接收一个节点entry作为参数并返回一个布尔值。 + + + + +有效类型列表。 + +- 如果为空或未定义，则允许所有类型。 + + + + +无效类型列表。 + + + + +有效的路径层级。 + + + + +高于此层级的路径无效。 + + + diff --git a/apps/www/content/docs/cn/api/utils.mdx b/apps/www/content/docs/cn/api/utils.mdx new file mode 100644 index 0000000000..453f7f5f9f --- /dev/null +++ b/apps/www/content/docs/cn/api/utils.mdx @@ -0,0 +1,362 @@ +--- +title: Plate Utils +description: udecode/plate-utils的API参考。 +--- + +`@udecode/plate-utils` 包含 Plate 的实用函数。 + +## 组件 + +### PlateElement + +用于渲染元素的通用组件。 + + + +PlateElementProps。 + + +应用于组件的 CSS 类。 + + +传递给组件的额外属性。 + + +编辑器实例。也可以使用 `useEditorRef` hook 获取。 + + +元素节点。也可以使用 `useElement` hook 获取。 + + +元素在编辑器树中的路径。也可以使用 `usePath` hook 获取。 + + +要传播到顶层元素的元素属性。 + + +这始终设置为 `'element'`。 + + + + + +元素的引用。如果使用自己的引用，必须将其与此引用合并。 + + + + +渲染节点子元素所必需的。 + + +从 Slate 元素获取 HTML 属性。这是 `PlatePlugin.props` 的替代方案。 + + +要渲染的组件类型。 + +- **默认值:** `'div'` + + + +如果为 true，将其属性合并到其直接子元素上。 + + + +### PlateLeaf + +用于渲染叶子节点的通用组件。 + + + +PlateLeafProps。 + + +应用于组件的 CSS 类。 + + +编辑器上下文。 + + +传递给组件的额外属性。 + + +渲染节点子元素所必需的。 + + +叶子节点。 + + +文本节点。 + + +要传播到顶层元素的叶子属性。 + + + +这始终设置为 `true`。 + + + + +从 Slate 叶子获取 HTML 属性。这是 `PlatePlugin.props` 的替代方案。 + + +要渲染的组件类型。 + +- **默认值:** `'span'` + + + +如果为 true，将其属性合并到其直接子元素上。 + + + +## Hooks + +### useEditorString + +一个返回编辑器全部文本内容作为字符串的 hook。 + + + + 编辑器中所有文本节点的连接文本内容。 + + + +### useMarkToolbarButtonState + +生成标记工具栏按钮的状态。 + + + + 要检查活动标记的节点类型。 + + + 应用标记时要清除的节点类型。 + + + + + 一个布尔值，指示当前选择中 nodeType 标记是否处于活动状态。 + + + 节点的类型。 + + + 要清除的节点类型。 + + + +### useMarkToolbarButton + +使用由 **`useMarkToolbarButtonState`** 创建的状态生成标记工具栏按钮的属性。 + + + + 由 `useMarkToolbarButtonState` 生成的标记工具栏按钮状态。 + + + + + 工具栏按钮的属性，包括 `pressed` 状态和 `onClick` 函数。 + + + 一个布尔值，指示标记工具栏按钮是否处于活动状态。 + + + 处理按钮的 onClick 事件的函数，切换标记并使编辑器获得焦点。 + + + + + +### usePlaceholderState + +生成编辑器中占位符的状态。 + + + + 如果为 true，则在编辑器失去焦点时隐藏占位符。 + + - **默认值:** `true` + + + + 查询节点的选项。如果定义了该选项，则只有在节点匹配查询时才显示占位符。 + + + 要显示占位符的元素。 + + + + + 一个布尔值，指示是否应该显示占位符。 + + + +### useRemoveNodeButton + +生成一个按钮的属性，点击该按钮时从编辑器中删除节点。 + + + + 点击按钮时要删除的节点元素。 + + + + + 删除节点按钮的属性，包括 `onClick` 函数。 + + + 处理按钮点击事件的函数，删除节点并使编辑器获得焦点。 + + + + + +## Queries + +### isType + +检查节点是否匹配提供的类型。 + + + + 节点所在的编辑器。 + + + 要检查的节点。 + + + 用于匹配节点的类型。可以是字符串或字符串数组。 + + + + 一个布尔值，指示节点的类型是否匹配提供的类型。 + + +## Transforms + +### resetEditorChildren + +用默认块替换编辑器的子节点。 + + + + 要替换其子节点的编辑器。 + + + 替换节点子节点的选项。不包括 `at` 和 `nodes` 选项。 + + + +### selectEditor + +在目标位置或边缘（开始、结束）选择编辑器。 + + + + 要选择的编辑器。 + + + 要选择的具体位置。 + - 如果未定义 `edge`，则考虑此选项。 + + + 选择编辑器的开始或结束。 + - 如果定义了此选项，则覆盖 `at` 选项。 + + + 如果为 true，则在选择 markdown Copy code 之前聚焦 React 编辑器。 + + - **默认值:** `false` + + + + + 没有显式返回，但会选择并可能聚焦编辑器。 + + +### moveSelectionByOffset + +根据键盘方向键按偏移量移动选择。 + + + + 编辑器实例。 + + + 按偏移量移动选择的选项。这是一个可选参数。 + + + 启用行为的查询函数。 + + + 触发移动的键盘事件。 + + + + + +### selectSiblingNodePoint + +从指定节点的前一个或后一个兄弟节点选择一个点。 + + + + 编辑器实例。 + + + 选择兄弟节点点的选项。 + + + 参考节点的路径。如果未提供，则必须指定 `node`。 + + + 是否选择前一个兄弟节点而不是后一个。 + - `false`: 选择下一个兄弟节点的起始点。 + - `true`: 选择前一个兄弟节点的结束点。 + - **Default:** `false` + + + 选择后是否聚焦编辑器。 + - **Default:** `true` + + + 参考节点。如果未提供 `at`，则用于查找路径。 + + + + + +## Utils + +### defaultsDeepToNodes + +使用查询递归地将源对象合并到子节点中。 + + + + 函数的选项，不包括 'apply' 选项。 + + + + 没有显式返回，但会根据提供的选项修改子节点。 + diff --git a/apps/www/content/docs/cn/autoformat.mdx b/apps/www/content/docs/cn/autoformat.mdx new file mode 100644 index 0000000000..da6515f60e --- /dev/null +++ b/apps/www/content/docs/cn/autoformat.mdx @@ -0,0 +1,317 @@ +--- +title: Autoformat +docs: + - route: /docs/basic-elements + title: Basic Elements + - route: /docs/basic-marks + title: Basic Marks + - route: /docs/horizontal-rule + title: Horizontal Rule + - route: /docs/list + title: List +--- + + + + + +## 功能特点 + +- 通过短代码快速格式化内容。 +- 提供类似 markdown 的行内代码，用于实时输入。 +- 通过避免工具栏按钮和快捷键来简化编辑。 +- 自动转换功能（例如，`#` 到 H1）。 +- 提供预定义的格式化规则。 + +**格式化快捷代码：** + +- `text*` 用于加粗文本。 +- `_text_` 用于斜体文本。 +- `~~text~~` 用于删除线文本。 +- ...等等。 + + + +## 安装 + +```bash +npm install @udecode/plate-autoformat +``` + +## 使用 + +```tsx +import { AutoformatPlugin } from '@udecode/plate-autoformat/react'; + +const plugins = [ + // ...otherPlugins, + AutoformatPlugin.configure({ + options: { + rules: autoformatRules, + enableUndoOnDelete: true, + }, + }), +]; +``` + +## 示例 + +### `autoformatRules` + + + +### `autoformatBlocks` + +### `autoformatIndentLists` +如果使用 [Indent List 插件](/docs/indent-list)，您可以使用以下规则： + +### `autoformatLists` + +如果使用 [List 插件](/docs/list)，您可以使用以下规则： + +### `autoformatMarks` + +### `autoformatUtils` + +## API + +### AutoformatPlugin + + + + + +触发规则列表。 + +- 可以是以下之一：`AutoformatBlockRule`、`AutoformatMarkRule`、`AutoformatTextRule`。 +- 继承 `AutoformatCommonRule`。 + + + + +Enable undo on delete. + + + + +### Rules + +You can import the following rules: + +| 名称 | 描述 | +| :----------------------------- | :----------------------------------- | +| `autoformatSmartQuotes` | 将 `"text"` 转换为 `"text"`。 | +| | 将 `'text'` 转换为 `'text'`。 | +| `autoformatPunctuation` | 将 `--` 转换为 `—`。 | +| | 将 `...` 转换为 `…`。 | +| | 将 `>>` 转换为 `»`。 | +| | 将 `<<` 转换为 `«`。 | +| `autoformatArrow` | 将 `->` 转换为 `→`。 | +| | 将 `<-` 转换为 `←`。 | +| | 将 `=>` 转换为 `⇒`。 | +| | 将 `<=` 和 `≤=` 转换为 `⇐`。 | +| `autoformatLegal` | 将 `(tm)` 和 `(TM)` 转换为 `™`。 | +| | 将 `(r)` 和 `(R)` 转换为 `®`。 | +| | 将 `(c)` 和 `(C)` 转换为 `©`。 | +| `autoformatLegalHtml` | 将 `™` 转换为 `™`。 | +| | 将 `®` 转换为 `®`。 | +| | 将 `©` 转换为 `©`。 | +| | 将 `§` 转换为 `§`。 | +| `autoformatComparison` | 将 `!>` 转换为 `!>`。 | +| | 将 `!<` 转换为 `≮`。 | +| | 将 `>=` 转换为 `≥`。 | +| | 将 `<=` 转换为 `≤`。 | +| | 将 `!>=` 转换为 `≱`。 | +| | 将 `!<=` 转换为 `≰`。 | +| `autoformatEquality` | 将 `!=` 转换为 `≠`。 | +| | 将 `==` 转换为 `≡`。 | +| | 将 `!==` 和 `≠=` 转换为 `≢`。 | +| | 将 `~=` 转换为 `≈`。 | +| | 将 `!~=` 转换为 `≉`。 | +| `autoformatFraction` | 将 `1/2` 转换为 `½`。 | +| | 将 `1/3` 转换为 `⅓`。 | +| | ... | +| | 将 `7/8` 转换为 `⅞`。 | +| `autoformatDivision` | 将 `//` 转换为 `÷`。 | +| `autoformatOperation` | 将 `+-` 转换为 `±`。 | +| | 将 `%%` 转换为 `‰`。 | +| | 将 `%%%` 和 `‰%` 转换为 `‱`。 | +| | `autoformatDivision` rules. | +| `autoformatSubscriptNumbers` | 将 `~0` 转换为 `₀`。 | +| | 将 `~1` 转换为 `₁`。 | +| | ... | +| | 将 `~9` 转换为 `₉`。 | +| `autoformatSubscriptSymbols` | 将 `~+` 转换为 `₊`。 | +| | 将 `~-` 转换为 `₋`。 | +| `autoformatSuperscriptNumbers` | 将 `^0` 转换为 `⁰`。 | +| | 将 `^1` 转换为 `¹`。 | +| | ... | +| | 将 `^9` 转换为 `⁹`。 | +| `autoformatSuperscriptSymbols` | 将 `^+` 转换为 `°`。 | +| | 将 `^-` 转换为 `⁺`。 | +| `autoformatMath` | `autoformatComparison` rules | +| | `autoformatEquality` rules | +| | `autoformatOperation` rules | +| | `autoformatFraction` rules | +| | `autoformatSubscriptNumbers` rules | +| | `autoformatSubscriptSymbols` rules | +| | `autoformatSuperscriptNumbers` rules | +| | `autoformatSuperscriptSymbols` rules | + +### AutoformatCommonRule +自动格式化规则的通用结构接口，不受其模式影响。 + + + + +当触发器和光标前的文本匹配时应用规则。 + +- 对于 `mode: 'block'`：在光标前查找结束匹配。 +- 对于 `mode: 'text'`：在光标前查找结束匹配。如果 `format` 是数组，还会查找开始匹配。 +- 对于 `mode: 'mark'`：查找开始和结束匹配。 +- 注意：`'_*'`、`['_*']` 和 `{ start: '_*', end: '*_' }` 是等效的。 +- `MatchRange`： + + + + + +范围的起始点。 + + + + +范围的结束点。 + + + + + + + +触发自动格式化的字符。 + + + + +如果为 true，在自动格式化后插入触发字符。 + +- **默认值：** `false` + + + + +允许自动格式化的查询函数。 + +- `AutoformatQueryOptions` 继承 `Omit`： + + + + +`insertText` 文本。 + + + + + + + +### AutoformatBlockRule + +块模式自动格式化规则的接口。 + + + + +- 文本：插入文本。 +- 块：设置块类型或自定义格式。 +- 标记：在匹配之间插入标记。 + + + + +匹配自动格式化规则的模式。 + + + + +- 对于 `mode: 'block'`：设置块类型。如果定义了 `format`，则忽略此字段。 +- 对于 `mode: 'mark'`：要添加的标记。 + + + + +如果为 true，触发器应该在块开始处才允许自动格式化。 + +- **默认值：** `true` + + + + +如果为 true，即使在选定块上方有相同类型的块，也允许自动格式化。 + +- **默认值：** `false` + + + + +在 `format` 之前调用的函数。通常用于重置选定的块。 + + + + +自定义格式化函数。 + + + + +### AutoformatMarkRule + +标记模式自动格式化规则的接口。 + + + + +模式为 'mark'。 + + + + +要添加的标记。 + + + + +如果为 false，当字符串可以被修剪时不进行格式化。 + + + + +### AutoformatTextRule + +文本模式自动格式化规则的接口。 + + + + +模式为 'text'。 + + + + +匹配自动格式化规则的模式。 + + + + +匹配的文本被该字符串替换，匹配的文本被这些字符串替换，或在匹配时调用的函数。 + + + diff --git a/apps/www/content/docs/cn/basic-elements.mdx b/apps/www/content/docs/cn/basic-elements.mdx new file mode 100644 index 0000000000..e423fcd225 --- /dev/null +++ b/apps/www/content/docs/cn/basic-elements.mdx @@ -0,0 +1,292 @@ +--- +title: Basic Elements +docs: + - route: /docs/components/blockquote-element + title: Block Quote Element + - route: /docs/components/code-block-element + title: Code Block Element + - route: /docs/components/code-line-element + title: Code Line Element + - route: /docs/components/code-syntax-leaf + title: Code Syntax Leaf + - route: /docs/components/heading-element + title: Heading Element +--- + + + + + +## 功能特点 + +- 包含常用的块级元素：引用块、代码块和标题。 + + + +**插件：** + +- `BlockquotePlugin` 用于 `blockquote` 元素 +- `CodeBlockPlugin` 用于 `code_block` 元素 +- `HeadingPlugin` 用于 `h1`、`h2`... 等元素 + +## 安装 + +## Usage + +```tsx +import { + BasicElementsPlugin, + CodeBlockPlugin, +} from '@udecode/plate-basic-elements/react'; +import Prism from 'prismjs'; + +const plugins = [ + // ...otherPlugins, + BasicElementsPlugin.configurePlugin(CodeBlockPlugin, { + options: { + prism: Prism, + }, + }), +]; +``` + +## 键盘快捷键 + + + 切换一级标题块。 + 切换二级标题块。 + 切换三级标题块。 + + 切换所选文本的引用块格式。 + + + +## 插件 + +### BasicElementsPlugin + +### BlockquotePlugin + +### HeadingPlugin + + + +指定支持的标题级别，范围从1到指定的级别。 + + + + +### CodeBlockPlugin + + + + +确定是否启用语法高亮。 + + + +确定是否优先显示常用语法。 + + + +定义代码块插件的反序列化器。 + + + + +## 代码块 API + +### isCodeBlockEmpty + +检查选区是否在空代码块内。 + + + + 编辑器实例。 + + + + + + 如果选区在空代码块内则返回 true。 + + + +### isSelectionAtCodeBlockStart + +检查选区是否在代码块第一行的开始位置。 + + + + 编辑器实例。 + + + + + + 如果选区在代码块第一行的开始位置则返回 true。 + + + +### indentCodeLine + +如果选区已展开或光标左侧没有非空白字符，则缩进代码行。默认缩进为2个空格。 + + + +编辑器实例。 + + + + + 要缩进的代码行。 + + +代码行的缩进大小。 + +- **默认值：** `2` + + + + + + + +### insertCodeBlock + +插入一个代码块，将节点设置为代码行并将其包裹在代码块中。如果光标不在块开始处，则会在代码块前插入一个换行符。 + + + + 编辑器实例。 + + + `setNodes` 函数的选项。 + + + +### insertCodeLine + +插入一个具有指定缩进深度的代码行。 + + + + 编辑器实例。 + + + 代码行的缩进深度。 + + - **默认值：** `0` + + + + +### outdentCodeLine + +减少代码行缩进，如果存在则删除两个空白字符。 + + + + 编辑器实例。 + + + + + 要减少缩进的代码行。 + + + 包含要减少缩进的代码行的代码块。 + + + + + +### toggleCodeBlock + +在编辑器中切换代码块。 + + + + 编辑器实例。 + + + +### unwrapCodeBlock + +在编辑器中解除代码块包裹。 + + + + 编辑器实例。 + + + +### useCodeBlockCombobox + + + + 代码块元素。 + + + 设置元素值的回调函数。 + + + + + + 命令项的属性。 + + + 选择命令项时调用的函数。 + + + + + +### useCodeBlockElementState + + + + 代码块元素。 + + + + + + 代码块元素的 CSS 类名，表示所选的语言。 + + + 语法插件选项。 + + + +### useCodeSyntaxLeaf + + + + + + 表示代码语法标记的叶节点。 + + + + + + + + 标记的属性。 + + + 标记的 CSS 类名。 + + + + diff --git a/apps/www/content/docs/cn/basic-marks.mdx b/apps/www/content/docs/cn/basic-marks.mdx new file mode 100644 index 0000000000..8fb63f7aa8 --- /dev/null +++ b/apps/www/content/docs/cn/basic-marks.mdx @@ -0,0 +1,136 @@ +--- +title: Basic Marks +docs: + - route: /docs/components/mark-toolbar-button + title: 标记工具栏按钮 +--- + + + + + +## 功能 + +- 包括常用的文本样式功能：粗体、斜体、下划线、删除线、上标、下标和代码。 + + + +**插件：** + +- `BoldPlugin` 用于 `bold` 标记 +- `ItalicPlugin` 用于 `italic` 标记 +- `UnderlinePlugin` 用于 `underline` 标记 +- `StrikethroughPlugin` 用于 `strikethrough` 标记 +- `SubscriptPlugin` 用于 `subscript` 标记 +- `SuperscriptPlugin` 用于 `superscript` 标记 +- `CodePlugin` 用于 `code` 标记 + +## Installation + +```bash +npm install @udecode/plate-basic-marks +``` + +## Usage + +```tsx +import { BasicMarksPlugin } from '@udecode/plate-basic-marks/react'; + +const plugins = [ + // ...otherPlugins, + BasicMarksPlugin, +]; +``` + +## 键盘快捷键 + + + + 切换所选文本的粗体格式。 + + + 切换所选文本的斜体格式。 + + + 切换所选文本的下划线格式。 + + + 切换所选文本的代码格式。 + + + 切换所选文本的删除线格式。 + + + 切换所选文本的下标格式。 + + + 切换所选文本的上标格式。 + + + +## 插件 + +### BasicMarksPlugin + +### BoldPlugin + + + +要删除的节点属性。 + + + + +### CodePlugin + + + +要删除的节点属性。 + + + + +### ItalicPlugin + + + +要删除的节点属性。 + + + + +### UnderlinePlugin + + + +要删除的节点属性。 + + + + +### StrikethroughPlugin + + + +要删除的节点属性。 + + + + +### SubscriptPlugin + + + +要删除的节点属性。 + + + + +### SuperscriptPlugin + + + +要删除的节点属性。 + + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/block-menu.mdx b/apps/www/content/docs/cn/block-menu.mdx new file mode 100644 index 0000000000..48c39c7714 --- /dev/null +++ b/apps/www/content/docs/cn/block-menu.mdx @@ -0,0 +1,114 @@ +--- +title: Block Menu +docs: + - route: /docs/components/block-context-menu + title: Block Context Menu + + - route: https://pro.platejs.org/docs/components/block-menu + title: Block Menu + + - route: https://pro.platejs.org/docs/components/block-context-menu + title: Block Context Menu + +--- + + + + + +## 功能特点 + +- 右键点击块元素打开菜单。 +- 允许对块执行转换、复制或删除等操作。 +- 可自定义菜单项和操作。 +- 支持键盘导航 + + + +## Installation + +```bash +npm install @udecode/plate-selection @udecode/plate-node-id +``` + +## Usage + +```tsx +import { BlockMenuPlugin } from '@udecode/plate-selection/react'; +import { NodeIdPlugin } from '@udecode/plate-node-id'; +``` + +```tsx +const plugins = [ + // ...otherPlugins, + NodeIdPlugin, + BlockSelectionPlugin.configure({ + options: { + enableContextMenu: true, + }, + }), + BlockMenuPlugin.configure({ + render: { aboveEditable: BlockContextMenu }, + }), +] +``` + +- [BlockContextMenu](/docs/components/block-context-menu) + +要控制特定元素的上下文菜单的打开，你可以使用 `data-plate-open-context-menu` 属性： + +```tsx + + {children} + +``` + +通常，我们只需要阻止在 `` 的内边距上右键点击。 + +## 示例 + +### Plate UI + +参考上面的预览。 + +### Plate Plus + + + +## 插件 + +### BlockMenuPlugin + +块菜单状态管理。 + +## API + +### editor.api.blockMenu.hide + +隐藏块菜单。 + +### editor.api.blockMenu.show + +显示特定块的菜单。 + + + + 要显示菜单的块的 ID。 + + + 显示菜单的位置。 + + + +### editor.api.blockMenu.showContextMenu + +显示特定块的上下文菜单。 + + + + 要显示上下文菜单的块的 ID。 + + + 显示上下文菜单的位置。 + + diff --git a/apps/www/content/docs/cn/block-selection.mdx b/apps/www/content/docs/cn/block-selection.mdx new file mode 100644 index 0000000000..ce86779ecf --- /dev/null +++ b/apps/www/content/docs/cn/block-selection.mdx @@ -0,0 +1,376 @@ +--- +title: Block Selection +docs: + - route: /docs/components/block-selection + title: Block Selection +--- + + + + +块选择功能允许用户选择和操作整个文本块，而不是单个词或字符。这个强大的功能通过提供高效的方式来管理大段内容，从而增强了编辑体验。 + +## 功能特点 + +- 单次操作即可选择整个块 +- 多块选择 +- 对选中的块进行复制、剪切和删除操作 +- 快速选择的键盘快捷键： + - `Cmd+A`： + - 第一次按：选择当前块 + - 双击：选择所有块 + - 方向键：选择上方或下方的块 +- 可自定义选中块的样式 + + + +## Installation + +```bash +npm install @udecode/plate-selection @udecode/plate-node-id +``` + +## Usage + +```tsx +import { NodeIdPlugin } from '@udecode/plate-node-id'; +import { BlockSelectionPlugin } from '@udecode/plate-selection/react'; + +const plugins = [ + // ...otherPlugins, + NodeIdPlugin, + BlockSelectionPlugin, +]; +``` + +### 从选择中排除块 + +你可以使用以下方式从块选择中排除某些插件： + +```ts +BlockSelectionPlugin.configure({ + inject: { + // Exclude blocks below table rows + excludeBelowPlugins: ['tr'], + // Exclude block types + excludePlugins: ['table', 'code_line', 'column_group', 'column'], + } +}) +``` +- `excludeBelowPlugins`: 不可选择的块级后代元素的插件键。用于防止在特定块下进行选择。例如，排除 'tr' 可以防止选择单个单元格，但仍允许选择表格行。 + +- `excludePlugins`: 不可选择的块的插件键。 + +### 设置可滚动容器 + +如果你正在使用 [Editor](/docs/components/editor) 中的 `EditorContainer`，可以跳过本节。 + +要控制可滚动容器，请在 `areaOptions` 中配置 `boundaries` 和 `container` 选项。这些选项接受 CSS 选择器，例如 `#selection-demo #${editor.uid}`，它们与 `document.querySelector()` 一起使用。 + +为了使其有效工作： + +1. 为你的滚动容器添加 `id` 或 `className`。如果你不确定容器，可以将其添加到 `` 组件中。我们推荐使用 `id={editor.uid}`。 +2. 在你的配置中使用适当的选择器。 +3. 不要忘记将 `position: relative` 设置到容器。 + +Default configuration: + +```js +BlockSelectionPlugin.configure({ + options: { + areaOptions: { + boundaries: `#${editor.uid}`, + container: `#${editor.uid}`, + selectables: `#${editor.uid} .slate-selectable`, + }, + }, +}); +``` + +### 设置滚动速度 + +使用 `options.areaOptions.behaviour.scrolling.speedDivider` 来设置滚动速度。 + +我们推荐使用 `0.8` 的值，因为它接近浏览器原生的滚动速度。 + + +```ts +BlockSelectionPlugin.configure({ + options: { + areaOptions: { + behaviour: { + scrolling: { + // 你可以通过设置更大的值来减慢滚动速度。 + speedDivider: 1.5, + }, + // 需要移动的距离，使选择区域出现。 + // 如果太小，可能会导致鼠标点击事件被阻止。10 是一个很好的默认值。 + startThreshold: 4, + }, + }, +} +``` +### 添加可选择元素 + +在任何你想要启动块选择的元素上添加 `data-plate-selectable="true"` 属性。 + +### 阻止取消选择 + +要防止在点击某些元素时取消选择块，请在这些组件上添加 `data-plate-prevent-unselect` 属性 + +例如： +```tsx + +``` + +### 全页选择 + +#### 使元素可选择 + +你可以启用块选择，使 `` 组件之外的元素可选择，类似于 [Potion](https://potion.platejs.org/) 模板。添加 `data-plate-selectable` 属性到任何你想使可选择的组件： + +```tsx + + +``` + +这适用于任何元素，即使是在编辑器 DOM 树之外的元素。 + +#### 重置选择 + +有两种方式处理全页面的选择重置： + +1. 直接调用 API： +```tsx +editor.api.blockSelection.unselect(); +``` + +2. 点击外部处理程序： +```tsx +const handleClickOutside = (event: MouseEvent) => { + if (!(event.target as HTMLElement).closest('[data-plate-selectable]')) { + editor.api.blockSelection.unselect(); + } +}; +``` + +## 样式 + +### 选择区域 + +通过将 `.slate-selection-area` 类添加到你的编辑器容器组件来样式化选择区域。例如： + +```js +'[&_.slate-selection-area]:border [&_.slate-selection-area]:border-primary [&_.slate-selection-area]:bg-primary/10' +``` + +### 选中的元素 + +要确定一个元素是否被选中，使用 `useBlockSelected` 钩子。你可以使用我们的 [BlockSelection](/docs/components/block-selection) 组件或创建你自己的来渲染选中的块的视觉指示器。 + +这个组件应该在每个块元素内部渲染，以确保一致的选择反馈。Plate UI 在 [PlateElement](/docs/components/plate-element) 中这样做。 + +## 插件 + +### BlockSelectionPlugin + + + +Options for the selection area. Example: + +```ts +{ + boundaries: [`#${editor.uid}`], + container: [`#${editor.uid}`], + selectables: [`#${editor.uid} .slate-selectable`], + selectionAreaClass: 'slate-selection-area', +} +``` + + + +编辑器的右内边距。 + + + +启用或禁用块选择的上下文菜单。 + +- **默认值:** `false` + + + +指示块选择当前是否处于活动状态。 + +- **默认值:** `false` + + + +一个用于处理选择时的 **`keydown`** 事件的函数。 + + + +块选择期间查询节点的选项。 + +- **默认值:** `{ maxLevel: 1 }` + + + +当前选中的块的 ID 集合。 + +- **默认值:** `new Set()` + + + +### BlockMenuPlugin + +## API + +### editor.api.blockSelection.focus +聚焦块选择的影子输入。这个输入处理选中块的复制、删除和粘贴事件。 + +### editor.api.blockSelection.addSelectedRow + +向块选择中添加一个选中的行。 + + + + 要选择的行的 ID。 + + + + + 在添加新选择之前是否清除现有选择。 + - **默认值:** `true` + + + + + +### editor.api.blockSelection.getNodes + +获取编辑器中选中的块。 + + + + 选中块entry的数组。 + + + +### editor.api.blockSelection.resetSelectedIds + +将选中的 ID 集合重置为空集合。 + +### editor.api.blockSelection.selectedAll + +选择编辑器中所有可选择的块。 + +### editor.api.blockSelection.setSelectedIds + +根据添加和移除的元素设置选中的 ID。 + + + + + + 要添加到选择中的 HTML 元素数组。 + + + 要从选择中移除的 HTML 元素数组。 + + + + + +### editor.api.blockSelection.unselect + +取消选择所有块并将 `isSelecting` 标志设置为 false。 + +## 转换 + +### editor.tf.blockSelection.duplicate + +复制选中的块。 + + + + 要复制的节点entry数组。 + + + +### editor.tf.blockSelection.removeNodes + +从编辑器中移除选中的节点。 + +### editor.tf.blockSelection.select + +选择由 `getNodes()` 返回的节点并重置选中的 ID。 + +### editor.tf.blockSelection.setNodes + +设置选中节点的属性。 + + + + 要设置到选中节点的属性。 + + + 设置节点的选项。 + + + +### editor.tf.blockSelection.setTexts + +设置选中节点的文本属性。 + + + + 要设置到选中节点的文本属性。 + + + 设置文本节点的选项，不包括 'at' 属性。 + + + +## 钩子 + +### useBlockSelectable + +一个提供使块元素可选择的属性的钩子，包括上下文菜单行为。 + + + + 要传播到块元素的属性： + + + `'slate-selectable'` - 选择功能所需的类 + + + 处理右键上下文菜单行为： + - 为选中的块打开上下文菜单 + - 为 void 元素打开 + - 为带有 `data-plate-open-context-menu="true"` 的元素打开 + - 使用 Shift 键进行多选时添加块到选择 + + + + + +### useBlockSelected + +如果上下文块被选中则返回 true。 + +### useBlockSelectionNodes + +返回当前选中块的节点entry数组。 + +### useBlockSelectionFragment + +返回当前选中块的节点数组。 + +### useBlockSelectionFragmentProp + +返回当前选中块的片段属性。 + +### useSelectionArea + +一个初始化和管理选择区域功能的钩子。 diff --git a/apps/www/content/docs/cn/callout.mdx b/apps/www/content/docs/cn/callout.mdx new file mode 100644 index 0000000000..14240cadd9 --- /dev/null +++ b/apps/www/content/docs/cn/callout.mdx @@ -0,0 +1,142 @@ +--- +title: Callout +docs: + - route: https://pro.platejs.org/docs/components/callout-element + title: Callout Element +--- + + + +## 功能 + +- 可自定义的标注块，用于突出显示重要信息 +- 支持不同的标注变体（例如：信息、警告、错误） +- 能够为标注设置自定义图标或表情符号 + + + +## 安装 + +```bash +npm install @udecode/plate-callout +``` + +## 使用 + +```tsx +import { CalloutPlugin } from '@udecode/plate-callout/react'; +``` + +```tsx +const plugins = [ + // ...otherPlugins, + CalloutPlugin, +] +``` + +```tsx +const components = { + // ...otherComponents, + [CalloutPlugin.key]: CalloutElement, +} +``` + +- [CalloutElement](https://pro.platejs.org/docs/components/callout-element) (Plus) + +## 示例 + +### Plate UI + +Work in progress. + +### Plate Plus + + + +## 插件 + +### CalloutPlugin + +标注元素插件。 + +## Transforms + +### editor.tf.insert.callout + +插入标注元素。 + + + + 编辑器实例。 + + + 插入标注的选项。 + + + 要插入的标注变体。 + + + 来自 `InsertNodesOptions` 的其他选项。 + + + + + +## Hooks + +### useCalloutEmojiPicker + +此钩子管理标注的表情选择器功能。 + + + + 标注表情选择器的选项。 + + + 表情选择器是否打开。 + + + 设置表情选择器打开状态的函数。 + + + + + + + + 表情工具栏下拉菜单的属性。 + + + 表情选择器是否打开。 + + + 设置表情选择器打开状态的函数，会遵循只读模式。 + + + + + 表情选择器组件的属性。 + + + 表情选择器是否打开。 + + + 设置表情选择器打开状态的函数。 + + + 选择表情时调用的函数。它会更新标注的图标并关闭选择器。 + + + + + +## Types + +### TCalloutElement + +```typescript +interface TCalloutElement extends TElement { + variant?: string; + icon?: string; +} +``` diff --git a/apps/www/content/docs/cn/caption.mdx b/apps/www/content/docs/cn/caption.mdx new file mode 100644 index 0000000000..a64ed37e38 --- /dev/null +++ b/apps/www/content/docs/cn/caption.mdx @@ -0,0 +1,155 @@ +--- +title: Caption +docs: + - route: /docs/components/caption + title: Caption +--- + + + + + +## 功能 + +- 箭头导航应选择块内的标题。 + + + +## 安装 + +```bash +npm install @udecode/plate-caption +``` + +## 使用 + +```tsx +import { CaptionPlugin } from '@udecode/plate-caption/react'; +import { + AudioPlugin, + FilePlugin, + ImagePlugin, + MediaEmbedPlugin, + VideoPlugin, +} from '@udecode/plate-media/react'; +``` + +```tsx +const plugins = [ + // ...otherPlugins, + ImagePlugin, + VideoPlugin, + AudioPlugin, + FilePlugin, + MediaEmbedPlugin, + CaptionPlugin.configure({ + options: { + plugins: [ + ImagePlugin, + VideoPlugin, + AudioPlugin, + FilePlugin, + MediaEmbedPlugin, + ], + }, + }), +]; +``` + +## 插件 + +### CaptionPlugin + + + + 具有标题的块的插件键。 + + + 聚焦到标题末尾的路径。 + + + 聚焦到标题开头的路径。 + + + 可见标题的 ID。 + + + 标题是否可见。 + + + +## API + +### TCaptionElement + + +扩展 `TElement`. + + +标题值。 + + + +## API Components + +### Caption + + + + + + 标题组件是否处于只读模式。 + + + + + + + 标题字符串。 + + + 标题组件是否被选中。 + + + 标题组件是否处于只读模式。 + + + + + +### CaptionTextarea + + + + + + 标题组件关联的 `textarea` 元素的引用。 + + + 标题组件显示的 `textarea` 的值。 + + + `captionValue` 设置器。 + + + 标题组件是否处于只读模式。 + + + 标题元素。 + + + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/collaboration.mdx b/apps/www/content/docs/cn/collaboration.mdx new file mode 100644 index 0000000000..3e7d3e95db --- /dev/null +++ b/apps/www/content/docs/cn/collaboration.mdx @@ -0,0 +1,156 @@ +--- +title: Collaboration +--- + + + +**Backend Development in Progress** - Demo Unavailable. + + + + + +## 功能 + +- yjs 插件支持使用 [slate-yjs](https://docs.slate-yjs.dev/) 和 [Hocuspocus](https://docs.slate-yjs.dev/walkthroughs/collaboration-hocuspocus) 进行协作。 +- 默认情况下，远程光标不会渲染，除非你安装了远程光标覆盖并将其包含在配置中。 +- 光标渲染时稍微淡化，悬停时变为实色。使用 `cursorOptions` 中的 `data` 字段自定义显示名称和颜色。 + + + +## Frontend + +### 安装 + +```bash +npm install @udecode/plate-yjs +``` + +### 使用 + +```tsx +import { YjsPlugin } from '@udecode/plate-yjs/react'; +import { RemoteCursorOverlay } from '@/components/plate-ui/remote-cursor-overlay'; + +const editor = createPlateEditor({ + plugins: [ + // ...otherPlugins, + YjsPlugin.configure({ + render: { + afterEditable: RemoteCursorOverlay, + }, + options: { + cursorOptions: { + autoSend: true, + data: { name: 'A plate user', color: '#5AC990' }, + }, + disableCursors: false, + hocuspocusProviderOptions: { + url: 'https://hocuspocus.test/hocuspocus', + name: 'test', + }, + }, + }), + ], +}); +``` + +### Editor Container + +编辑器需要一个容器组件，确保光标覆盖正确： + +```tsx +export const EditorContainer = ( + props: React.HTMLAttributes +) => { + const editor = useEditorRef(); + const containerRef = useEditorContainerRef(); + + return
; +}; +``` + +这个组件在 [Editor](/docs/components/editor) 中可用。 + +## 后端 + +请参阅 [Hocuspocus 文档](https://tiptap.dev/hocuspocus/getting-started) 中的后端说明。 + +## 插件 + +### YjsPlugin + + + +处理光标的配置。这些选项传递给 `withCursors` 函数。 + +- [WithCursorsOptions API](https://docs.slate-yjs.dev/api/slate-yjs-core/cursor-plugin#withcursors). + + + +Hocuspocus provider的配置。 + +- [HocuspocusProviderConfiguration API](https://tiptap.dev/hocuspocus/provider/configuration). + + + +Yjs 集成的可选配置。这些选项传递给 `withYjs` 函数。 + +- [WithYjsOptions API](https://docs.slate-yjs.dev/api/slate-yjs-core/yjs-plugin#withyjs). + + + +是否禁用光标功能。 + + + +## API + +### useYjsStore + + + + 编辑器是否连接到 Hocuspocus 服务器。 + + + 编辑器是否与 Hocuspocus 服务器同步。 + + + +### withTYjs + +一个高阶函数，用于将 Plate 编辑器与 Yjs 支持结合，允许实时协作编辑。 + +### PlateYjsEditorProps + + + +扩展 `YjsEditorProps` 和 [CursorEditor](https://docs.slate-yjs.dev/api/slate-yjs-core/cursor-plugin#cursoreditor). + + + + + + + +Hocuspocus provider 实例。 + + + + + + + + + +### YHistoryEditorProps + +扩展 `YjsEditorProps`, [YHistoryEditor](https://docs.slate-yjs.dev/api/slate-yjs-core/history-plugin#yhistoryeditor). + +### YjsEditorProps + +[YjsEditor API](https://docs.slate-yjs.dev/api/slate-yjs-core/yjs-plugin#yjseditor). diff --git a/apps/www/content/docs/cn/column.mdx b/apps/www/content/docs/cn/column.mdx new file mode 100644 index 0000000000..4ca07f65cd --- /dev/null +++ b/apps/www/content/docs/cn/column.mdx @@ -0,0 +1,181 @@ +--- +title: Column +docs: + - route: /docs/components/column-element + title: Column Element + - route: /docs/components/column-group-element + title: Column Group Element +--- + + + + + +## Features + +- 向文档添加列。 +- 使用 `column-group-element` 工具栏选择多种列布局。 +- [ ] 可调整列大小 + + + +## Installation + +```bash +npm install @udecode/plate-layout +``` + +## Usage + +```tsx +import { ColumnPlugin, ColumnItemPlugin } from '@udecode/plate-layout/react'; + +const plugins = [ + // ...otherPlugins, + ColumnPlugin, +]; +``` + +## Plugins + +### ColumnPlugin + +向文档添加列插件。 + +### ColumnItemPlugin + +向文档添加列项插件。 + +## API + +### TColumnGroupElement + + +Extends `TElement`. + + + +### TColumnElement + + +Extends `TElement`. + + + 列宽度以 `%` 结尾。 + + + +### insertColumnGroup + +插入一个包含两个空列的列组。 + + + + 编辑器实例。 + + + - `columns`: 列宽度数组或等宽列数（默认：2） + - 其他 `InsertNodesOptions` 以控制插入行为 + + + +### insertColumn + +插入一个空列。你可以通过 `options.width` 设置宽度，默认是 "33%"。 + + + + 编辑器实例。 + + + 插入行为和宽度设置。 + + + +### moveMiddleColumn + +将中间列向左或向右移动，通过 `options.direction` 设置。如果中间节点为空，返回 false 并删除它。 + + + + 编辑器实例。 + + + 列元素的节点入口。 + + + 控制中间列的移动方向。 + + + +### toggleColumnGroup + +将一个块转换为列组布局或更新现有列组的布局。 + + + + 编辑器实例。 + + + + + 切换列组的位置。 + + + 创建等宽列的数量（默认：2） + + + 列宽度数组（例如：['50%', '50%']）。优先级高于 `columns`。 + + + + + +行为： +- 如果目标块不是列组，则将其包裹在新的列组中，并使用指定的列数 +- 如果目标块已经是列组，则使用 `setColumns` 更新其列布局 +- 原始内容成为第一个列的内容 +- 额外的列创建为空段落 + +### setColumns + +更新现有列组的列布局，通过修改列数和宽度。 + + + + The editor instance. + + + + + The path to the column group element. + + + Number of equal-width columns to create. + + + Array of column widths (e.g., ['33%', '67%']). Takes precedence over `columns`. + + + + + +行为： +- 增加列数时： + - 保留现有列内容 + - 添加新空列，指定宽度 +- 减少列数时： + - 将删除列的内容合并到剩余列中 + - 更新剩余列的宽度 +- 保持相同数量的列时： + - 仅更新列宽度 + +## API Components + +### useDebouncePopoverOpen + + + +控制 `popover` 是否打开 + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/combobox.mdx b/apps/www/content/docs/cn/combobox.mdx new file mode 100644 index 0000000000..ac41df506a --- /dev/null +++ b/apps/www/content/docs/cn/combobox.mdx @@ -0,0 +1,219 @@ +--- +title: Combobox +docs: + - route: /docs/mention + title: Mention Plugin + - route: /docs/slash-command + title: Slash Command Plugin + - route: /docs/emoji + title: Emoji Plugin +--- + +`TriggerComboboxPluginOptions` 配置你的插件，当用户输入指定触发字符时插入一个组合框输入元素。 + +例如： +- [Mention](/docs/mention) 插件在输入 `@` 时插入组合框 +- [Slash Command](/docs/slash-command) 插件在输入 `/` 时激活 +- [Emoji](/docs/emoji) 插件在输入 `:` 时显示建议 + +## Usage + + + + +创建一个组合框输入插件： + +```ts +const ComboboxInputPlugin = createPlatePlugin({ + key: 'combobox_input', + node: { + isElement: true, + isInline: true, + isVoid: true, + }, +}); +``` + + + +创建你的主插件，使用 `withTriggerCombobox`： + +```ts +const MyPlugin = createPlatePlugin({ + key: 'my_plugin', + extendEditor: withTriggerCombobox, + // Plugin node options + node: { + isElement: true, + isInline: true, + isVoid: true, + }, + // Combobox options + options: { + createComboboxInput: (trigger) => ({ + children: [{ text: '' }], + trigger, + type: ComboboxInputPlugin.key, + }), + trigger: '@', + triggerPreviousCharPattern: /^\s?$/, + }, + // Include the input plugin + plugins: [ComboboxInputPlugin], +}); +``` + + + +输入元素组件可以使用 [Inline Combobox](/docs/components/inline-combobox) 构建。 + + + +## Examples + + + + + +## Types + +### TriggerComboboxPluginOptions + + + + 当触发器被激活时创建输入节点的函数。 + + + 触发组合框的字符。可以是： + - 单个字符（例如 '@'） + - 字符数组 + - 正则表达式 + + + 匹配触发字符前的字符模式。 + - **示例：** `/^\s?$/` 匹配行首或空格 + + + 自定义查询函数，用于控制触发器何时激活。 + + + +## Hooks + +### useComboboxInput + +用于管理组合框输入行为和键盘交互的 Hook。 + + + + + + 输入元素的引用。 + + + 挂载时自动聚焦输入框。 + - **默认值：** `true` + + + 在按下方向键时取消输入。 + - **默认值：** `true` + + + 在起始位置按下退格键时取消输入。 + - **默认值：** `true` + + + 在失焦时取消输入。 + - **默认值：** `true` + + + 在取消选择时取消输入。 + - **默认值：** `true` + + + 在按下 Escape 键时取消输入。 + - **默认值：** `true` + + + 当前光标位置状态。 + + + 将撤销/重做操作转发给编辑器。 + - **默认值：** `true` + + + 输入被取消时的回调函数。 + + + + + + + + 取消输入的函数。 + + + + + 失焦事件处理器。 + + + 按键事件处理器。 + + + + + 移除输入节点的函数。 + + + +Example: + +```tsx +const MyCombobox = () => { + const inputRef = useRef(null); + const cursorState = useHTMLInputCursorState(inputRef); + + const { props: inputProps, removeInput } = useComboboxInput({ + ref: inputRef, + cursorState, + cancelInputOnBlur: false, + onCancelInput: (cause) => { + if (cause !== 'backspace') { + insertText(editor, trigger + value); + } + if (cause === 'arrowLeft' || cause === 'arrowRight') { + moveSelection(editor, { + distance: 1, + reverse: cause === 'arrowLeft', + }); + } + }, + }); + + return ; +}; +``` + +### useHTMLInputCursorState + +用于跟踪 HTML 输入元素中光标位置的 Hook。 + + + + 要跟踪的输入元素的引用。 + + + + + + + + 光标是否在输入的起始位置。 + + + 光标是否在输入的末尾位置。 + + + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/comments.mdx b/apps/www/content/docs/cn/comments.mdx new file mode 100644 index 0000000000..72b75bba8c --- /dev/null +++ b/apps/www/content/docs/cn/comments.mdx @@ -0,0 +1,639 @@ +--- +title: Comments +docs: + - route: /docs/components/comment-leaf + title: Comment Leaf + - route: /docs/components/comment-toolbar-button + title: Comment Toolbar Button + - route: /docs/components/comments-popover + title: Comments Popover +--- + + + + + +## 功能 + +- 将文本注释添加为标记。 +- 注释可以包含解释、建议、问题、笔记或内容改进的想法。 +- 通过选择文本并使用注释按钮或快捷键 **`Cmd+Shift+M`** 添加注释。 + + + +## Installation + +```bash +npm install @udecode/plate-comments +``` + +## Usage + +```tsx +import { CommentsPlugin } from '@udecode/plate-comments/react'; + +const editor = createPlateEditor({ + plugins: [ + // ...otherPlugins, + CommentsPlugin, + ], +}); +``` + +## 键盘快捷键 + + + + 在选中的文本上添加注释。 + + + +## 插件 + +### CommentsPlugin + + + + +新注释的文本。 + + + +当前用户的信息。 + + + +通过 ID 获取用户的函数。 + + + +通过 ID 获取注释的函数。 + + + +当前活动的注释。 + + + + +## API + +### editor.tf.insert.comment + +插入新的注释标记。 + +### editor.api.comment.updateComment + +更新现有注释。 + +### editor.api.comment.addRawComment + +添加新的原始注释。 + +### editor.api.comment.addComment + +添加新注释。 + +### editor.api.comment.removeComment + +删除注释。 + +### editor.api.comment.resetNewCommentValue + +重置新注释的值。 + +### CommentStoreState + + + + 注释的唯一 ID。 + + + 表示与此注释关联的菜单当前是否打开的标志。 + + + 此注释当前正在编辑的值。如果没有正在进行的编辑，此值为 null。 + + + +### findCommentNode + +在编辑器中查找注释节点。 + + + + 编辑器实例。 + + + 查找节点的附加选项。 + + + +### findCommentNodeById + +通过 ID 在编辑器中查找注释节点。 + + + + 编辑器实例。 + + + 要查找的注释节点的 ID。 + + + +### getCommentCount + +获取注释节点中的注释数量。 + + + + 注释节点。 + + + +### getCommentKey + +根据提供的 ID 生成注释键。 + + + + 注释的 ID。 + + + +### getCommentKeyId + +从注释键中提取注释 ID。 + + + + 注释键。 + + + +### getCommentKeys + +返回给定节点中存在的注释键数组。 + + + + 要检查注释键的节点。 + + + +### getCommentNodeEntries + +返回编辑器中注释节点的节点entry数组。 + + + + 编辑器实例。 + + + +### getCommentNodesById + +返回编辑器中具有特定 ID 的注释节点的节点entry数组。 + + + + 编辑器实例。 + + + 要检索的注释节点的 ID。 + + + +### getCommentPosition + +计算注释节点相对于编辑器的位置。 + + + + 编辑器实例。 + + + 要计算位置的注释节点。 + + + +### getCommentUrl + +生成带有特定注释 ID 查询参数的 URL。 + + + + 注释的 ID。 + + + +### getElementAbsolutePosition + +计算 HTML 元素相对于文档的绝对位置。 + + + + 要计算绝对位置的 HTML 元素。 + + + +### isCommentKey + +检查给定的键是否是注释键。 + + + + 要检查的键。 + + + +### isCommentNodeById + +检查给定节点是否是具有指定 ID 的注释。 + + + + 要检查的节点。 + + + 注释的 ID。 + + + +### isCommentText + +检查给定节点是否是注释文本节点。 + + + + 要检查的节点。 + + + + + 如果节点是注释文本节点则返回 `true`。 + + +### removeCommentMark + +从编辑器中删除注释标记。 + + + + 编辑器实例。 + + + +### unsetCommentNodesById + +从编辑器中取消设置指定 ID 的注释节点。 + + + + 编辑器实例。 + + + 要取消设置的注释节点的 ID。 + + + +### CommentUser + +表示可以发表注释的用户的接口。 + + + + 用户的唯一 ID。 + + + 用户的名称。 + + + 用户头像的 URL。 + + + +### TComment + + + +注释的唯一 ID。 + + +注释的 Slate 值。 + + +注释创建的时间戳。 + +- **默认值：** `Date.now()` + + + +注释作者的 ID。 + + +回复的父注释的 ID。 + + +注释是否已解决。 + + + +### TCommentText + + + + 表示这是否是一个注释。单个文本节点中可以存在多个注释。 + + + +## API 组件 + +### CommentProvider + +注释数据的 jotai 提供者。 + + + 扩展 `CommentStoreState`。 + + + 提供者的作用域。 + + + +### CommentDeleteButton + +用于删除注释的按钮组件。 + + + + 活动注释的 ID。 + + + 编辑器实例。 + + + 注释的 ID。 + + + 注释被删除时调用的函数。 + + + 删除注释的函数。 + + + 设置活动注释 ID 的函数。 + + + +### CommentEditButton + +用于编辑注释的按钮组件。 + + + + 设置菜单打开状态的函数。 + + + 注释对象。 + + + 设置编辑值的函数。 + + + +### CommentEditCancelButton + +用于取消编辑注释的按钮组件。 + +### CommentEditSaveButton + +用于保存编辑注释的按钮组件。 + + + + 编辑值的值。 + + + 设置编辑值的函数。 + + + 注释的 ID。 + + + 注释更新时调用的函数。 + + + 更新注释的函数。 + + + 注释的值。 + + + +### CommentEditTextarea + +用于编辑注释的文本区域组件。 + + + + 设置编辑值的函数。 + + + 文本区域的引用。 + + + 文本区域的值。 + + + +### CommentNewSubmitButton + +用于提交新注释的按钮组件。 + + + + 正在编辑的注释文本。 + + + 重置新注释值的函数。 + + + 添加注释的函数。 + + + 注释是否是回复。 + + + 提交按钮的文本。 + + + 注释添加时调用的函数。 + + + 活动注释的 ID。 + + + 注释对象。 + + + 编辑的注释的值。 + + + +### CommentNewTextarea + +用于添加新注释的文本区域组件。 + + + + 文本区域的引用。 + + + 文本区域的占位符。 + + + 文本区域的值。 + + + 设置新值的函数。 + + + +### CommentResolveButton + +用于解决/取消解决注释的按钮组件。 + +### CommentUserName + +用于显示注释用户名称的 div 组件。 + +### CommentsPositioner + +用于在编辑器中定位注释的 div 组件。 + + + + 活动注释的 ID。 + + + 表示注释当前位置的对象（顶部和左侧坐标）。 + + + +### useActiveCommentNode + +基于活动注释 ID 检索活动注释节点的自定义钩子。 + + + +- 如果存在活动注释 ID，则返回相应的注释节点。 + +- 如果没有活动注释 ID 或找不到注释节点，则返回 `null`。 + + + +### useCommentAddButton + +提供向选定文本添加注释标记并将焦点设置到注释文本区域的功能的自定义钩子。 + + + + + + 按钮点击时调用的函数。 + + + + + +### useCommentItemContentState + +注释项内容组件的状态钩子。 + + + + 注释对象。 + + + 表示注释是否是回复注释的布尔值。 + + + 注释的文本内容。 + + + 与注释关联的用户。 + + + 当前用户的 ID。 + + + 正在编辑的注释的值。 + + + 表示注释是否由当前用户创作的布尔值。 + + + +### useCommentLeaf + +注释叶子组件的行为钩子。 + + + + 设置活动注释 ID 的函数。 + + + 叶子中最后一个注释的 ID。 + + + + + + + + 按钮点击时调用的函数。 + + + + + +### useCommentValue + +聚焦并选择文本区域内文本的自定义钩子。 + + + + 文本区域元素的引用。 + + + +### useCommentsResolved + +返回已解决注释数组的自定义钩子。 + + + + +已解决注释的数组。 + + + + +### useCommentsShowResolvedButton + +返回用于显示已解决注释的按钮组件属性的自定义钩子。 + + + + + + 表示按钮是否被按下的布尔值。 + + + 按钮点击时调用的函数。 + + + + \ No newline at end of file diff --git a/apps/www/content/docs/cn/components/changelog.mdx b/apps/www/content/docs/cn/components/changelog.mdx new file mode 100644 index 0000000000..dc4c05df4d --- /dev/null +++ b/apps/www/content/docs/cn/components/changelog.mdx @@ -0,0 +1,632 @@ +--- +title: Changelog +description: 最新组件更新和公告。 +toc: true +--- + +由于 Plate UI 不是一个组件库，因此在此维护更新日志。 + +使用 [CLI](https://platejs.org/docs/components/cli) 安装最新版本的组件。 + +## 2024年12月 #17 + + +### 12月25日 #17.6 + +- `indent-list-toolbar-button`: 移除 `IndentListToolbarButton`，改用 `NumberedIndentListToolbarButton` 和 `BulletedIndentListToolbarButton`。 +- `table-dropdown-menu`: 新的插入表格界面。 + +### 12月23日 #17.5 + +- `table-element`: 修复选择 +- 修改前: `isSelectingCell && '[&_*::selection]:bg-none'` +- 修改后: `isSelectingCell && '[&_*::selection]:!bg-transparent'` + + +### 12月21日 #17.4 + +更新 `tailwind.config.cjs` 以提供更好的 HTML 导出字体支持： + +```ts +fontFamily: { + heading: [ + 'var(--font-heading)', + 'ui-sans-serif', + '-apple-system', + 'BlinkMacSystemFont', + 'Segoe UI Variable Display', + 'Segoe UI', + 'Helvetica', + 'Apple Color Emoji', + 'Arial', + 'sans-serif', + 'Segoe UI Emoji', + 'Segoe UI Symbol', + 'Noto Color Emoji', + ], + mono: ['var(--font-mono)', ...fontFamily.mono], + sans: [ + 'var(--font-sans)', + 'ui-sans-serif', + '-apple-system', + 'BlinkMacSystemFont', + 'Segoe UI Variable Display', + 'Segoe UI', + 'Helvetica', + 'Apple Color Emoji', + 'Arial', + 'sans-serif', + 'Segoe UI Emoji', + 'Segoe UI Symbol', + 'Noto Color Emoji', + ], +``` + +### 12月20日 #17.3 + +- `insertColumnGroup`、`toggleColumnGroup`：使用 `columns` 选项替代 `layout` +- 移除 `with-draggables`。将 [`DraggableAboveNodes`](https://github.com/udecode/plate/pull/3878/files#diff-493c12ebed9c3ef9fd8c3a723909b18ad439a448c0132d2d93e5341ee0888ad2) 添加到 `draggable`。添加到 `DndPlugin` 配置中： +```tsx +DndPlugin.configure({ render: { aboveNodes: DraggableAboveNodes } }), +``` +- `column-element`、`image-element`、`media-video-element`：移除 `useDraggableState`。使用 `const { isDragging, previewRef, handleRef } = useDraggable` +- `column-group-element`：移除 `useColumnState`。改用： +```tsx +const columnGroupElement = useElement(ColumnPlugin.key); + +const onColumnChange = (widths: string[]) => { + setColumns(editor, { + at: findNodePath(editor, columnGroupElement), + widths, + }); +}; +``` +- `export-toolbar-button`: 增加 `exportToHtml` + +### 12月19日 #17.2 + +Plate 41 + +- 为元素和叶子组件新增 RSC 组件，文件名以 `-static.tsx` 结尾。这些组件现在与默认的客户端组件一起添加。 +- `editor`: 在 `editorVariants` 中添加 `select-text` +- `date-element`: 在只读模式下移除弹出框 +- `indent-todo-marker`: 使用 `SlateRenderElementProps` 类型替代 `PlateRenderElementProps` +- `hr-element`, `media-audio-element`, `media-embed-element`, `mention-element`: 改进光标样式 +- `media-file-element`: 使用 `` 替代 `div` + `onClick` +- 所有元素和叶子组件：`className` 属性现在放置在内联属性之前。 + +### 12月16日 #17.1 + +- `column-element`: + - 添加列的拖放支持 + - 添加带工具提示的拖动手柄 + - 修复列间距和内边距 + +- `column-group-element`: + - 移除列之间的间隙 + - 移除顶部外边距 + +- `draggable`: + - 移除 `DraggableProvider` HOC + - 移除 `DropLine` 子属性 + +## 2024年11月 #16 + +### 11月26日 #16.9 + +https://github.com/udecode/plate/pull/3809/files +- 添加 `select-editor`, `tag-element`, `label`, `form` +- 使用 `@udecode/cmdk` 替换 `cmdk` 依赖。这是一个可控版本的 `cmdk`。 +- `command`: 添加变体 +- `editor`: 添加 `select` 变体 +- `popover`: 添加 `animate` 变体 + +https://github.com/udecode/plate/pull/3807/files +- `toc-element`: 移除 `