syncfusion-react-mention

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion React Mention Component

Syncfusion React Mention 组件

The Syncfusion React

MentionComponent

attaches to a target editable element (e.g. a

<div contenteditable>

) and displays a suggestion popup when the user types a trigger character (default

). Selecting an item inserts it inline into the editor.

Syncfusion React

MentionComponent

会绑定到目标可编辑元素（例如

<div contenteditable>

），当用户输入触发字符（默认是

）时会展示建议弹窗。选中条目后会将其插入到编辑器的对应位置。

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and package setup (
```
@syncfusion/ej2-react-dropdowns
```
)
CSS theme imports
Basic
```
MentionComponent
```
setup with
```
target
```
prop
Binding a simple data source
Custom trigger character (
```
mentionChar
```
) and
```
showMentionChar
```

⚠️ Security Note: Installing npm packages (
@syncfusion/ej2-react-dropdowns
and related) must be a deliberate, user-confirmed step. Do not allow automated agents to run
npm install
without explicit user approval, as this introduces supply-chain risk.

📄 阅读： references/getting-started.md

安装与包配置（
```
@syncfusion/ej2-react-dropdowns
```
）
CSS主题导入
基于
```
target
```
属性的基础
```
MentionComponent
```
配置
绑定简单数据源
自定义触发字符（
```
mentionChar
```
）和
```
showMentionChar
```
配置

⚠️ 安全提示： 安装npm包（
@syncfusion/ej2-react-dropdowns
及相关依赖）必须是用户明确确认的操作。请勿让自动化Agent在未获得用户明确批准的情况下运行
npm install
，否则会引入供应链风险。

Working with Data

数据处理

📄 Read: references/working-with-data.md

Binding array of strings, JSON objects, and complex nested data
Mapping
```
fields
```
(text, value, groupBy, iconCss)
Remote data with OData V4 (
```
ODataV4Adaptor
```
)
Remote data with Web API (
```
WebApiAdaptor
```
)
Using
```
query
```
to filter/select remote fields

📄 阅读： references/working-with-data.md

绑定字符串数组、JSON对象和复杂嵌套数据
映射
```
fields
```
（text、value、groupBy、iconCss）
基于OData V4的远程数据（
```
ODataV4Adaptor
```
）
基于Web API的远程数据（
```
WebApiAdaptor
```
）
使用
```
query
```
过滤/选择远程字段

Filtering Data

数据过滤

📄 Read: references/filtering-data.md

Setting minimum filter character length (
```
minLength
```
)
Changing filter type:
```
Contains
```
,
```
StartsWith
```
,
```
EndsWith
```
Allowing spaces within search text (
```
allowSpaces
```
)
Customizing the suggestion count (
```
suggestionCount
```
)
Debounce delay for filtering (
```
debounceDelay
```
)

📄 阅读： references/filtering-data.md

设置最小过滤字符长度（
```
minLength
```
）
修改过滤类型：
```
Contains
```
、
```
StartsWith
```
、
```
EndsWith
```
允许搜索文本中包含空格（
```
allowSpaces
```
）
自定义建议条目数量（
```
suggestionCount
```
）
过滤防抖延迟（
```
debounceDelay
```
）

Templates

模板

📄 Read: references/template.md

Item template (
```
itemTemplate
```
) for custom list rendering
Display template (
```
displayTemplate
```
) for selected value format
No-records template (
```
noRecordsTemplate
```
)
Spinner/loading template (
```
spinnerTemplate
```
)
Group header template (
```
groupTemplate
```
)

📄 阅读： references/template.md

自定义列表渲染的条目模板（
```
itemTemplate
```
）
选中值格式的展示模板（
```
displayTemplate
```
）
无匹配结果模板（
```
noRecordsTemplate
```
）
加载动画模板（
```
spinnerTemplate
```
）
分组头部模板（
```
groupTemplate
```
）

Customization

自定义配置

📄 Read: references/customization.md

Show/hide mention character in output (
```
showMentionChar
```
)
Appending suffix text after selection (
```
suffixText
```
)
Configuring popup height and width (
```
popupHeight
```
,
```
popupWidth
```
)
Custom trigger character (
```
mentionChar
```
)
Leading space requirement (
```
requireLeadingSpace
```
)
CSS class customization (
```
cssClass
```
)
Highlight matched characters (
```
highlight
```
)
Ignore accent/case in search (
```
ignoreAccent
```
,
```
ignoreCase
```
)
Z-index for popup (
```
zIndex
```
)

📄 阅读： references/customization.md

