syncfusion-react-autocomplete

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion React AutoComplete

The Syncfusion React AutoComplete component provides a matched suggestion list as the user types into an input field, allowing selection from the filtered results. It supports local and remote data, rich filtering options, templates, grouping, virtualization, and full accessibility.

Syncfusion React AutoComplete组件会在用户在输入框中输入内容时提供匹配的建议列表，用户可以从过滤后的结果中选择选项。它支持本地和远程数据、丰富的过滤选项、模板、分组、虚拟化以及完整的无障碍访问支持。

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Package installation (
```
@syncfusion/ej2-react-dropdowns
```
)
CSS imports and theme configuration
Basic component setup (functional and class components)
Binding a simple string array
Configuring popup height and width (
```
popupHeight
```
,
```
popupWidth
```
)

📄 阅读： references/getting-started.md

包安装（
```
@syncfusion/ej2-react-dropdowns
```
）
CSS导入与主题配置
基础组件搭建（函数式组件与类组件）
绑定简单字符串数组
配置弹出层高度与宽度（
```
popupHeight
```
、
```
popupWidth
```
）

Data Binding

数据绑定

📄 Read: references/data-binding.md

Array of strings or numbers
Array of objects with
```
fields
```
mapping (
```
value
```
,
```
groupBy
```
,
```
iconCss
```
)
Array of complex/nested objects (dot-notation field mapping)
Remote data with
```
DataManager
```
(ODataV4Adaptor, WebApiAdaptor)
Using
```
query
```
property to filter/select remote data
```
sortOrder
```
for alphabetical ordering

📄 阅读： references/data-binding.md

字符串或数字数组
带
```
fields
```
映射的对象数组（
```
value
```
、
```
groupBy
```
、
```
iconCss
```
）
复杂/嵌套对象数组（点表示法字段映射）
使用
```
DataManager
```
绑定远程数据（ODataV4Adaptor、WebApiAdaptor）
使用
```
query
```
属性过滤/选择远程数据
用于字母排序的
```
sortOrder
```
参数

Filtering

过滤功能

📄 Read: references/filtering.md

Filter types:
```
StartsWith
```
,
```
EndsWith
```
,
```
Contains
```
```
suggestionCount
```
– limit number of suggestions
```
minLength
```
– minimum characters before search triggers
```
ignoreCase
```
– case-sensitive filtering
```
ignoreAccent
```
– diacritics filtering
```
debounceDelay
```
– delay filtering to reduce requests
Custom filtering with the
```
filtering
```
event

📄 阅读： references/filtering.md

过滤类型：
```
StartsWith
```
、
```
EndsWith
```
、
```
Contains
```
```
suggestionCount
```
– 限制建议项数量
```
minLength
```
– 触发搜索的最少输入字符数
```
ignoreCase
```
– 大小写不敏感过滤
```
ignoreAccent
```
– 变音符号过滤
```
debounceDelay
```
– 延迟过滤以减少请求次数
通过
```
filtering
```
事件实现自定义过滤

Grouping

分组功能

📄 Read: references/grouping.md

Grouping items using
```
fields.groupBy
```
Fixed and inline group headers
Custom group header with
```
groupTemplate
```

📄 阅读： references/grouping.md

使用
```
fields.groupBy
```
对选项分组
固定与行内分组头部
通过
```
groupTemplate
```
自定义分组头部

Templates

模板

📄 Read: references/templates.md

```
itemTemplate
```
– customize each list item
```
groupTemplate
```
– customize group header
```
headerTemplate
```
– static popup header
```
footerTemplate
```
– static popup footer
```
noRecordsTemplate
```
– message when no data found
```
actionFailureTemplate
```
– message on remote fetch failure

📄 阅读： references/templates.md

```
itemTemplate
```
– 自定义列表每一项的样式
```
groupTemplate
```
– 自定义分组头部样式
```
headerTemplate
```
– 静态弹出层头部
```
footerTemplate
```
– 静态弹出层底部
```
noRecordsTemplate
```
– 无匹配数据时的提示信息
```
actionFailureTemplate
```
– 远程数据请求失败时的提示信息

Value Binding

值绑定

📄 Read: references/value-binding.md

Binding primitive values (string, number)
Object binding with
```
allowObjectBinding
```
Presetting selected values with the
```
value
```
property

📄 阅读： references/value-binding.md

绑定基础类型值（字符串、数字）
通过
```
allowObjectBinding
```
绑定对象
通过
```
value
```
属性预设选中值

Virtualization

虚拟化

📄 Read: references/virtual-scroll.md

```
enableVirtualization
```
for large datasets
Injecting the
```
VirtualScroll
```
service
Virtual scrolling with local data, remote data, and grouping
Customizing item count with
```
query.take()
```

📄 阅读： references/virtual-scroll.md

针对大数据集开启
```
enableVirtualization
```
注入
```
VirtualScroll
```
服务
支持本地数据、远程数据、分组场景下的虚拟滚动
通过
```
query.take()
```
自定义项数量

Disabled Items

禁用选项

📄 Read: references/disabled-items.md

Disabling items via
```
fields.disabled
```
```
disableItem
```
method for dynamic disabling
Disabling the entire component with
```
enabled={false}
```

📄 阅读： references/disabled-items.md

通过
```
fields.disabled
```
禁用指定选项
通过
```
disableItem
```
方法动态禁用选项
通过
```
enabled={false}
```
禁用整个组件

Accessibility and Localization

无障碍访问与本地化

📄 Read: references/accessibility-localization.md

WAI-ARIA roles and attributes
Keyboard navigation shortcuts
RTL support (
```
enableRtl
```
)
Localization with
```
L10n
```
(noRecordsTemplate, actionFailureTemplate text)
WCAG 2.2 compliance overview

