║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

---

title: 链接 docs:

• route: /docs/components/link-node title: 链接元素
• route: /docs/components/link-toolbar title: 链接浮动工具栏
• route: /docs/components/link-toolbar-button title: 链接工具栏按钮

---

<ComponentPreview name="link-demo" /> <PackageInfo>

功能特性

• 支持超链接的插入、编辑和删除。

</PackageInfo>

套件使用

<Steps>

安装

最快捷添加链接功能的方式是使用 LinkKit，它包含预配置的 LinkPlugin 以及浮动工具栏和 Plate UI 组件。

<ComponentSource name="link-kit" />

• LinkElement: 渲染链接元素
• LinkFloatingToolbar: 提供链接编辑的浮动工具栏

添加套件

将套件添加到插件中：

import { createPlateEditor } from 'platejs/react';
import { LinkKit } from '@/components/editor/plugins/link-kit';

const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    ...LinkKit,
  ],
});

</Steps>

手动配置

<Steps>

安装

npm install @platejs/link

添加插件

在创建编辑器时，将 LinkPlugin 包含到 Plate 插件数组中。

import { LinkPlugin } from '@platejs/link/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    LinkPlugin,
  ],
});

配置插件

使用浮动工具栏和自定义组件配置插件。

import { LinkPlugin } from '@platejs/link/react';
import { createPlateEditor } from 'platejs/react';
import { LinkElement } from '@/components/ui/link-node';
import { LinkFloatingToolbar } from '@/components/ui/link-toolbar';

const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    LinkPlugin.configure({
      render: {
        node: LinkElement,
        afterEditable: () => <LinkFloatingToolbar />,
      },
    }),
  ],
});

• render.afterEditable: 在可编辑区域后渲染 LinkFloatingToolbar 用于链接编辑
• render.node: 指定 LinkElement 来渲染链接元素

添加工具栏按钮

您可以在工具栏中添加 LinkToolbarButton 来插入和编辑链接。

</Steps>

键盘快捷键

<KeyTable> <KeyTableItem hotkey="Cmd + K">在选中文本上添加链接</KeyTableItem> </KeyTable>

插件

LinkPlugin

链接格式化插件。

<API name="LinkPlugin"> <APIOptions type="object"> <APIItem name="forceSubmit" type="boolean" optional> 决定是否强制提交链接表单。 </APIItem> <APIItem name="rangeBeforeOptions" type="RangeBeforeOptions" optional> 允许自定义 rangeBeforeOptions 配置。 - **默认值:** ```ts { matchString: ' ', skipInvalid: true, afterMatch: true, } ``` </APIItem> <APIItem name="triggerFloatingLinkHotkeys" type="string | string[]" optional> 触发浮动链接的热键。 - **默认值:** **`'meta+k, ctrl+k'`** </APIItem> <APIItem name="allowedSchemes" type="string[]" optional> 允许的URL协议列表。 - **默认值:** **`['http', 'https', 'mailto', 'tel']`** </APIItem> <APIItem name="dangerouslySkipSanitization" type="boolean" optional> 决定是否跳过链接的消毒处理。 - **默认值:** **`false`** </APIItem> <APIItem name="defaultLinkAttributes" type="AnchorHTMLAttributes&lt;HTMLAnchorElement&gt;" optional> 链接元素的默认HTML属性。 - **默认值:** **`{}`** </APIItem> <APIItem name="keepSelectedTextOnPaste" type="boolean" optional> 粘贴链接时默认保留选中文本。 - **默认值:** **`true`** </APIItem> <APIItem name="isUrl" type="(text: string) => boolean" optional> 验证URL的回调函数。 - **默认值:** **`isUrl`** </APIItem> <APIItem name="getUrlHref" type="(url: string) => string | undefined" optional> 可选获取URL href的回调函数。返回与文本内容不同的可选链接。例如，为 `google.com` 返回 `https://google.com`。 </APIItem> <APIItem name="transformInput" type="(url: string | null) => string | undefined" optional> 在验证前可选转换用户提交的URL输入的回调函数。 </APIItem> <APIItem name="getLinkUrl" type="(prevUrl: string | null) => Promise<string | null>" optional> 当使用键盘快捷键或工具栏鼠标按下时，调用此函数获取链接URL。默认行为是使用浏览器的原生 `prompt`。 </APIItem> </APIOptions> </API>

