syncfusion-angular-autocomplete

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular AutoComplete Component

实现Syncfusion Angular AutoComplete组件

Component Overview & Architecture

组件概述与架构

The AutoComplete is a text input component that provides matching suggestions as the user types. It is designed for:

Type-ahead suggestions — shows matching items from a data source as the user types
Free-form input — users can type any value, not restricted to the list
Search/filter — multiple filter strategies (StartsWith, Contains, EndsWith)
Autofill — automatically completes the first matched suggestion in the input
Grouped suggestions — categorize items by a
```
groupBy
```
field
Virtual scrolling — efficiently handles thousands of items
Template customization — item, group, header, footer, and empty-state templates

AutoComplete是一款文本输入组件，可在用户输入时提供匹配的建议项。它的设计用途包括：

键入提前建议 —— 用户输入时展示数据源中匹配的条目
自由格式输入 —— 用户可输入任意值，不受列表限制
搜索/过滤 —— 多种过滤策略（StartsWith、Contains、EndsWith）
自动填充 —— 自动在输入框中补全第一个匹配的建议项
分组建议 —— 通过
```
groupBy
```
字段对条目进行分类
虚拟滚动 —— 高效处理数千条数据
模板自定义 —— 支持条目、分组、头部、底部和空状态模板

Key Characteristics

核心特性

Aspect	Details
Selection	Single item; user can also type any free-form value
Data Sources	Local arrays, remote DataManager, OData, Web API, Observable (async pipe)
Filtering	Built-in filtering: `StartsWith` , `EndsWith` , `Contains`
Autofill	Completes the first match inline as the user types
Performance	Virtual scrolling for large datasets (1,000+ items)
Forms	Template-driven ( `ngModel` ) and reactive ( `FormControl` ) form integration
Accessibility	WCAG 2.2 compliant, full keyboard navigation, ARIA attributes
Customization	Item, group, header, footer, noRecords, actionFailure templates; CSS theming

维度	详情
选择能力	单选；用户也可输入任意自由格式的值
数据源	本地数组、远程DataManager、OData、Web API、Observable（异步管道）
过滤能力	内置过滤： `StartsWith` 、 `EndsWith` 、 `Contains`
自动填充	用户输入时自动内联补全第一个匹配项
性能	适配大数据集（1000+条目）的虚拟滚动能力
表单支持	模板驱动（ `ngModel` ）和响应式（ `FormControl` ）表单集成
无障碍	符合WCAG 2.2标准，支持全键盘导航、ARIA属性
自定义能力	条目、分组、头部、底部、无数据、请求失败模板；CSS主题定制

Documentation Navigation Guide

文档导航指南

📄 Getting Started

📄 入门指南

Read: references/getting-started.md

Install
```
@syncfusion/ej2-angular-dropdowns
```
package
Set up Angular 21+ project with standalone components
Import
```
AutoCompleteModule
```
and required CSS themes
Create your first AutoComplete with basic data binding
Configure popup height, width, and placeholder
Enable two-way binding with
```
[(value)]
```

阅读： references/getting-started.md

安装
```
@syncfusion/ej2-angular-dropdowns
```
包
配置Angular 21+ 独立组件项目
导入
```
AutoCompleteModule
```
和所需CSS主题
基于基础数据绑定创建你的第一个AutoComplete组件
配置弹出层高度、宽度和占位符
使用
```
[(value)]
```
启用双向绑定

📄 Data Binding

📄 数据绑定

Read: references/data-binding.md

Bind to local arrays (strings, numbers, objects, complex objects)
Map
```
value
```
,
```
text
```
, and
```
iconCss
```
fields via
```
fields
```
property
Remote data using DataManager with OData, Web API adapters
Async pipe pattern for RxJS Observables
Object binding with
```
allowObjectBinding
```
Preselecting values using the
```
value
```
property

阅读： references/data-binding.md

绑定本地数组（字符串、数字、对象、复杂对象）
通过
```
fields
```
属性映射
```
value
```
、
```
text
```
和
```
iconCss
```
字段
使用适配OData、Web API的DataManager实现远程数据绑定
适配RxJS Observables的异步管道模式
通过
```
allowObjectBinding
```
实现对象绑定
使用
```
value
```
属性实现默认值预选