📄 阅读： references/accessibility-localization.md

WAI-ARIA角色与属性支持
键盘导航快捷键
从右到左排版支持（
```
enableRtl
```
）
通过
```
L10n
```
实现本地化（noRecordsTemplate、actionFailureTemplate文本）
WCAG 2.2合规性说明

Styling and Customization

样式与自定义

📄 Read: references/styling.md

CSS class targets for wrapper, icon, focus, placeholder, selection
Float label customization
Popup item appearance
```
cssClass
```
property for custom class injection
Popup resize (
```
allowResize
```
)
Mandatory asterisk styling

📄 阅读： references/styling.md

可自定义的CSS类目标：容器、图标、聚焦状态、占位符、选中状态
浮动标签自定义
弹出层选项外观调整
通过
```
cssClass
```
属性注入自定义类
弹出层大小调整（
```
allowResize
```
）
必填项星号样式自定义

How-To: Autofill, Highlight, and Icons

操作指南：自动填充、高亮与图标

📄 Read: references/how-to.md

```
autofill
```
– suggest first matched item on Arrow Down
```
highlight
```
– highlight typed characters in suggestion list
Icon support with
```
fields.iconCss
```

📄 阅读： references/how-to.md

```
autofill
```
– 按下向下箭头时自动补全第一个匹配项
```
highlight
```
– 在建议列表中高亮用户输入的字符
通过
```
fields.iconCss
```
支持图标展示

API Reference

API参考

📄 Read: references/api.md

All properties with types, defaults, and descriptions
All methods with parameters and return types
All events with descriptions

📄 阅读： references/api.md

所有属性的类型、默认值与说明
所有方法的参数与返回类型
所有事件的说明

Quick Start Example

快速开始示例

Installation: Pin packages to a specific major version to reduce supply-chain risk.
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-react-inputs@^33.x.x @syncfusion/ej2-base@^33.x.x

tsx

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-inputs/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

const sportsData: string[] = [
  'Badminton', 'Basketball', 'Cricket', 'Football',
  'Golf', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
];

export default function App() {
  return (
    <AutoCompleteComponent
      id="sports-ac"
      dataSource={sportsData}
      placeholder="Find a game"
    />
  );
}

安装提示： 将包固定到特定的主版本，以降低供应链风险。
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-react-inputs@^33.x.x @syncfusion/ej2-base@^33.x.x

tsx

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-inputs/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

const sportsData: string[] = [
  'Badminton', 'Basketball', 'Cricket', 'Football',
  'Golf', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
];

export default function App() {
  return (
    <AutoCompleteComponent
      id="sports-ac"
      dataSource={sportsData}
      placeholder="Find a game"
    />
  );
}

Common Patterns

常用使用模式

Object data source with field mapping

带字段映射的对象数据源

tsx

const sportsData = [
  { id: 'Game1', game: 'Badminton' },
  { id: 'Game2', game: 'Basketball' },
];
const fields = { value: 'game' };

<AutoCompleteComponent dataSource={sportsData} fields={fields} placeholder="Find a game" />

tsx

const sportsData = [
  { id: 'Game1', game: 'Badminton' },
  { id: 'Game2', game: 'Basketball' },
];
const fields = { value: 'game' };

<AutoCompleteComponent dataSource={sportsData} fields={fields} placeholder="Find a game" />

Remote data binding

远程数据绑定

Note: Replace the URL below with your own OData endpoint. Do not use a live third-party URL in production.

tsx

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

const customerData = new DataManager({
  adaptor: new ODataV4Adaptor,
  crossDomain: true,
  url: 'https://your-api-endpoint.example.com/odata/' // ← replace with your own endpoint
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { value: 'ContactName' };

<AutoCompleteComponent
  dataSource={customerData}
  query={query}
  fields={fields}
  sortOrder="Ascending"
  placeholder="Find a customer"
/>

注意： 将下方的URL替换为你自己的OData接口地址。生产环境中不要使用第三方公共URL。

tsx

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

const customerData = new DataManager({
  adaptor: new ODataV4Adaptor,
  crossDomain: true,
  url: 'https://your-api-endpoint.example.com/odata/' // ← replace with your own endpoint
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { value: 'ContactName' };

<AutoCompleteComponent
  dataSource={customerData}
  query={query}
  fields={fields}
  sortOrder="Ascending"
  placeholder="Find a customer"
/>

Filtering with custom options

自定义选项过滤

tsx

<AutoCompleteComponent
  dataSource={sportsData}
  filterType="StartsWith"
  minLength={2}
  suggestionCount={5}
  debounceDelay={300}
  ignoreCase={true}
  placeholder="Type to search"
/>

tsx

<AutoCompleteComponent
  dataSource={sportsData}
  filterType="StartsWith"
  minLength={2}
  suggestionCount={5}
  debounceDelay={300}
  ignoreCase={true}
  placeholder="Type to search"
/>

Accessing methods via ref

通过ref访问组件方法

tsx

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

export default function App() {
  const acRef = useRef<AutoCompleteComponent>(null);

  return (
    <>
      <AutoCompleteComponent ref={acRef} dataSource={sportsData} placeholder="Find a game" />
      <button onClick={() => acRef.current?.showPopup()}>Open</button>
      <button onClick={() => acRef.current?.clear()}>Clear</button>
    </>
  );
}

tsx

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

export default function App() {
  const acRef = useRef<AutoCompleteComponent>(null);

  return (
    <>
      <AutoCompleteComponent ref={acRef} dataSource={sportsData} placeholder="Find a game" />
      <button onClick={() => acRef.current?.showPopup()}>Open</button>
      <button onClick={() => acRef.current?.clear()}>Clear</button>
    </>
  );
}