链接

链接元素链接浮动工具栏链接工具栏按钮

功能特性

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

套件使用

安装

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

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

添加套件

将套件添加到插件中：

import { createPlateEditor } from 'platejs/react';
import { LinkKit } from '@/components/editor/plugins/link-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    ...LinkKit,
  ],
});

手动配置

安装


pnpm add @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 来插入和编辑链接。

键盘快捷键

Key	Description
`Cmd + K`	在选中文本上添加链接

插件

`LinkPlugin`

链接格式化插件。

Optionsobject

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

转换操作

`tf.insert.link`

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

Parameters

Collapse all

options object

插入链接的选项。

OptionsInsertLinkOptions

Collapse all

createLinkNodeOptions CreateLinkNodeOptions

创建链接节点的选项。

insertOptions optional InsertNodesOptions

插入节点的附加选项。

API

`api.floatingLink.hide`

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

`api.floatingLink.reset`

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

`api.floatingLink.show`

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

Parameters

Collapse all

mode FloatingLinkMode

设置浮动链接的模式（'edit' 或 'insert'）。

editorId string

应显示浮动链接的编辑器ID。

`api.link.getAttributes`

获取链接元素的属性。

Parameters

Collapse all

element TLinkElement

要获取属性的链接元素。

ReturnsReact.AnchorHTMLAttributes<HTMLAnchorElement>

链接元素的HTML属性。

`api.link.submitFloatingLink`

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

Returnsboolean

如果链接成功插入则返回 true。

`insertLink`

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

Parameters

Collapse all

createLinkNodeOptions CreateLinkNodeOptions

创建链接节点的选项。

options optional InsertNodesOptions

节点插入的附加选项。

`submitFloatingLink`

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

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

Returnsboolean

如果链接被插入则返回 true。

`triggerFloatingLink`

触发浮动链接。

Optionsobject

Collapse all

focused optional boolean

浮动链接是否应被聚焦。

`triggerFloatingLinkEdit`

触发浮动链接编辑。

Returnsboolean

如果链接被编辑则返回 true。

`triggerFloatingLinkInsert`

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

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

OptionsTriggerFloatingLinkOptions

Collapse all

focused optional boolean

浮动链接是否应被聚焦。

Returnsboolean

如果链接被插入则返回 true。

`unwrapLink`

解包链接节点。

OptionsUnwrapLinkOptions

Collapse all

split optional boolean

如果为 true，当选择在链接内部时分割节点。

`upsertLink`

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

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

Parameters

Collapse all

options UpsertLinkOptions

更新链接的选项。

OptionsUpsertLinkOptions

Collapse all

url string

链接的URL。

text optional string

链接的文本内容。

target optional string

链接的目标属性。

insertTextInLink optional boolean

如果为 true，在链接中插入URL作为文本。

insertNodesOptions optional InsertNodesOptions

插入节点的选项。

skipValidation optional boolean

如果为 true，跳过URL验证。

默认值: false

Returnsboolean

如果链接被插入或更新则返回 true。

`upsertLinkText`

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

OptionsUpsertLinkTextOptions

Collapse all

text optional string

用于替换链接子节点的新文本。

`validateUrl`

根据插件选项验证URL。

OptionsValidateUrlOptions

Collapse all

url string

要验证的URL。

Returnsboolean

如果URL有效则返回 true。

`wrapLink`

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

OptionsWrapLinkOptions

Collapse all

url string

链接的URL。

target optional string

链接的目标属性。

`CreateLinkNodeOptions`

创建新链接节点的选项。

Optionsobject

Collapse all

url string

正在创建的链接节点的URL。

text optional string

链接节点显示的文本。如果未提供，则使用URL作为显示文本。

target optional string

指定打开URL的位置：

_blank: 新标签页
_self: 相同框架
_parent: 父框架
_top: 整个窗口

children optional TText[]

表示链接内容的文本节点数组。

API 组件

`FloatingLinkNewTabInput`

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

State

Collapse all

checked boolean

链接是否应在新标签页中打开。

setChecked React.Dispatch<React.SetStateAction<boolean>>

更新选中状态的函数。

ref RefObject<HTMLInputElement>

输入元素的引用。

`FloatingLinkUrlInput`

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

State

Collapse all

ref RefObject<HTMLInputElement>

输入元素的引用。

`LinkOpenButton`

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

State

Collapse all

element TLinkElement

包含要打开URL的链接元素。

`useFloatingLinkEdit`

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

