syncfusion-react-mention

用途

Syncfusion React Mention（MentionComponent）用于在可编辑内容区域中实现 @ 提及功能，即在输入触发字符（默认 @）时弹出建议列表，供用户选择并内联插入到编辑器中。适用于评论框、编辑器等需要 @ 标记用户或条目的场景。

主要能力

挂载到目标可编辑元素（如 <div contenteditable>），通过 target 属性指定 CSS 选择器或元素。
支持自定义触发字符（mentionChar），并可控制是否在输出中显示触发字符（showMentionChar）。
数据绑定：支持字符串数组、JSON 对象、复杂嵌套数据，以及通过 ODataV4Adaptor、WebApiAdaptor 绑定远程数据，可用 query 过滤/选择远程字段。
字段映射：text、value、groupBy、iconCss。
过滤：可设置最小过滤字符长度（minLength）、过滤类型（Contains、StartsWith、EndsWith）、允许搜索文本含空格（allowSpaces）、建议数量（suggestionCount）、防抖延迟（debounceDelay）。
模板：条目模板（itemTemplate）、显示模板（displayTemplate）、无记录模板（noRecordsTemplate）、加载模板（spinnerTemplate）、分组头模板（groupTemplate）。
自定义：后缀文本（suffixText）、弹窗高度与宽度（popupHeight、popupWidth）、前导空格要求（requireLeadingSpace）、CSS 类（cssClass）、高亮匹配字符（highlight）、忽略重音/大小写（ignoreAccent、ignoreCase）、弹窗 z-index（zIndex）。
排序：升序、降序、无。
禁用项：通过 fields.disabled 或 disableItem() 方法动态禁用。
无障碍：WAI-ARIA 属性、键盘导航、WCAG 2.2 与 Section 508 合规、RTL 支持（enableRtl）。
本地化：通过 L10n 本地化无记录模板文本，设置 locale 属性。
API：提供属性、方法（addItem、disableItem、getDataByValue、getItems、showPopup、hidePopup、search、destroy）与事件（select、change、filtering、beforeOpen、opened、closed、dataBound、actionBegin、actionComplete、actionFailure）。

使用方式

安装包 @syncfusion/ej2-react-dropdowns 并引入 CSS 主题。基本用法：

import { MentionComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

// CSS imports
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

function App() {
  const mentionTarget = '#commentBox';
  const users = [
    { Name: 'Selma Rose', EmailId: 'selma@example.com' },
    { Name: 'Robert', EmailId: 'robert@example.com' },
    { Name: 'William', EmailId: 'william@example.com' },
  ];
  const fields = { text: 'Name' };

  return (
    <div>
      <label>Comments</label>
      <div id="commentBox" placeholder="Type @ to mention a user"></div>
      <MentionComponent
        target={mentionTarget}
        dataSource={users}
        fields={fields}
      />
    </div>
  );
}

export default App;

自定义触发字符示例：

<MentionComponent
  target="#editor"
  dataSource={tags}
  mentionChar="#"
  showMentionChar={true}
/>

远程数据与过滤示例：

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';

// NOTE: Replace the URL below with your own API endpoint.
// Do not use third-party or public endpoints in production.
const dataSource = new DataManager({
  url: 'https://your-api-endpoint.example.com/odata/',
  adaptor: new ODataV4Adaptor,
  crossDomain: true,
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { text: 'ContactName', value: 'CustomerID' };

<MentionComponent
  target="#editor"
  dataSource={dataSource}
  fields={fields}
  query={query}
  minLength={2}
  popupWidth="250px"
/>

选择事件处理示例：

import { SelectEventArgs } from '@syncfusion/ej2-react-dropdowns';

function onSelect(args: SelectEventArgs) {
  console.log('Selected item:', args.itemData);
  console.log('Selected text:', args.text);
}

<MentionComponent
  target="#editor"
  dataSource={users}
  fields={{ text: 'Name' }}
  select={onSelect}
/>

弹窗配置示例：

<MentionComponent
  target="#editor"
  dataSource={data}
  fields={{ text: 'Name' }}
  popupHeight="200px"
  popupWidth="300px"
  suggestionCount={10}
  sortOrder="Ascending"
  suffixText="&nbsp;"
/>

关键属性摘要：

属性	类型	默认值	用途
target	string\|HTMLElement	—	可编辑区域的 CSS 选择器或元素
dataSource	array\|DataManager	[]	建议数据
fields	FieldSettingsModel	{text:null,value:null}	映射数据字段
mentionChar	string	'@'	触发字符
showMentionChar	boolean	false	在插入文本前添加触发字符
minLength	number	0	搜索前最小字符数
suggestionCount	number	25	弹窗中最大条目数
filterType	FilterType	'Contains'	过滤匹配策略
allowSpaces	boolean	false	允许搜索中含空格
sortOrder	SortOrder	'None'	排序方向
popupHeight	string\|number	'300px'	弹窗高度
popupWidth	string\|number	'auto'	弹窗宽度
suffixText	string	null	选择后追加的文本
requireLeadingSpace	boolean	true	触发字符前是否需要空格
highlight	boolean	false	高亮搜索字符

适用场景

评论框、编辑器中的 @ 提及用户或条目。
需要从本地或远程数据源提供建议列表的输入场景。
需要自定义触发字符、模板、过滤策略、排序与无障碍支持的 React 应用。

限制与注意事项

安装 npm 包（@syncfusion/ej2-react-dropdowns 及相关）必须是用户确认的步骤。不要让自动化代理在未经用户明确批准的情况下运行 npm install，这会引入供应链风险。
远程数据示例中的 URL 需替换为自己的 API 端点，不要在生产环境使用第三方或公共端点。
关于收费、价格、平台支持范围等具体信息，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项