转换操作

tf.insert.link

向编辑器中插入链接节点。

<API name="insert.link"> <APIParameters> <APIItem name="options" type="object"> 插入链接的选项。 </APIItem> </APIParameters> <APIOptions type="InsertLinkOptions"> <APIItem name="createLinkNodeOptions" type="CreateLinkNodeOptions"> 创建链接节点的选项。 </APIItem> <APIItem name="insertOptions" type="InsertNodesOptions" optional> 插入节点的附加选项。 </APIItem> </APIOptions> </API>

API

api.floatingLink.hide

隐藏浮动链接并重置其状态。

api.floatingLink.reset

重置浮动链接状态但不改变 openEditorId。

api.floatingLink.show

为指定模式和编辑器ID显示浮动链接。

<API name="floatingLink.show"> <APIParameters> <APIItem name="mode" type="FloatingLinkMode"> 设置浮动链接的模式（'edit' 或 'insert'）。 </APIItem> <APIItem name="editorId" type="string"> 应显示浮动链接的编辑器ID。 </APIItem> </APIParameters> </API>

api.link.getAttributes

获取链接元素的属性。

<API name="link.getAttributes"> <APIParameters> <APIItem name="element" type="TLinkElement"> 要获取属性的链接元素。 </APIItem> </APIParameters> <APIReturns type="React.AnchorHTMLAttributes<HTMLAnchorElement>"> 链接元素的HTML属性。 </APIReturns> </API>

api.link.submitFloatingLink

如果URL有效则插入链接，关闭浮动链接并聚焦编辑器。

<APIReturns type="boolean"> 如果链接成功插入则返回 `true`。 </APIReturns>

insertLink

向编辑器中插入链接节点。

<API name="insertLink"> <APIParameters> <APIItem name="createLinkNodeOptions" type="CreateLinkNodeOptions"> 创建链接节点的选项。 </APIItem> <APIItem name="options" type="InsertNodesOptions" optional> 节点插入的附加选项。 </APIItem> </APIParameters> </API>

submitFloatingLink

如果URL有效则插入链接，关闭浮动链接并聚焦编辑器。

• 如果URL有效则插入链接
• 如果文本为空则使用URL作为文本
• 关闭浮动链接
• 聚焦编辑器

<API name="submitFloatingLink"> <APIReturns type="boolean"> 如果链接被插入则返回 `true`。 </APIReturns> </API>

triggerFloatingLink

触发浮动链接。

<API name="triggerFloatingLink"> <APIOptions type="object"> <APIItem name="focused" type="boolean" optional> 浮动链接是否应被聚焦。 </APIItem> </APIOptions> </API>

triggerFloatingLinkEdit

触发浮动链接编辑。

<API name="triggerFloatingLinkEdit"> <APIReturns type="boolean"> 如果链接被编辑则返回 `true`。 </APIReturns> </API>

triggerFloatingLinkInsert

触发浮动链接。以下情况不触发：

• 选择跨多个块
• 选择包含多个叶子节点
• 最低层级选择不是文本
• 选择包含链接节点

<API name="triggerFloatingLinkInsert"> <APIOptions type="TriggerFloatingLinkOptions"> <APIItem name="focused" type="boolean" optional> 浮动链接是否应被聚焦。 </APIItem> </APIOptions> <APIReturns type="boolean"> 如果链接被插入则返回 `true`。 </APIReturns> </API>

unwrapLink

解包链接节点。

<API name="unwrapLink"> <APIOptions type="UnwrapLinkOptions"> <APIItem name="split" type="boolean" optional> 如果为 `true`，当选择在链接内部时分割节点。 </APIItem> </APIOptions> </API>

upsertLink

插入或更新链接节点。行为取决于当前选择和选项：