State

Collapse all

floating optional object

虚拟浮动返回对象。

Returnsobject

Collapse all

ref function

浮动元素的引用回调。

props object

浮动元素的属性。

editButtonProps object

编辑按钮的属性。

unlinkButtonProps object

取消链接按钮的属性。

`useFloatingLinkEnter`

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

`useFloatingLinkEscape`

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

`useFloatingLinkInsert`

插入链接的行为钩子。

State

Collapse all

floating ReturnType<typeof useFloatingLinkInsertState>

虚拟浮动返回对象。

refClickOutside React.Ref

浮动元素的引用。

Returnsobject

Collapse all

ref function

浮动元素的引用回调。

props object

浮动元素的属性。

textInputProps object

文本输入的属性。

`useLink`

链接元素的行为钩子。

OptionsUseLinkOptions

Collapse all

element TLinkElement

链接元素。

Returnsobject

Collapse all

props object

链接元素的属性。

`useLinkToolbarButton`

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

State

Collapse all

pressed boolean

选择是否在链接中。

Returnsobject

Collapse all

props object

工具栏按钮的属性。

`useVirtualFloatingLink`

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

Optionsobject

Collapse all

editorId string

链接所属编辑器的 ID。

floatingOptions optional UseVirtualFloatingOptions

虚拟浮动的选项。

ReturnsUseVirtualFloatingReturn

useVirtualFloating 钩子的返回值。

Horizontal Rule Link

链接

功能特性

套件使用

安装

添加套件

手动配置

安装

添加插件

配置插件

添加工具栏按钮

键盘快捷键

插件

LinkPlugin

Optionsobject

forceSubmit optional boolean

rangeBeforeOptions optional RangeBeforeOptions

triggerFloatingLinkHotkeys optional string | string[]

allowedSchemes optional string[]

dangerouslySkipSanitization optional boolean

defaultLinkAttributes optional AnchorHTMLAttributes<HTMLAnchorElement>

keepSelectedTextOnPaste optional boolean

isUrl optional (text: string) => boolean

getUrlHref optional (url: string) => string | undefined

transformInput optional (url: string | null) => string | undefined

getLinkUrl optional (prevUrl: string | null) => Promise<string | null>

转换操作

tf.insert.link

Parameters

options object

OptionsInsertLinkOptions

createLinkNodeOptions CreateLinkNodeOptions

insertOptions optional InsertNodesOptions

API

api.floatingLink.hide

api.floatingLink.reset

api.floatingLink.show

Parameters

mode FloatingLinkMode

editorId string

api.link.getAttributes

Parameters

element TLinkElement

ReturnsReact.AnchorHTMLAttributes<HTMLAnchorElement>

api.link.submitFloatingLink

Returnsboolean

insertLink

Parameters

createLinkNodeOptions CreateLinkNodeOptions

options optional InsertNodesOptions

submitFloatingLink

Returnsboolean

triggerFloatingLink

Optionsobject

focused optional boolean

triggerFloatingLinkEdit

Returnsboolean

triggerFloatingLinkInsert

OptionsTriggerFloatingLinkOptions

focused optional boolean

Returnsboolean

unwrapLink

OptionsUnwrapLinkOptions

split optional boolean

upsertLink

Parameters

options UpsertLinkOptions

OptionsUpsertLinkOptions

url string

text optional string

target optional string

insertTextInLink optional boolean

insertNodesOptions optional InsertNodesOptions

skipValidation optional boolean

Returnsboolean

upsertLinkText

OptionsUpsertLinkTextOptions

text optional string

validateUrl

OptionsValidateUrlOptions

url string

`LinkPlugin`

`tf.insert.link`

`api.floatingLink.hide`

`api.floatingLink.reset`

`api.floatingLink.show`

`api.link.getAttributes`

`api.link.submitFloatingLink`

`insertLink`

`submitFloatingLink`

`triggerFloatingLink`

`triggerFloatingLinkEdit`

`triggerFloatingLinkInsert`

`unwrapLink`

`upsertLink`

`upsertLinkText`

`validateUrl`

`wrapLink`

`CreateLinkNodeOptions`

`FloatingLinkNewTabInput`

`FloatingLinkUrlInput`

`LinkOpenButton`

`useFloatingLinkEdit`

`useFloatingLinkEnter`

`useFloatingLinkEscape`

`useFloatingLinkInsert`

`useLink`

`useLinkToolbarButton`

`useVirtualFloatingLink`