提及功能 - Plate

功能特性

智能自动补全，可用于提及用户、页面或任何引用
通过可配置字符触发（默认：@）
键盘导航与选择
可自定义的提及数据与渲染方式

</PackageInfo>

套件使用方式

<Steps>

安装

最快捷的添加提及功能方式是使用 MentionKit，它包含预配置的 MentionPlugin 和 MentionInputPlugin 以及它们的 Plate UI 组件。

MentionElement: 渲染提及元素
MentionInputElement: 渲染提及输入组合框

添加套件

tsx

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

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

</Steps>

手动配置方式

<Steps>

安装

bash

npm install @platejs/mention

添加插件

tsx

import { MentionPlugin, MentionInputPlugin } from '@platejs/mention/react';
import { createPlateEditor } from 'platejs/react';

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

配置插件

tsx

import { MentionPlugin, MentionInputPlugin } from '@platejs/mention/react';
import { createPlateEditor } from 'platejs/react';
import { MentionElement, MentionInputElement } from '@/components/ui/mention-node';

const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    MentionPlugin.configure({
      options: {
        trigger: '@',
        triggerPreviousCharPattern: /^$|^[\s"']$/,
        insertSpaceAfterMention: false,
      },
    }).withComponent(MentionElement),
    MentionInputPlugin.withComponent(MentionInputElement),
  ],
});

options.trigger: 触发提及组合框的字符
options.triggerPreviousCharPattern: 触发字符前一个字符的正则表达式模式。套件使用 /^$|^[\s"']$/ 允许在行首、空白符后或引号后触发提及
options.insertSpaceAfterMention: 是否在插入提及后自动添加空格
withComponent: 分配用于渲染提及和提及输入的UI组件

</Steps>

插件说明

MentionPlugin

提供提及功能的插件。扩展自 TriggerComboboxPluginOptions。

<API name="MentionPlugin"> <APIOptions> <APIItem name="insertSpaceAfterMention" type="boolean" optional> 是否在提及后插入空格。 - **默认值:** `false` </APIItem> <APIItem name="trigger" type="string" optional> 触发提及组合框的字符。 - **默认值:** `'@'` </APIItem> <APIItem name="triggerPreviousCharPattern" type="RegExp" optional> 匹配触发字符前一个字符的模式。 - **默认值:** `/^\s?$/` </APIItem> <APIItem name="createComboboxInput" type="(trigger: string) => TElement" optional> 当触发字符激活时创建输入元素的函数。 </APIItem> </APIOptions> </API>

MentionInputPlugin

提供提及输入功能的插件。

API接口

api.insert.mention

在当前选区插入提及元素。

<API name="api.insert.mention"> <APIParameters> <APIItem name="options" type="object"> <APISubList> <APISubListItem parent="options" name="search" type="string"> 触发提及的搜索文本。 </APISubListItem> <APISubListItem parent="options" name="value" type="any"> 存储在提及元素中的值。 </APISubListItem> <APISubListItem parent="options" name="key" type="any" optional> 提及元素的可选键值。 </APISubListItem> </APISubList> </APIItem> </APIParameters> </API>

getMentionOnSelectItem

获取处理提及组合框项选择的处理器。

<API name="getMentionOnSelectItem"> <APIOptions> <APIItem name="key" type="string" optional> 提及插件的插件键。 - **默认值:** `MentionPlugin.key` </APIItem> </APIOptions> <APIReturns> 处理提及项选择的函数。 </APIReturns> </API>