在输出内容中显示/隐藏提及触发字符（
```
showMentionChar
```
）
选中条目后追加后缀文本（
```
suffixText
```
）
配置弹窗宽高（
```
popupHeight
```
、
```
popupWidth
```
）
自定义触发字符（
```
mentionChar
```
）
要求触发字符前存在空格（
```
requireLeadingSpace
```
）
CSS类名自定义（
```
cssClass
```
）
高亮匹配字符（
```
highlight
```
）
搜索时忽略重音/大小写（
```
ignoreAccent
```
、
```
ignoreCase
```
）
弹窗层级设置（
```
zIndex
```
）

Sorting

排序

📄 Read: references/sorting.md

Sorting suggestion list:
```
Ascending
```
,
```
Descending
```
,
```
None
```

📄 阅读： references/sorting.md

建议列表排序：
```
Ascending
```
（升序）、
```
Descending
```
（降序）、
```
None
```
（不排序）

Disabled Items

禁用条目

📄 Read: references/disabled-items.md

Disabling items via
```
fields.disabled
```
Dynamically disabling items with
```
disableItem()
```
method

📄 阅读： references/disabled-items.md

通过
```
fields.disabled
```
禁用条目
使用
```
disableItem()
```
方法动态禁用条目

Accessibility

无障碍访问

📄 Read: references/accessibility.md

WAI-ARIA attributes (

aria-selected

aria-activedescendent

aria-owns

)

Keyboard navigation shortcuts
WCAG 2.2 and Section 508 compliance
RTL support (
```
enableRtl
```
)

📄 阅读： references/accessibility.md

WAI-ARIA属性支持（

aria-selected

、

aria-activedescendent

、

aria-owns

）

键盘导航快捷键
符合WCAG 2.2和Section 508标准
RTL（从右到左）布局支持（
```
enableRtl
```
）

Localization

本地化

📄 Read: references/localization.md

Localizing the
```
noRecordsTemplate
```
text via
```
L10n
```
Setting
```
locale
```
property

📄 阅读： references/localization.md

通过
```
L10n
```
对
```
noRecordsTemplate
```
文本进行本地化
设置
```
locale
```
属性

API Reference

API参考

📄 Read: references/api.md

All properties, methods, and events

target

dataSource

fields

mentionChar

minLength

suggestionCount

Methods:

addItem

disableItem

getDataByValue

getItems

showPopup

hidePopup

search

destroy

Events:

select

change

filtering

beforeOpen

opened

closed

dataBound

actionBegin

actionComplete

actionFailure

📄 阅读： references/api.md

所有属性、方法和事件

target

、

dataSource

、

fields

、

mentionChar

、

minLength

、

suggestionCount

方法：

addItem

、

disableItem

、

getDataByValue

、

getItems

、

showPopup

、

hidePopup

、

search

、

destroy

事件：

select

、

change

、

filtering

、

beforeOpen

、

opened

、

closed

、

dataBound

、

actionBegin

、

actionComplete

、

actionFailure

Quick Start Example

快速开始示例

tsx

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;

tsx

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;

Common Patterns

常见使用模式

Custom Trigger Character

自定义触发字符

Use

mentionChar

to trigger with

instead of

tsx

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

使用

mentionChar

将触发字符设置为

替代默认的

：

tsx

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

Remote Data with Filtering

带过滤的远程数据

tsx

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"
/>

tsx

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

// 注意：将下方URL替换为你自己的API接口地址
// 生产环境请勿使用第三方或公共接口
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"
/>

Handling Selection Events

处理选中事件

tsx

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}
/>

tsx

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}
/>

Popup Configuration

弹窗配置

tsx

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

tsx

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

Key Props Summary

核心属性汇总

Prop	Type	Default	Purpose
`target`	`string\|HTMLElement`	—	CSS selector or element for the editable area
`dataSource`	`array\|DataManager`	`[]`	Data for suggestions
`fields`	`FieldSettingsModel`	`{text:null,value:null}`	Maps data fields
`mentionChar`	`string`	`'@'`	Trigger character
`showMentionChar`	`boolean`	`false`	Prepend trigger char to inserted text
`minLength`	`number`	`0`	Min chars before search
`suggestionCount`	`number`	`25`	Max items in popup
`filterType`	`FilterType`	`'Contains'`	Filter match strategy
`allowSpaces`	`boolean`	`false`	Allow spaces in search
`sortOrder`	`SortOrder`	`'None'`	Sort direction
`popupHeight`	`string\|number`	`'300px'`	Popup height
`popupWidth`	`string\|number`	`'auto'`	Popup width
`suffixText`	`string`	`null`	Text appended after selection
`requireLeadingSpace`	`boolean`	`true`	Space required before trigger char
`highlight`	`boolean`	`false`	Highlight search characters

属性	类型	默认值	用途
`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`	是否高亮搜索匹配的字符