📄 Filtering & Search

📄 过滤与搜索

Read: references/filtering-and-search.md

Configure
```
filterType
```
(StartsWith, Contains, EndsWith)
Limit suggestion count with
```
suggestionCount
```
Minimum character threshold with
```
minLength
```
Case-sensitive filtering with
```
ignoreCase
```
Diacritics/accent-insensitive filtering with
```
ignoreAccent
```
Debounce delay to optimize remote filtering with
```
debounceDelay
```
Custom filtering via the
```
filtering
```
event with
```
updateData
```

阅读： references/filtering-and-search.md

配置
```
filterType
```
（StartsWith、Contains、EndsWith）
通过
```
suggestionCount
```
限制建议项数量
通过
```
minLength
```
设置触发建议的最小输入字符数
通过
```
ignoreCase
```
设置大小写敏感过滤
通过
```
ignoreAccent
```
设置忽略变音符号/重音的过滤
通过
```
debounceDelay
```
设置防抖延迟优化远程过滤性能
通过
```
filtering
```
事件和
```
updateData
```
实现自定义过滤

📄 Grouping & Templates

📄 分组与模板

Read: references/grouping-and-templates.md

Group suggestions by category using
```
fields.groupBy
```
Item templates for custom rendering
Group header templates (inline and fixed)
Header and footer templates for the popup
Empty state with
```
noRecordsTemplate
```
Action failure template for remote data errors

阅读： references/grouping-and-templates.md

使用
```
fields.groupBy
```
按类别分组建议项
自定义渲染的条目模板
分组头部模板（内联和固定）
弹出层的头部和底部模板
通过
```
noRecordsTemplate
```
自定义空状态
远程数据请求失败的错误模板

📄 Feature Configuration

📄 功能配置

Read: references/feature-configuration.md

Autofill: inline suggestion completion with
```
autofill
```
property
Highlight matched characters with
```
highlight
```
property
Disable individual items with
```
fields.disabled
```
or
```
disableItem
```
method
Disable entire component with
```
enabled
```
property
Resizable popup with
```
allowResize
```
Virtual scrolling for large datasets with
```
enableVirtualization
```
Show/hide popup button with
```
showPopupButton
```
Show/hide clear button with
```
showClearButton
```
RTL support with
```
enableRtl
```
Sort order with
```
sortOrder
```

阅读： references/feature-configuration.md

自动填充：通过
```
autofill
```
属性实现内联建议补全
通过
```
highlight
```
属性高亮匹配字符
通过
```
fields.disabled
```
或
```
disableItem
```
方法禁用单个条目
通过
```
enabled
```
属性禁用整个组件
通过
```
allowResize
```
实现弹出层大小可调整
通过
```
enableVirtualization
```
为大数据集启用虚拟滚动
通过
```
showPopupButton
```
控制是否显示弹出层切换按钮
通过
```
showClearButton
```
控制是否显示清空按钮
通过
```
enableRtl
```
支持从右到左排版
通过
```
sortOrder
```
设置排序规则

📄 Form Support & Validation

📄 表单支持与验证

Read: references/form-support-and-validation.md

Template-driven forms using
```
ngModel
```
and
```
FormsModule
```
Reactive forms using
```
FormControl
```
,
```
FormGroup
```
, and
```
ReactiveFormsModule
```
Binding and validation patterns
Pre-selecting values via form model

阅读： references/form-support-and-validation.md

使用
```
ngModel
```
和
```
FormsModule
```
实现模板驱动表单
使用
```
FormControl
```
、
```
FormGroup
```
和
```
ReactiveFormsModule
```
实现响应式表单
绑定和验证模式
通过表单模型预设置值

📄 Accessibility & Localization

📄 无障碍与国际化

Read: references/accessibility-and-localization.md

WCAG 2.2, Section 508, and ADA compliance
Full keyboard shortcuts (Arrow keys, Tab, Enter, Escape, Alt+Down/Up)

ARIA attributes:

aria-haspopup

aria-expanded

aria-selected

aria-autocomplete

Screen reader support and focus management

Localization with

L10n.load()

for

noRecordsTemplate

and

actionFailureTemplate

RTL language support

阅读： references/accessibility-and-localization.md

