链接

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

功能特性

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

套件使用

安装

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

'use client';

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

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

export const LinkKit = [
  LinkPlugin.configure({
    render: {
      node: LinkElement,
      afterEditable: () => <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 />,
      },
    }),
  ],
});

添加工具栏按钮

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

键盘快捷键

KeyDescription
Cmd + K在选中文本上添加链接

插件

LinkPlugin

链接格式化插件。

Optionsobject

Collapse all

    决定是否强制提交链接表单。

    允许自定义 rangeBeforeOptions 配置。

    • 默认值:
    {
  matchString: ' ',
  skipInvalid: true,
  afterMatch: true,
}

    触发浮动链接的热键。

    • 默认值: 'meta+k, ctrl+k'

    允许的URL协议列表。

    • 默认值: ['http', 'https', 'mailto', 'tel']

    决定是否跳过链接的消毒处理。

    • 默认值: false

    链接元素的默认HTML属性。

    • 默认值: {}

    粘贴链接时默认保留选中文本。

    • 默认值: true

    验证URL的回调函数。

    • 默认值: isUrl

    可选获取URL href的回调函数。返回与文本内容不同的可选链接。例如，为 google.com 返回 https://google.com。

    在验证前可选转换用户提交的URL输入的回调函数。

    当使用键盘快捷键或工具栏鼠标按下时，调用此函数获取链接URL。默认行为是使用浏览器的原生 prompt。

转换操作

tf.insert.link

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

Parameters

Collapse all

    插入链接的选项。

OptionsInsertLinkOptions

Collapse all

    创建链接节点的选项。

    插入节点的附加选项。

API

api.floatingLink.hide

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

api.floatingLink.reset

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

api.floatingLink.show

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

Parameters

Collapse all

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

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

api.link.getAttributes

获取链接元素的属性。

Parameters

Collapse all

    要获取属性的链接元素。

ReturnsReact.AnchorHTMLAttributes<HTMLAnchorElement>

Collapse all

    链接元素的HTML属性。

api.link.submitFloatingLink

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

Returnsboolean

Collapse all

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

insertLink

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

Parameters

Collapse all

    创建链接节点的选项。

    节点插入的附加选项。

submitFloatingLink

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

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

Returnsboolean

Collapse all

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

triggerFloatingLink

触发浮动链接。

Optionsobject

Collapse all

    浮动链接是否应被聚焦。

triggerFloatingLinkEdit

触发浮动链接编辑。

Returnsboolean

Collapse all

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

triggerFloatingLinkInsert

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

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

OptionsTriggerFloatingLinkOptions

Collapse all

    浮动链接是否应被聚焦。

Returnsboolean

Collapse all

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

unwrapLink

解包链接节点。

OptionsUnwrapLinkOptions

Collapse all

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

upsertLink

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

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

Parameters

Collapse all

    更新链接的选项。

OptionsUpsertLinkOptions

Collapse all

    链接的URL。

    链接的文本内容。

    链接的目标属性。

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

    插入节点的选项。

    如果为 true，跳过URL验证。

    • 默认值: false

Returnsboolean

Collapse all

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

upsertLinkText

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

OptionsUpsertLinkTextOptions

Collapse all

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

validateUrl

根据插件选项验证URL。

OptionsValidateUrlOptions

Collapse all

    要验证的URL。

Returnsboolean

Collapse all

    如果URL有效则返回 true。

wrapLink

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

OptionsWrapLinkOptions

Collapse all

    链接的URL。

    链接的目标属性。

CreateLinkNodeOptions

创建新链接节点的选项。

Optionsobject

Collapse all

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

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

    指定打开URL的位置：

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

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

API 组件

FloatingLinkNewTabInput

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

State

Collapse all

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

    更新选中状态的函数。

    输入元素的引用。

FloatingLinkUrlInput

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

State

Collapse all

    输入元素的引用。

LinkOpenButton

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

State

Collapse all

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

useFloatingLinkEdit

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

State

Collapse all

    虚拟浮动返回对象。

Returnsobject

Collapse all

    浮动元素的引用回调。

    浮动元素的属性。

    编辑按钮的属性。

    取消链接按钮的属性。

useFloatingLinkEnter

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

useFloatingLinkEscape

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

useFloatingLinkInsert

插入链接的行为钩子。

State

Collapse all

    虚拟浮动返回对象。

    浮动元素的引用。

Returnsobject

Collapse all

    浮动元素的引用回调。

    浮动元素的属性。

    文本输入的属性。

useLink

链接元素的行为钩子。

OptionsUseLinkOptions

Collapse all

    链接元素。

Returnsobject

Collapse all

    链接元素的属性。

useLinkToolbarButton

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

State

Collapse all

    选择是否在链接中。

Returnsobject

Collapse all

    工具栏按钮的属性。

useVirtualFloatingLink

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

Optionsobject

Collapse all

    链接所属编辑器的 ID。

    虚拟浮动的选项。

ReturnsUseVirtualFloatingReturn

Collapse all

    useVirtualFloating 钩子的返回值。

Horizontal RuleLink