• 如果选择在链接中或不是URL：
  • 当 insertTextInLink: true 时，在链接中插入URL作为文本
  • 否则，如果 text 为空，则设置为URL
  • 除非 skipValidation: true，否则验证URL
• 如果选择已展开或链接中 update: true：
  • 移除链接节点并获取链接文本
• 然后：
  • 插入带有更新URL和目标的链接节点
  • 如果提供 text，则替换链接文本

<API name="upsertLink"> <APIParameters> <APIItem name="options" type="UpsertLinkOptions"> 更新链接的选项。 </APIItem> </APIParameters> <APIOptions type="UpsertLinkOptions"> <APIItem name="url" type="string"> 链接的URL。 </APIItem> <APIItem name="text" type="string" optional> 链接的文本内容。 </APIItem> <APIItem name="target" type="string" optional> 链接的目标属性。 </APIItem> <APIItem name="insertTextInLink" type="boolean" optional> 如果为 `true`，在链接中插入URL作为文本。 </APIItem> <APIItem name="insertNodesOptions" type="InsertNodesOptions" optional> 插入节点的选项。 </APIItem> <APIItem name="skipValidation" type="boolean" optional> 如果为 `true`，跳过URL验证。 - **默认值:** `false` </APIItem> </APIOptions> <APIReturns type="boolean"> 如果链接被插入或更新则返回 `true`。 </APIReturns> </API>

upsertLinkText

如果文本与上方链接文本不同，则用新文本节点替换链接子节点。新文本节点具有与链接中第一个文本节点相同的标记。

<API name="upsertLinkText"> <APIOptions type="UpsertLinkTextOptions"> <APIItem name="text" type="string" optional> 用于替换链接子节点的新文本。 </APIItem> </APIOptions> </API>

validateUrl

根据插件选项验证URL。

<API name="validateUrl"> <APIOptions type="ValidateUrlOptions"> <APIItem name="url" type="string"> 要验证的URL。 </APIItem> </APIOptions> <APIReturns type="boolean"> 如果URL有效则返回 `true`。 </APIReturns> </API>

wrapLink

用分割方式包裹链接节点。

<API name="wrapLink"> <APIOptions type="WrapLinkOptions"> <APIItem name="url" type="string"> 链接的URL。 </APIItem> <APIItem name="target" type="string" optional> 链接的目标属性。 </APIItem> </APIOptions> </API>

CreateLinkNodeOptions

创建新链接节点的选项。

<API name="CreateLinkNodeOptions"> <APIOptions type="object"> <APIItem name="url" type="string"> 正在创建的链接节点的URL。 </APIItem> <APIItem name="text" type="string" optional> 链接节点显示的文本。如果未提供，则使用URL作为显示文本。 </APIItem> <APIItem name="target" type="string" optional> 指定打开URL的位置： - `_blank`: 新标签页 - `_self`: 相同框架 - `_parent`: 父框架 - `_top`: 整个窗口 </APIItem> <APIItem name="children" type="TText[]" optional> 表示链接内容的文本节点数组。 </APIItem> </APIOptions> </API>

API 组件

FloatingLinkNewTabInput

控制链接是否在新标签页中打开的输入组件。

<API name="FloatingLinkNewTabInput"> <APIState> <APIItem name="checked" type="boolean"> 链接是否应在新标签页中打开。 </APIItem> <APIItem name="setChecked" type="React.Dispatch<React.SetStateAction<boolean>>"> 更新选中状态的函数。 </APIItem> <APIItem name="ref" type="RefObject<HTMLInputElement>"> 输入元素的引用。 </APIItem> </APIState> </API>

FloatingLinkUrlInput

用于输入和编辑链接URL的输入组件。

<API name="FloatingLinkUrlInput"> <APIState> <APIItem name="ref" type="RefObject<HTMLInputElement>"> 输入元素的引用。 </APIItem> </APIState> </API>

LinkOpenButton

用于打开链接URL的按钮组件。

<API name="LinkOpenButton"> <APIState> <APIItem name="element" type="TLinkElement"> 包含要打开URL的链接元素。 </APIItem> </APIState> </API>