符合WCAG 2.2、第508节和ADA标准
全键盘快捷键支持（方向键、Tab、Enter、Escape、Alt+下/上键）

ARIA属性支持：

aria-haspopup

、

aria-expanded

、

aria-selected

、

aria-autocomplete

屏幕阅读器支持和焦点管理

通过

L10n.load()

实现

noRecordsTemplate

和

actionFailureTemplate

的本地化

从右到左语言支持

📄 Advanced Patterns & How-To

📄 高级模式与实践指南

Read: references/advanced-patterns-how-to.md

Autofill feature with the
```
autofill
```
property
Highlight searched characters with the
```
highlight
```
property
Multi-field custom filtering with
```
Predicate
```
(filter by both Name and Code)
Icon support via
```
fields.iconCss
```
Suggestion list on focus from browser local storage
Custom search and highlight styling

阅读： references/advanced-patterns-how-to.md

基于
```
autofill
```
属性的自动填充功能
基于
```
highlight
```
属性的搜索字符高亮
基于
```
Predicate
```
的多字段自定义过滤（同时按名称和编码过滤）
通过
```
fields.iconCss
```
支持图标展示
聚焦时从浏览器本地存储加载建议列表
自定义搜索和高亮样式

📄 API Reference

📄 API参考

Read: references/api.md

Complete properties reference with types, defaults, and descriptions
All methods with signatures and usage
All events with payload types and handler examples

阅读： references/api.md

完整属性参考，包含类型、默认值和描述
所有方法的签名和用法
所有事件的载荷类型和处理示例

Quick Start Example

快速入门示例

typescript

// app.component.ts (Angular 21 Standalone)
import { Component } from '@angular/core';
import { AutoCompleteModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AutoCompleteModule],
  template: `
    <ejs-autocomplete
      id="sports"
      [dataSource]="sportsData"
      placeholder="Find a sport"
      [(value)]="selectedValue">
    </ejs-autocomplete>
  `
})
export class AppComponent {
  public sportsData: string[] = [
    'Badminton', 'Basketball', 'Cricket',
    'Football', 'Golf', 'Hockey', 'Tennis'
  ];
  public selectedValue: string = '';
}

Install the package:

bash

ng add @syncfusion/ej2-angular-dropdowns

Add CSS (styles.css):

css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-lists/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';

typescript

// app.component.ts (Angular 21 Standalone)
import { Component } from '@angular/core';
import { AutoCompleteModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AutoCompleteModule],
  template: `
    <ejs-autocomplete
      id="sports"
      [dataSource]="sportsData"
      placeholder="Find a sport"
      [(value)]="selectedValue">
    </ejs-autocomplete>
  `
})
export class AppComponent {
  public sportsData: string[] = [
    'Badminton', 'Basketball', 'Cricket',
    'Football', 'Golf', 'Hockey', 'Tennis'
  ];
  public selectedValue: string = '';
}

安装依赖包：

bash

ng add @syncfusion/ej2-angular-dropdowns

引入CSS（styles.css）：

css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-lists/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';

Common Patterns

常用模式

Pattern 1: Filter with Complex Object Data

模式1：复杂对象数据过滤

typescript

// Map fields for object array
public fields: Object = { value: 'Game' };
public sportsData: { [key: string]: Object }[] = [
  { Id: 'Game1', Game: 'Badminton' },
  { Id: 'Game2', Game: 'Cricket' }
];

html

<ejs-autocomplete [dataSource]="sportsData" [fields]="fields" placeholder="Find a game">
</ejs-autocomplete>

When to use: Whenever your data is an array of objects and you need to display one field as the suggestion text.

typescript

// 为对象数组映射字段
public fields: Object = { value: 'Game' };
public sportsData: { [key: string]: Object }[] = [
  { Id: 'Game1', Game: 'Badminton' },
  { Id: 'Game2', Game: 'Cricket' }
];

html

<ejs-autocomplete [dataSource]="sportsData" [fields]="fields" placeholder="Find a game">
</ejs-autocomplete>

适用场景： 你的数据是对象数组，需要展示某一个字段作为建议文本时使用。

Pattern 2: Autofill + Highlight

模式2：自动填充+高亮

html