useFloatingLinkEdit

浮动链接编辑功能的行为钩子。

<API name="useFloatingLinkEdit"> <APIState> <APIItem name="floating" type="object" optional> 虚拟浮动返回对象。 </APIItem> </APIState> <APIReturns type="object"> <APIItem name="ref" type="function"> 浮动元素的引用回调。 </APIItem> <APIItem name="props" type="object"> 浮动元素的属性。 <APISubList> <APISubListItem parent="props" name="style" type="object"> 浮动链接的样式。 </APISubListItem> </APISubList> </APIItem> <APIItem name="editButtonProps" type="object"> 编辑按钮的属性。 <APISubList> <APISubListItem parent="editButtonProps" name="onClick" type="function"> 点击编辑按钮时调用的函数。 </APISubListItem> </APISubList> </APIItem> <APIItem name="unlinkButtonProps" type="object"> 取消链接按钮的属性。 <APISubList> <APISubListItem parent="unlinkButtonProps" name="onClick" type="function"> 点击取消链接按钮时调用的函数。 </APISubListItem> </APISubList> </APIItem> </APIReturns> </API>

useFloatingLinkEnter

监听Enter键按下事件并提交编辑器中的浮动链接。

useFloatingLinkEscape

监听Escape键按下事件并处理编辑器中浮动链接的行为。

useFloatingLinkInsert

插入链接的行为钩子。

<API name="useFloatingLinkInsert"> <APIState> <APIItem name="floating" type="ReturnType<typeof useFloatingLinkInsertState>"> 虚拟浮动返回对象。 </APIItem> <APIItem name="refClickOutside" type="React.Ref"> 浮动元素的引用。 </APIItem> </APIState> <APIReturns type="object"> <APIItem name="ref" type="function"> 浮动元素的引用回调。 </APIItem> <APIItem name="props" type="object"> 浮动元素的属性。 <APISubList> <APISubListItem parent="props" name="style" type="object"> 浮动链接的样式。 </APISubListItem> </APISubList> </APIItem> <APIItem name="textInputProps" type="object"> 文本输入的属性。 <APISubList> <APISubListItem parent="textInputProps" name="onChange" type="function"> 文本输入值变化时调用的函数。 </APISubListItem> <APISubListItem parent="textInputProps" name="defaultValue" type="string"> 文本输入的默认值。 </APISubListItem> </APISubList> </APIItem> </APIReturns> </API>

useLink

链接元素的行为钩子。

<API name="useLink"> <APIOptions type="UseLinkOptions"> <APIItem name="element" type="TLinkElement"> 链接元素。 </APIItem> </APIOptions> <APIReturns type="object"> <APIItem name="props" type="object"> 链接元素的属性。 <APISubList> <APISubListItem parent="props" name="onMouseOver" type="function"> 鼠标悬停在链接上时调用的函数。 </APISubListItem> </APISubList> </APIItem> </APIReturns> </API>

useLinkToolbarButton

链接工具栏按钮的行为钩子。

<API name="useLinkToolbarButton"> <APIState> <APIItem name="pressed" type="boolean"> 选择是否在链接中。 </APIItem> </APIState> <APIReturns type="object"> <APIItem name="props" type="object"> 工具栏按钮的属性。 <APISubList> <APISubListItem parent="props" name="pressed" type="boolean"> 链接是否被按下。 </APISubListItem> <APISubListItem parent="props" name="onClick" type="function"> 点击按钮时调用的函数。 </APISubListItem> </APISubList> </APIItem> </APIReturns> </API>

useVirtualFloatingLink

用于管理链接虚拟浮动的自定义钩子。

<API name="useVirtualFloatingLink"> <APIOptions type="object"> <APIItem name="editorId" type="string"> 链接所属编辑器的 ID。 </APIItem> <APIItem name="floatingOptions" type="UseVirtualFloatingOptions" optional> 虚拟浮动的选项。 </APIItem> </APIOptions> <APIReturns type="UseVirtualFloatingReturn"> `useVirtualFloating` 钩子的返回值。 </APIReturns> </API>

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║