<ejs-autocomplete
  [dataSource]="data"
  [autofill]="true"
  [highlight]="true"
  filterType="StartsWith">
</ejs-autocomplete>

When to use: Search bars where users expect inline completion and visual emphasis on matched text.

html

<ejs-autocomplete
  [dataSource]="data"
  [autofill]="true"
  [highlight]="true"
  filterType="StartsWith">
</ejs-autocomplete>

适用场景： 搜索栏场景，用户期望获得内联补全和匹配文本视觉强调的效果。

Pattern 3: Remote Data with Debounce

模式3：带防抖的远程数据加载

typescript

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

public data: DataManager = new DataManager({
  url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Customers',
  adaptor: new ODataV4Adaptor,
  crossDomain: true
});
public fields: Object = { value: 'ContactName' };
public query: Query = new Query().select(['ContactName']).take(6);
public debounceDelay: number = 500;

html

<ejs-autocomplete
  [dataSource]="data"
  [fields]="fields"
  [query]="query"
  [debounceDelay]="debounceDelay"
  filterType="StartsWith">
</ejs-autocomplete>

When to use: API-backed autocomplete where you want to reduce request frequency.

typescript

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

public data: DataManager = new DataManager({
  url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Customers',
  adaptor: new ODataV4Adaptor,
  crossDomain: true
});
public fields: Object = { value: 'ContactName' };
public query: Query = new Query().select(['ContactName']).take(6);
public debounceDelay: number = 500;

html

<ejs-autocomplete
  [dataSource]="data"
  [fields]="fields"
  [query]="query"
  [debounceDelay]="debounceDelay"
  filterType="StartsWith">
</ejs-autocomplete>

适用场景： 基于API的自动完成功能，你希望降低请求频率时使用。

Pattern 4: Virtual Scrolling for Large Datasets

模式4：适用于大数据集的虚拟滚动

typescript

import { AutoCompleteComponent, VirtualScroll } from '@syncfusion/ej2-angular-dropdowns';
AutoCompleteComponent.Inject(VirtualScroll);

html

<ejs-autocomplete
  [dataSource]="records"
  [fields]="fields"
  [enableVirtualization]="true"
  popupHeight="200px">
</ejs-autocomplete>

When to use: Datasets with 1,000+ items where rendering all DOM elements at once is costly.

typescript

import { AutoCompleteComponent, VirtualScroll } from '@syncfusion/ej2-angular-dropdowns';
AutoCompleteComponent.Inject(VirtualScroll);

html

<ejs-autocomplete
  [dataSource]="records"
  [fields]="fields"
  [enableVirtualization]="true"
  popupHeight="200px">
</ejs-autocomplete>

适用场景： 数据集包含1000+条目，一次性渲染所有DOM元素性能开销过高时使用。

Key Properties Quick Reference

核心属性快速参考

Property	Type	Default	Purpose
`dataSource`	Array \| DataManager	`[]`	Source data for suggestions
`fields`	FieldSettingsModel	`{ value: null }`	Map data columns to component
`placeholder`	string	`null`	Hint text when empty
`value`	string \| number \| boolean \| object	`null`	Selected/typed value
`filterType`	FilterType	`'Contains'`	How suggestions are matched
`minLength`	number	`1`	Minimum chars to trigger suggestions
`suggestionCount`	number	`20`	Max suggestions shown
`autofill`	boolean	`false`	Inline completion of first match
`highlight`	boolean	`false`	Highlight matched characters
`ignoreCase`	boolean	`true`	Case-insensitive filtering
`ignoreAccent`	boolean	—	Ignore diacritics in filtering
`debounceDelay`	number	`300`	Delay (ms) before filtering fires
`enableVirtualization`	boolean	`false`	Virtual scroll for large data
`allowResize`	boolean	`false`	Resizable popup
`showClearButton`	boolean	`true`	Show ✕ to clear value
`showPopupButton`	boolean	`false`	Show dropdown toggle button
`enabled`	boolean	`true`	Enable/disable entire component
`readonly`	boolean	`false`	Prevent user edits
`allowObjectBinding`	boolean	`false`	Bind value as full object
`sortOrder`	SortOrder	`null`	Sort suggestions (Ascending/Descending)
`popupHeight`	string \| number	`'300px'`	Popup list height
`popupWidth`	string \| number	`'100%'`	Popup list width
`locale`	string	`'en-US'`	Localization culture
`enableRtl`	boolean	`false`	Right-to-left rendering

属性	类型	默认值	用途
`dataSource`	Array \| DataManager	`[]`	建议项的源数据
`fields`	FieldSettingsModel	`{ value: null }`	映射数据列到组件字段
`placeholder`	string	`null`	输入框为空时的提示文本
`value`	string \| number \| boolean \| object	`null`	选中/输入的值
`filterType`	FilterType	`'Contains'`	建议项的匹配规则
`minLength`	number	`1`	触发建议的最小输入字符数
`suggestionCount`	number	`20`	最多展示的建议项数量
`autofill`	boolean	`false`	内联补全第一个匹配项
`highlight`	boolean	`false`	高亮匹配的字符
`ignoreCase`	boolean	`true`	大小写不敏感过滤
`ignoreAccent`	boolean	—	过滤时忽略变音符号
`debounceDelay`	number	`300`	触发过滤前的延迟（毫秒）
`enableVirtualization`	boolean	`false`	为大数据启用虚拟滚动
`allowResize`	boolean	`false`	弹出层大小可调整
`showClearButton`	boolean	`true`	显示清空值的✕按钮
`showPopupButton`	boolean	`false`	显示下拉切换按钮
`enabled`	boolean	`true`	启用/禁用整个组件
`readonly`	boolean	`false`	禁止用户编辑
`allowObjectBinding`	boolean	`false`	将值绑定为完整对象
`sortOrder`	SortOrder	`null`	建议项排序规则（升序/降序）
`popupHeight`	string \| number	`'300px'`	弹出层列表高度
`popupWidth`	string \| number	`'100%'`	弹出层列表宽度
`locale`	string	`'en-US'`	本地化文化标识
`enableRtl`	boolean	`false`	从右到左渲染

Workflow Decision Tree

工作流决策树

Need to implement AutoComplete?
│
├─ What's your data source?
│   ├─ Local array → See Data Binding: "Array of string" or "Array of object"
│   └─ Remote API  → See Data Binding: "Bind to remote data"
│
├─ How should filtering work?
│   ├─ Default (Contains)   → No extra config needed
│   ├─ StartsWith           → filterType="StartsWith"
│   ├─ Custom multi-field   → See Advanced Patterns: "Custom filtering"
│   └─ Accent-insensitive   → [ignoreAccent]="true"
│
├─ Need autofill (inline completion)?
│   └─ YES → [autofill]="true" + filterType="StartsWith"
│
├─ Highlight matched text?
│   └─ YES → [highlight]="true"
│
├─ Large dataset (1,000+ items)?
│   └─ YES → [enableVirtualization]="true" + inject VirtualScroll
│
├─ Using inside a form?
│   ├─ Template-driven → See Form Support: "ngModel"
│   └─ Reactive        → See Form Support: "FormControl"
│
└─ Need accessibility or localization?
    └─ YES → See Accessibility & Localization reference

需要实现AutoComplete功能？
│
├─ 你的数据源是什么？
│   ├─ 本地数组 → 查看数据绑定："字符串数组" 或 "对象数组"
│   └─ 远程API  → 查看数据绑定："绑定远程数据"
│
├─ 过滤规则需要如何配置？
│   ├─ 默认（包含匹配）   → 无需额外配置
│   ├─ 开头匹配           → filterType="StartsWith"
│   ├─ 自定义多字段匹配   → 查看高级模式："自定义过滤"
│   └─ 忽略重音符号       → [ignoreAccent]="true"
│
├─ 需要自动填充（内联补全）？
│   └─ 是 → [autofill]="true" + filterType="StartsWith"
│
├─ 需要高亮匹配文本？
│   └─ 是 → [highlight]="true"
│
├─ 数据集很大（1000+条目）？
│   └─ 是 → [enableVirtualization]="true" + 注入VirtualScroll
│
├─ 在表单中使用？
│   ├─ 模板驱动表单 → 查看表单支持："ngModel"
│   └─ 响应式表单        → 查看表单支持："FormControl"
│
└─ 需要无障碍或国际化能力？
    └─ 是 → 查看无障碍与国际化参考