syncfusion-angular-dropdowns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular Dropdowns

实现Syncfusion Angular下拉组件

Security & Trust Boundary

安全与信任边界

Default posture: local data only

默认策略：仅使用本地数据

All dropdown components in this skill default to local, in-memory data sources. Binding a component to a remote HTTP endpoint (via

DataManager

or any Observable/HTTP source) is a non-default, elevated-risk operation that requires an explicit security review before it is permitted in production code.

⛔ Do not generate or suggest remote
DataManager
/ HTTP data-source configurations unless the consuming application has passed a security review confirming that:
The target endpoint is owned and operated by the same team as the application.

The endpoint enforces authentication, authorization, and input validation.
All responses are sanitized before being bound to a component
dataSource
.
A Content Security Policy (CSP) covering the origin is in place.

本技能中的所有下拉组件默认使用本地内存数据源。 将组件绑定到远程HTTP端点（通过

DataManager

或任何Observable/HTTP源）是非默认的高风险操作，在生产代码中使用前需要经过明确的安全审查。

⛔ 除非消费应用已通过安全审查并确认以下条件，否则请勿生成或建议远程
DataManager
/HTTP数据源配置：
目标端点由与应用相同的团队拥有和运营。

端点实施了身份验证、授权和输入验证。
所有响应在绑定到组件
dataSource
之前都经过清理。
已配置覆盖该源的内容安全策略（CSP）。

Mandatory security requirements

强制性安全要求

#	Requirement
1	Local data by default. Use plain TypeScript arrays for `dataSource` unless a remote source has been explicitly approved.
2	No public or third-party URLs. Never configure a data source that fetches from an endpoint outside the application's own origin.
3	Sanitize all external data before binding. Any value that originates outside the application (API response, local-storage read) must be stripped of HTML/script content before assignment to `dataSource` or `value` .
4	Sanitize user filter input. Before forwarding typed text to any server query, strip non-alphanumeric characters to prevent injection.
5	No `crossDomain: true` by default. CORS relaxation in `DataManager` must be explicitly justified and reviewed.
6	Pin package versions. Every `@syncfusion/ej2-*` dependency must be locked to an exact version in `package.json` ; verify against the lockfile after every install.
7	No CDN asset loading without SRI. CSS/JS must be resolved from `node_modules` at build time, not fetched from a CDN at runtime without Subresource Integrity hashes.
8	No sensitive data in local storage. `enablePersistence` must never store tokens, credentials, or PII; sanitize any value read back before use.

序号	要求
1	默认使用本地数据。除非远程源已明确获批，否则使用纯TypeScript数组作为 `dataSource` 。
2	禁止使用公共或第三方URL。绝不配置从应用自身源之外的端点获取数据的数据源。
3	绑定前清理所有外部数据。任何源自应用外部的值（API响应、本地存储读取值）在赋值给 `dataSource` 或 `value` 之前，必须剥离HTML/脚本内容。
4	清理用户过滤输入。在将输入文本转发到任何服务器查询之前，剥离非字母数字字符以防止注入攻击。
5	默认禁用 `crossDomain: true` 。 `DataManager` 中的CORS放宽必须有明确的理由并经过审查。
6	锁定包版本。每个 `@syncfusion/ej2-*` 依赖项必须在 `package.json` 中锁定到确切版本；每次安装后验证锁文件。
7	无SRI时禁止加载CDN资源。 CSS/JS必须在构建时从 `node_modules` 解析，而非在运行时从CDN获取（除非带有子资源完整性哈希）。
8	禁止在本地存储中存储敏感数据。 `enablePersistence` 绝不能存储令牌、凭据或个人身份信息（PII）；使用前清理从本地存储读取的任何值。

AutoComplete

A text input component that provides matching suggestions as the user types. Supports free-form input, remote data, filtering strategies, grouping, virtual scrolling, and full Angular forms integration.

一个文本输入组件，用户输入时会提供匹配建议。支持自由输入、远程数据、过滤策略、分组、虚拟滚动以及完整的Angular表单集成。

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（async管道）
过滤	内置过滤： `StartsWith` 、 `EndsWith` 、 `Contains`
自动填充	用户输入时自动在输入框中补全第一个匹配项
性能	针对大型数据集（1000+条）的虚拟滚动
表单	模板驱动（ `ngModel` ）和响应式（ `FormControl` ）表单集成
无障碍	符合WCAG 2.2标准，支持完整键盘导航、ARIA属性
自定义	项、分组、页眉、页脚、无数据、操作失败模板；CSS主题定制

Documentation Navigation Guide

文档导航指南

📄 Getting Started

📄 快速入门

Read: references/autocomplete-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/autocomplete-getting-started.md

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

📄 Data Binding

📄 数据绑定

Read: references/autocomplete-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/autocomplete-data-binding.md

绑定到本地数组（字符串、数字、对象、复杂对象）
通过
```
fields
```
属性映射
```
value
```
、
```
text
```
和
```
iconCss
```
字段
使用带有OData、Web API适配器的DataManager进行远程数据绑定
RxJS Observables的async管道模式
使用
```
allowObjectBinding
```
进行对象绑定
使用
```
value
```
属性预选择值

📄 Filtering & Search

📄 过滤与搜索

Read: references/autocomplete-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/autocomplete-filtering-and-search.md

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

📄 Grouping & Templates

📄 分组与模板

Read: references/autocomplete-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/autocomplete-grouping-and-templates.md

使用
```
fields.groupBy
```
按类别分组建议
自定义渲染的项模板
分组页眉模板（内联和固定）
弹出框的页眉和页脚模板
使用
```
noRecordsTemplate
```
设置空状态
远程数据错误的操作失败模板

📄 Feature Configuration

📄 功能配置

Read: references/autocomplete-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/autocomplete-feature-configuration.md

自动填充：使用
```
autofill
```
属性实现内联建议补全
使用
```
highlight
```
属性高亮匹配字符
使用
```
fields.disabled
```
或
```
disableItem
```
方法禁用单个项
使用
```
enabled
```
属性禁用整个组件
使用
```
allowResize
```
启用弹出框可调整大小
使用
```
enableVirtualization
```
针对大型数据集启用虚拟滚动
使用
```
showPopupButton
```
显示/隐藏弹出按钮
使用
```
showClearButton
```
显示/清除按钮
使用
```
enableRtl
```
启用RTL支持
使用
```
sortOrder
```
设置排序顺序

📄 Form Support & Validation

📄 表单支持与验证

Read: references/autocomplete-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/autocomplete-form-support-and-validation.md

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

📄 Accessibility & Localization

📄 无障碍与本地化

Read: references/autocomplete-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/autocomplete-accessibility-and-localization.md

符合WCAG 2.2、Section 508和ADA标准
完整键盘快捷键（箭头键、Tab、Enter、Escape、Alt+Down/Up）

ARIA属性：

aria-haspopup

、

aria-expanded

、

aria-selected

、

aria-autocomplete

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

使用

L10n.load()

本地化

noRecordsTemplate

和

actionFailureTemplate

RTL语言支持

📄 Advanced Patterns & How-To

📄 高级模式与操作指南

Read: references/autocomplete-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
⚠️ Security note: Local storage is accessible to any JavaScript running on the same origin and is a common XSS attack surface. Never store sensitive data (tokens, PII) in local storage. Sanitize any values read from local storage before binding them to the component's
```
dataSource
```
or
```
value
```
.
Custom search and highlight styling

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

使用
```
autofill
```
属性的自动填充功能
使用
```
highlight
```
属性高亮搜索字符
使用
```
Predicate
```
实现多字段自定义过滤（按名称和代码过滤）
通过
```
fields.iconCss
```
支持图标
浏览器本地存储聚焦时显示建议列表
⚠️ 安全提示： 本地存储对同一源上运行的任何JavaScript都可访问，是常见的XSS攻击面。切勿在本地存储中存储敏感数据（令牌、PII）。将从本地存储读取的值绑定到组件的
```
dataSource
```
或
```
value
```
之前，必须进行清理。
自定义搜索和高亮样式

📄 API Reference

📄 API参考

Read: references/autocomplete-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/autocomplete-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:

⚠️ Security note: Pin the package to a specific version to prevent unintended upgrades to potentially compromised releases. Verify the installed version against your lockfile (
package-lock.json
/
yarn.lock
) after installation.

bash

ng add @syncfusion/ej2-angular-dropdowns@<version>

Add CSS (styles.css):

⚠️ Security note: These imports are resolved from
node_modules
at build time. Ensure the installed Syncfusion packages match your pinned versions in
package-lock.json
or
yarn.lock
before building. Do not source these files from a CDN without Subresource Integrity (SRI) hashes.

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 独立组件)
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="查找运动项目"
      [(value)]="selectedValue">
    </ejs-autocomplete>
  `
})
export class AppComponent {
  public sportsData: string[] = [
    'Badminton', 'Basketball', 'Cricket',
    'Football', 'Golf', 'Hockey', 'Tennis'
  ];
  public selectedValue: string = '';
}

安装包：

⚠️ 安全提示： 将包固定到特定版本，防止意外升级到可能存在风险的版本。安装后验证锁文件（
package-lock.json
/
yarn.lock
）中的已安装版本。

bash

ng add @syncfusion/ej2-angular-dropdowns@<version>

添加CSS（styles.css）：

⚠️ 安全提示： 这些导入在构建时从
node_modules
解析。构建前确保已安装的Syncfusion包与
package-lock.json
或
yarn.lock
中的固定版本匹配。请勿从CDN获取这些文件，除非带有子资源完整性（SRI）哈希。

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="查找运动项目">
</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：带防抖的远程数据

🔒 Security policy — remote data is a restricted pattern. Binding AutoComplete to a remote endpoint requires a security review (see Security & Trust Boundary above) before use in production. Remote data binding details and requirements are documented in references/autocomplete-data-binding.md. No remote
DataManager
example is provided here by default.

When to use: API-backed autocomplete where you want to reduce request frequency — only after the endpoint and data pipeline have been reviewed per the security requirements above.

🔒 安全策略 — 远程数据是受限模式。 将AutoComplete绑定到远程端点需要经过安全审查（参见上方安全与信任边界）才能在生产环境中使用。远程数据绑定的详细信息和要求记录在references/autocomplete-data-binding.md中。默认不提供远程
DataManager
示例。

适用场景： 基于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  → 参见数据绑定："绑定到远程数据"
│
├─ 过滤方式应该如何设置？
│   ├─ 默认（Contains）   → 无需额外配置
│   ├─ StartsWith           → filterType="StartsWith"
│   ├─ 自定义多字段   → 参见高级模式："自定义过滤"
│   └─ 忽略变音符号   → [ignoreAccent]="true"
│
├─ 需要自动填充（内联补全）？
│   └─ 是 → [autofill]="true" + filterType="StartsWith"
│
├─ 高亮匹配文本？
│   └─ 是 → [highlight]="true"
│
├─ 大型数据集（1000+条）？
│   └─ 是 → [enableVirtualization]="true" + 注入VirtualScroll
│
├─ 在表单中使用？
│   ├─ 模板驱动 → 参见表单支持："ngModel"
│   └─ 响应式        → 参见表单支持："FormControl"
│
└─ 需要无障碍或本地化？
    └─ 是 → 参见无障碍与本地化参考文档

ComboBox

A flexible dropdown component that allows users to select from a predefined list or enter a custom value. Supports filtering, grouping, templates, virtual scrolling, and full Angular forms integration.

一个灵活的下拉组件，允许用户从预定义列表中选择或输入自定义值。支持过滤、分组、模板、虚拟滚动以及完整的Angular表单集成。

Component Overview & Architecture

组件概述与架构

The ComboBox is a flexible dropdown component that allows users to:

Select from a list of predefined options
Enter custom values when
```
allowCustom
```
is enabled
Search/filter items as they type
Group items by category
Customize display with templates for items, groups, headers, footers

ComboBox是一个灵活的下拉组件，允许用户：

从列表中选择预定义选项
输入自定义值（启用
```
allowCustom
```
时）
搜索/过滤输入时的项
按类别分组项
自定义显示项、分组、页眉、页脚的模板

Key Characteristics

关键特性

Aspect	Details
Selection	Single item from predefined list or custom value
Data Sources	Local arrays, remote DataManager, OData, Web API, async data
Filtering	Built-in filtering with configurable strategies (StartsWith, Contains, EndsWith)
Performance	Virtual scrolling for large datasets (10,000+ items)
Forms	Works with template-driven forms (ngModel) and reactive forms (FormControl)
Accessibility	WCAG 2.2 compliant, full keyboard navigation, ARIA attributes
Customization	Templates for items, groups, headers; CSS theming support

方面	详情
选择	从预定义列表中选择单项或输入自定义值
数据源	本地数组、远程DataManager、OData、Web API、异步数据
过滤	内置过滤，支持可配置策略（StartsWith、Contains、EndsWith）
性能	针对大型数据集（10000+条）的虚拟滚动
表单	适用于模板驱动表单（ngModel）和响应式表单（FormControl）
无障碍	符合WCAG 2.2标准，支持完整键盘导航、ARIA属性
自定义	项、分组、页眉模板；CSS主题支持

Documentation Navigation Guide

文档导航指南

📄 Getting Started

📄 快速入门

Read: references/combobox-getting-started.md

Install
```
@syncfusion/ej2-angular-dropdowns
```
package
Set up Angular 21+ project with standalone components
Import required modules and CSS themes
Create your first ComboBox with minimal code
Basic event handlers and configuration

阅读： references/combobox-getting-started.md

安装
```
@syncfusion/ej2-angular-dropdowns
```
包
设置Angular 21+独立组件项目
导入所需模块和CSS主题
用最少代码创建第一个ComboBox
基本事件处理和配置

📄 Data Binding & Sources

📄 数据绑定与源

Read: references/combobox-data-binding.md

Bind to local arrays (strings, numbers, objects)
Map text and value fields for complex data
Remote data from Web APIs, OData services
DataManager configuration for different data adapters
Async pipe for RxJS Observables
Handling dynamic data updates

阅读： references/combobox-data-binding.md

绑定到本地数组（字符串、数字、对象）
为复杂数据映射文本和值字段
来自Web API、OData服务的远程数据
针对不同数据适配器的DataManager配置
RxJS Observables的async管道
处理动态数据更新

📄 Filtering & Search

📄 过滤与搜索

Read: references/combobox-filtering-and-search.md

Enable filtering with
```
allowFiltering
```
property
Configure filter types (StartsWith, Contains, EndsWith, etc.)
Case-sensitive filtering for strict matching
Diacritics filtering for accent-insensitive search
Debounce delay to optimize remote requests
Minimum filter character requirements
Custom filtering with remote queries

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

使用
```
allowFiltering
```
属性启用过滤
配置过滤类型（StartsWith、Contains、EndsWith等）
严格匹配的大小写敏感过滤
忽略变音符号的过滤
优化远程请求的防抖延迟
最小过滤字符要求
远程查询的自定义过滤

📄 Grouping & Templates

📄 分组与模板

Read: references/combobox-grouping-and-templates.md

Group items by category using
```
groupBy
```
field
Item templates for custom item rendering
Group header templates (inline and fixed)
Footer templates for additional information
Combining multiple templates effectively
Template performance optimization

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

使用
```
groupBy
```
字段按类别分组项
自定义项渲染的项模板
分组页眉模板（内联和固定）
附加信息的页脚模板
有效组合多个模板
模板性能优化

📄 Advanced Feature Configuration

📄 高级功能配置

Read: references/combobox-feature-configuration.md

Disable specific items or the entire component
Read-only mode for display-only scenarios
Virtual scrolling for thousands of items
Dynamic resize behavior
Allow custom values not in the list
Styling and theme integration
RTL support for Arabic/Hebrew

阅读： references/combobox-feature-configuration.md

禁用特定项或整个组件
仅显示场景的只读模式
数千条数据的虚拟滚动
动态调整大小行为
允许列表中不存在的自定义值
样式和主题集成
阿拉伯语/希伯来语的RTL支持

📄 Form Support & Validation

📄 表单支持与验证

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

Two-way binding with template-driven forms (ngModel)
Reactive forms with FormControl and FormGroup
Built-in and custom validators
Form submission and validation state
Disabled ComboBox in form context
Error message display patterns

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

模板驱动表单的双向绑定（ngModel）
带有FormControl和FormGroup的响应式表单
内置和自定义验证器
表单提交和验证状态
表单上下文中的禁用ComboBox
错误消息显示模式

📄 Accessibility & Localization

📄 无障碍与本地化

Read: references/combobox-accessibility-and-localization.md

WCAG 2.2, Section 508, and ADA compliance
Keyboard navigation shortcuts (arrow keys, Tab, Enter, Escape)
Screen reader support with ARIA attributes
Focus management and visual indicators
Localization strings for different languages
Right-to-left (RTL) language support

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

符合WCAG 2.2、Section 508和ADA标准
键盘导航快捷键（箭头键、Tab、Enter、Escape）
带有ARIA属性的屏幕阅读器支持
焦点管理和视觉指示器
不同语言的本地化字符串
从右到左（RTL）语言支持

📄 Advanced Patterns & How-To Guides

📄 高级模式与操作指南

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

Autofill suggestions for autocomplete behavior
Cascading ComboBoxes with dependent dropdowns
Icons and emoji support in list items
Resizable popup for better visibility
Real-world patterns (search, live data, grouping)
Performance optimization techniques

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

自动完成行为的自动填充建议
依赖下拉框的级联ComboBox
列表项中的图标和表情符号支持
更好可见性的可调整大小弹出框
实际场景模式（搜索、实时数据、分组）
性能优化技巧

📄 API Reference

📄 API参考

Read: references/combobox-api.md

Complete properties reference with types, defaults, and examples
All methods with signatures, parameters, and usage examples
All events with payload types and handler examples
Notes on template syntax, two-way binding, and virtual scrolling
Links to official Syncfusion documentation

阅读： references/combobox-api.md

完整的属性参考，包含类型、默认值和示例
所有方法的签名、参数和用法示例
所有事件的负载类型和处理示例
模板语法、双向绑定和虚拟滚动的说明
官方Syncfusion文档链接

Quick Start Example

快速入门示例

Minimal Setup (5 minutes)

最小设置（5分钟）

typescript

// app.component.ts
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ComboBoxComponent, ComboBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, ComboBoxModule],
  template: `
    <ejs-combobox
      [dataSource]="data"
      fields="{ text: 'text', value: 'id' }"
      placeholder="Select a language"
      [(ngModel)]="selectedValue">
    </ejs-combobox>
  `
})
export class AppComponent {
  selectedValue = '';
  data = [
    { id: '1', text: 'JavaScript' },
    { id: '2', text: 'TypeScript' },
    { id: '3', text: 'Angular' },
    { id: '4', text: 'React' }
  ];
}

What's happening:

Import

ComboBoxComponent

from

@syncfusion/ej2-angular-dropdowns

Define data array with objects (id, text)
Use
```
fields
```
to map text and value fields
Bind selected value with
```
[(ngModel)]
```
Set placeholder for empty state

typescript

// app.component.ts
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ComboBoxComponent, ComboBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, ComboBoxModule],
  template: `
    <ejs-combobox
      [dataSource]="data"
      fields="{ text: 'text', value: 'id' }"
      placeholder="选择语言"
      [(ngModel)]="selectedValue">
    </ejs-combobox>
  `
})
export class AppComponent {
  selectedValue = '';
  data = [
    { id: '1', text: 'JavaScript' },
    { id: '2', text: 'TypeScript' },
    { id: '3', text: 'Angular' },
    { id: '4', text: 'React' }
  ];
}

说明：

从

@syncfusion/ej2-angular-dropdowns

导入

ComboBoxComponent

定义带有对象（id、text）的数据数组
使用
```
fields
```
映射文本和值字段
使用
```
[(ngModel)]
```
绑定选中值
为空状态设置占位符

Common Patterns & Workflows

常见模式与工作流

Pattern 1: Autocomplete with Autofill

模式1：带自动填充的自动完成

typescript

[autofill]="true"              // Auto-complete suggestions
[allowFiltering]="true"        // Enable typing
filterType="StartsWith"        // Match from beginning

When to use: Skills, tags, email domains (user types 'j', sees 'JavaScript')

See: Advanced Patterns

typescript

[autofill]="true"              // 自动补全建议
[allowFiltering]="true"        // 启用输入
filterType="StartsWith"        // 从开头匹配

适用场景： 技能、标签、邮箱域名（用户输入'j'，显示'JavaScript'）

参见：高级模式

Pattern 2: Cascading Dependent Dropdowns

模式2：级联依赖下拉框

typescript

// Country → State → City relationship
onCountryChange() {
  this.states = this.getStatesFor(country);
}

onStateChange() {
  this.cities = this.getCitiesFor(state);
}

When to use: Address selection, hierarchical data (country/state/city)

See: Advanced Patterns

typescript

// 国家 → 州 → 城市关系
onCountryChange() {
  this.states = this.getStatesFor(country);
}

onStateChange() {
  this.cities = this.getCitiesFor(state);
}

适用场景： 地址选择、分层数据（国家/州/城市）

参见：高级模式

Pattern 3: Grouped Items with Icons

模式3：带图标的分组项

typescript

fields = { 
  text: 'Name', 
  value: 'Id', 
  groupBy: 'Category',
  iconCss: 'Icon'
};

When to use: Visual organization (languages with icons, file types)

See: Advanced Patterns

typescript

fields = { 
  text: 'Name', 
  value: 'Id', 
  groupBy: 'Category',
  iconCss: 'Icon'
};

适用场景： 视觉组织（带图标的语言、文件类型）

参见：高级模式

Pattern 4: Resizable Dropdown for Long Content

模式4：长内容的可调整大小下拉框

typescript

[allowResize]="true"           // Enable resize handle
itemTemplate="customTemplate"  // Show rich content

When to use: Product listings, descriptions, detailed information

See: Advanced Patterns

typescript

[allowResize]="true"           // 启用调整大小手柄
itemTemplate="customTemplate"  // 显示富内容

适用场景： 产品列表、描述、详细信息

参见：高级模式

Key Props & Configuration

关键属性与配置

Essential Properties

核心属性

Property	Type	Default	When to Use
`dataSource`	Array \| DataManager	`[]`	Specify items to display
`fields`	Object	`{ text, value }`	Map data structure to ComboBox
`placeholder`	string	`''`	Show hint when empty
`allowFiltering`	boolean	`false`	Enable search/filter
`allowCustom`	boolean	`false`	Allow values not in list
`readonly`	boolean	`false`	Prevent editing
`enabled`	boolean	`true`	Disable entire component
`[(ngModel)]`	any	undefined	Two-way value binding

属性	类型	默认值	适用场景
`dataSource`	Array \| DataManager	`[]`	指定要显示的项
`fields`	Object	`{ text, value }`	将数据结构映射到ComboBox
`placeholder`	string	`''`	空状态显示提示
`allowFiltering`	boolean	`false`	启用搜索/过滤
`allowCustom`	boolean	`false`	允许列表中不存在的值
`readonly`	boolean	`false`	阻止编辑
`enabled`	boolean	`true`	禁用整个组件
`[(ngModel)]`	any	undefined	双向值绑定

Advanced Properties

高级属性

Property	Type	When to Use
`itemTemplate`	string \| TemplateRef	Custom item rendering
`groupTemplate`	string \| TemplateRef	Custom group header display
`footerTemplate`	string \| TemplateRef	Add info below list
`enableVirtualization`	boolean	10,000+ items (performance)
`groupBy`	string	Organize items by category
`filterType`	string	StartsWith \| Contains \| EndsWith
`debounceDelay`	number	Remote data request delay

属性	类型	适用场景
`itemTemplate`	string \| TemplateRef	自定义项渲染
`groupTemplate`	string \| TemplateRef	自定义分组页眉显示
`footerTemplate`	string \| TemplateRef	在列表下方添加信息
`enableVirtualization`	boolean	10000+条数据（性能优化）
`groupBy`	string	按类别组织项
`filterType`	string	StartsWith \| Contains \| EndsWith
`debounceDelay`	number	远程数据请求延迟

Component Lifecycle

组件生命周期

1. CREATE: Component initialized
   ↓
2. DATA BIND: dataSource loaded & displayed
   ↓
3. USER INTERACTION: typing, clicking, keyboard
   ↓
4. FILTER/SEARCH: items filtered based on input
   ↓
5. SELECT: user chooses item or enters custom value
   ↓
6. VALUE UPDATE: ngModel updates, events fire
   ↓
7. DESTROY: component cleaned up

Key events to handle:

```
change
```
: When selected value changes
```
filtering
```
: When user types (filter queries)
```
select
```
: When item is selected
```
focus
```
: When component gets focus
```
blur
```
: When component loses focus

1. 创建：组件初始化
   ↓
2. 数据绑定：dataSource加载并显示
   ↓
3. 用户交互：输入、点击、键盘操作
   ↓
4. 过滤/搜索：根据输入过滤项
   ↓
5. 选择：用户选择项或输入自定义值
   ↓
6. 值更新：ngModel更新，事件触发
   ↓
7. 销毁：组件清理

需要处理的关键事件：

```
change
```
：选中值更改时
```
filtering
```
：用户输入时（过滤查询）
```
select
```
：项被选中时
```
focus
```
：组件获得焦点时
```
blur
```
：组件失去焦点时

Workflow Decision Tree

工作流决策树

Need to implement ComboBox? Follow this decision tree:

1. Do you have data to display?
   ├─ YES: Go to "Data Binding & Sources" reference
   └─ NO: Define your data array first

2. Do users need to search/filter?
   ├─ YES: Go to "Filtering & Search" reference
   └─ NO: allowFiltering = false (default)

3. Do you need to group items?
   ├─ YES: Go to "Grouping & Templates" reference
   └─ NO: Skip grouping configuration

4. Are you using a form?
   ├─ YES: Go to "Form Support & Validation" reference
   └─ NO: Use standalone ComboBox

5. Is accessibility required?
   ├─ YES: Go to "Accessibility & Localization" reference
   └─ NO: Still recommended for compliance

6. Performance issues with large datasets?
   ├─ YES: Enable virtual scrolling + pagination
   └─ NO: Standard rendering is fine

需要实现ComboBox？遵循以下决策树：

1. 你有要显示的数据吗？
   ├─ 是：参考"数据绑定与源"
   └─ 否：先定义你的数据数组

2. 用户需要搜索/过滤吗？
   ├─ 是：参考"过滤与搜索"
   └─ 否：allowFiltering = false（默认）

3. 需要分组项吗？
   ├─ 是：参考"分组与模板"
   └─ 否：跳过分组配置

4. 在表单中使用吗？
   ├─ 是：参考"表单支持与验证"
   └─ 否：使用独立ComboBox

5. 需要无障碍支持吗？
   ├─ 是：参考"无障碍与本地化"
   └─ 否：仍建议遵循合规要求

6. 大型数据集存在性能问题？
   ├─ 是：启用虚拟滚动 + 分页
   └─ 否：标准渲染即可

Next Steps

下一步

Start here: Getting Started - Set up your first ComboBox
Bind data: Data Binding & Sources - Connect to your data
Add search: Filtering & Search - Enable user filtering
Customize: Grouping & Templates - Style and organize display
Advanced: Advanced Patterns & How-To - Autofill, cascading, icons, resizing
Features: Feature Configuration - Enable advanced features
Integrate: Form Support - Connect to forms
Polish: Accessibility - Ensure compliance
Reference: API Reference - Full properties, methods, and events reference

从这里开始： 快速入门 - 设置你的第一个ComboBox
绑定数据： 数据绑定与源 - 连接你的数据
添加搜索： 过滤与搜索 - 启用用户过滤
自定义： 分组与模板 - 样式和组织显示
高级功能： 高级模式与操作指南 - 自动填充、级联、图标、调整大小
功能配置： 功能配置 - 启用高级功能
集成表单： 表单支持 - 连接到表单
优化： 无障碍 - 确保合规
参考： API参考 - 完整的属性、方法和事件参考

Additional Resources

额外资源

DropDownList

A single-value selection component from a predefined list. Supports local and remote data sources, filtering, grouping, custom templates, virtualization for large datasets, and full Angular forms integration.

从预定义列表中选择单项的组件。支持本地和远程数据源、过滤、分组、自定义模板、大型数据集虚拟化以及完整的Angular表单集成。

Documentation Navigation Guide

文档导航指南

Getting Started

快速入门

📄 Read: references/dropdownlist-getting-started.md

Installation and Angular CLI setup
Installing
```
@syncfusion/ej2-angular-dropdowns
```
CSS/theme imports for Material3
Adding
```
<ejs-dropdownlist>
```
to the template
Basic data binding with
```
[dataSource]
```
Popup height/width configuration
Two-way binding with
```
[(value)]
```

📄 阅读： references/dropdownlist-getting-started.md

安装和Angular CLI设置
安装
```
@syncfusion/ej2-angular-dropdowns
```
Material3的CSS/主题导入
在模板中添加
```
<ejs-dropdownlist>
```
使用
```
[dataSource]
```
的基本数据绑定
弹出框高度/宽度配置
使用
```
[(value)]
```
的双向绑定

Data Binding

数据绑定

📄 Read: references/dropdownlist-data-binding.md

Binding primitive arrays (strings, numbers)
Binding arrays of objects with
```
[fields]
```
mapping
Binding to nested/complex objects
Remote data via
```
DataManager
```
(OData, Web API)
Async pipe with Observable data streams
Value binding (primitive and object types with
```
allowObjectBinding
```
)

📄 阅读： references/dropdownlist-data-binding.md

绑定原始数组（字符串、数字）
使用
```
[fields]
```
映射绑定对象数组
绑定嵌套/复杂对象
通过
```
DataManager
```
绑定远程数据（OData、Web API）
Observable数据流的async管道
值绑定（原始类型和使用
```
allowObjectBinding
```
的对象类型）

Filtering

过滤

📄 Read: references/dropdownlist-filtering.md

Enabling search with
```
[allowFiltering]
```
Using the
```
filtering
```
event and
```
updateData()
```
method
Minimum character threshold before filtering starts
Filter types:
```
contains
```
,
```
startsWith
```
,
```
endsWith
```
Case-sensitive filtering
Diacritics/accent-insensitive filtering
Debounce delay for performance optimization

📄 阅读： references/dropdownlist-filtering.md

使用
```
[allowFiltering]
```
启用搜索
使用
```
filtering
```
事件和
```
updateData()
```
方法
过滤开始前的最小字符阈值
过滤类型：
```
contains
```
、
```
startsWith
```
、
```
endsWith
```
大小写敏感过滤
忽略变音符号/重音的过滤
性能优化的防抖延迟

Templates

模板

📄 Read: references/dropdownlist-templates.md

Item template: customize each list item
Value template: customize the selected value display
Group template: customize group header appearance
Header template: static element at popup top
Footer template: static element at popup bottom
No-records template: empty state display
Action failure template: error state display

📄 阅读： references/dropdownlist-templates.md

项模板：自定义每个列表项
值模板：自定义选中值的显示
分组模板：自定义分组页眉外观
页眉模板：弹出框顶部的静态元素
页脚模板：弹出框底部的静态元素
无数据模板：空状态显示
操作失败模板：错误状态显示

Grouping & Virtualization

分组与虚拟化

📄 Read: references/dropdownlist-grouping-and-virtualization.md

Grouping items with
```
groupBy
```
field
Inline and fixed floating group headers
Virtual scrolling with
```
[enableVirtualization]
```
for large lists
Virtual scrolling with remote data
Combining filtering and virtualization
Customizing item count in virtual mode

📄 阅读： references/dropdownlist-grouping-and-virtualization.md

使用
```
groupBy
```
字段分组项
内联和固定浮动分组页眉
使用
```
[enableVirtualization]
```
针对大型列表的虚拟滚动
远程数据的虚拟滚动
结合过滤和虚拟化
虚拟模式下的自定义项数量

Disabled Items & Forms

禁用项与表单

📄 Read: references/dropdownlist-disabled-items-and-forms.md

Disabling specific items via
```
fields.disabled
```
Dynamic
```
disableItem()
```
method (by value, index, or element)
Disabling the entire component with
```
[enabled]="false"
```
Template-driven forms with
```
[(ngModel)]
```
Reactive forms with
```
FormControl
```
and
```
FormGroup
```

📄 阅读： references/dropdownlist-disabled-items-and-forms.md

通过
```
fields.disabled
```
禁用特定项
动态
```
disableItem()
```
方法（按值、索引或元素）
使用
```
[enabled]="false"
```
禁用整个组件
使用
```
[(ngModel)]
```
的模板驱动表单
使用
```
FormControl
```
和
```
FormGroup
```
的响应式表单

Customization & Styling

自定义与样式

📄 Read: references/dropdownlist-customization-and-styling.md

CSS overrides for wrapper, icon, focus states
Outline theme focus customization
Popup appearance and list item styles
Float label and placeholder styling
Mandatory asterisk pattern
Localization with
```
L10n
```
class
RTL (right-to-left) support

📄 阅读： references/dropdownlist-customization-and-styling.md

包装器、图标、焦点状态的CSS覆盖
轮廓主题焦点自定义
弹出框外观和列表项样式
浮动标签和占位符样式
必填星号模式
使用
```
L10n
```
类进行本地化
RTL（从右到左）支持

How-To Recipes

操作指南

📄 Read: references/dropdownlist-how-to.md

Add / remove / clear items dynamically
Close popup programmatically
Cascading DropDownLists
Customize group header template
Highlight filtered characters
Incremental search behavior
Modify remote data results
Remote data item count display
Tooltip on list items
Value change event handling
Icon support in list items

📄 阅读： references/dropdownlist-how-to.md

动态添加/删除/清除项
以编程方式关闭弹出框
级联DropDownList
自定义分组页眉模板
高亮过滤字符
增量搜索行为
修改远程数据结果
远程数据项计数显示
列表项的工具提示
值更改事件处理
列表项中的图标支持

API Reference

API参考

📄 Read: references/dropdownlist-api.md

Complete properties reference with types, defaults, and usage examples
All methods with signatures, parameters, and return types
All events with argument interfaces and usage examples

Interface details:

FieldSettingsModel

ChangeEventArgs

SelectEventArgs

PopupEventArgs

FilteringEventArgs

Quick-reference summary tables for properties, methods, and events

📄 阅读： references/dropdownlist-api.md

完整的属性参考，包含类型、默认值和用法示例
所有方法的签名、参数和返回类型
所有事件的参数接口和用法示例

接口详情：

FieldSettingsModel

、

ChangeEventArgs

、

SelectEventArgs

、

PopupEventArgs

、

FilteringEventArgs

属性、方法和事件的速查表

Quick Start Example

快速入门示例

typescript

import { Component, OnInit } from '@angular/core';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [DropDownListModule],
  selector: 'app-root',
  template: `
    <ejs-dropdownlist
      id="ddl"
      [dataSource]="sports"
      [fields]="fields"
      placeholder="Select a sport"
      [(value)]="selectedValue"
      (change)="onChange($event)">
    </ejs-dropdownlist>
    <p>Selected: {{ selectedValue }}</p>
  `
})
export class AppComponent implements OnInit {
  public sports: { id: number; name: string }[] = [];
  public fields = { text: 'name', value: 'id' };
  public selectedValue: number = 2;

  ngOnInit() {
    this.sports = [
      { id: 1, name: 'Badminton' },
      { id: 2, name: 'Cricket' },
      { id: 3, name: 'Football' },
      { id: 4, name: 'Tennis' }
    ];
  }

  onChange(args: any) {
    this.selectedValue = args.value;
  }
}

typescript

import { Component, OnInit } from '@angular/core';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [DropDownListModule],
  selector: 'app-root',
  template: `
    <ejs-dropdownlist
      id="ddl"
      [dataSource]="sports"
      [fields]="fields"
      placeholder="选择运动项目"
      [(value)]="selectedValue"
      (change)="onChange($event)">
    </ejs-dropdownlist>
    <p>已选择：{{ selectedValue }}</p>
  `
})
export class AppComponent implements OnInit {
  public sports: { id: number; name: string }[] = [];
  public fields = { text: 'name', value: 'id' };
  public selectedValue: number = 2;

  ngOnInit() {
    this.sports = [
      { id: 1, name: 'Badminton' },
      { id: 2, name: 'Cricket' },
      { id: 3, name: 'Football' },
      { id: 4, name: 'Tennis' }
    ];
  }

  onChange(args: any) {
    this.selectedValue = args.value;
  }
}

Common Patterns

常见模式

Searchable Dropdown

可搜索下拉框

typescript

// Enable filtering in template
// <ejs-dropdownlist [allowFiltering]="true" (filtering)="onFilter($event)">
import { FilteringEventArgs } from '@syncfusion/ej2-angular-dropdowns';
import { Query } from '@syncfusion/ej2-data';

onFilter(args: FilteringEventArgs) {
  let query = new Query();
  query = args.text !== '' 
    ? query.where('name', 'contains', args.text, true) 
    : query;
  args.updateData(this.sports, query);
}

typescript

// 在模板中启用过滤
// <ejs-dropdownlist [allowFiltering]="true" (filtering)="onFilter($event)">
import { FilteringEventArgs } from '@syncfusion/ej2-angular-dropdowns';
import { Query } from '@syncfusion/ej2-data';

onFilter(args: FilteringEventArgs) {
  let query = new Query();
  query = args.text !== '' 
    ? query.where('name', 'contains', args.text, true) 
    : query;
  args.updateData(this.sports, query);
}

Remote Data Dropdown

远程数据下拉框

🔒 Security policy — remote data is a restricted pattern. Binding DropDownList to a remote endpoint requires a security review (see Security & Trust Boundary) before use in production. Remote data binding details and requirements are documented in references/dropdownlist-data-binding.md. No remote
DataManager
example is provided here by default.

🔒 安全策略 — 远程数据是受限模式。 将DropDownList绑定到远程端点需要经过安全审查（参见安全与信任边界）才能在生产环境中使用。远程数据绑定的详细信息和要求记录在references/dropdownlist-data-binding.md中。默认不提供远程
DataManager
示例。

Reactive Form Integration

响应式表单集成

typescript

import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

// In component:
form = this.fb.group({ sport: ['Cricket', Validators.required] });
// In template:
// <form [formGroup]="form">
//   <ejs-dropdownlist formControlName="sport" [dataSource]="sports"></ejs-dropdownlist>
// </form>

typescript

import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

// 在组件中：
form = this.fb.group({ sport: ['Cricket', Validators.required] });
// 在模板中：
// <form [formGroup]="form">
//   <ejs-dropdownlist formControlName="sport" [dataSource]="sports"></ejs-dropdownlist>
// </form>

Key Props

关键属性

Property	Type	Description
`dataSource`	`any[] \| DataManager`	Data for the list
`fields`	`FieldSettingsModel`	Maps text, value, groupBy, disabled, iconCss
`value`	`string \| number \| boolean \| object`	Selected value (supports two-way binding)
`placeholder`	`string`	Input placeholder text
`allowFiltering`	`boolean`	Enable search box in popup
`filterType`	`'contains' \| 'startsWith' \| 'endsWith'`	Filter match strategy
`enableVirtualization`	`boolean`	Virtual scrolling for large lists
`popupHeight` / `popupWidth`	`string \| number`	Popup dimensions
`enabled`	`boolean`	Enable/disable entire component
`allowObjectBinding`	`boolean`	Bind full object as value
`ignoreCase`	`boolean`	Case-insensitive filtering (default: true)
`ignoreAccent`	`boolean`	Diacritics-insensitive filtering
`debounceDelay`	`number`	Delay (ms) before filter triggers
`itemTemplate`	`string`	Template for list items
`valueTemplate`	`string`	Template for selected value display
`noRecordsTemplate`	`string`	Empty state message

属性	类型	描述
`dataSource`	`any[] \| DataManager`	列表数据
`fields`	`FieldSettingsModel`	映射text、value、groupBy、disabled、iconCss
`value`	`string \| number \| boolean \| object`	选中值（支持双向绑定）
`placeholder`	`string`	输入占位符文本
`allowFiltering`	`boolean`	在弹出框中启用搜索框
`filterType`	`'contains' \| 'startsWith' \| 'endsWith'`	过滤匹配策略
`enableVirtualization`	`boolean`	大型列表的虚拟滚动
`popupHeight` / `popupWidth`	`string \| number`	弹出框尺寸
`enabled`	`boolean`	启用/禁用整个组件
`allowObjectBinding`	`boolean`	将完整对象绑定为值
`ignoreCase`	`boolean`	大小写不敏感过滤（默认：true）
`ignoreAccent`	`boolean`	忽略变音符号的过滤
`debounceDelay`	`number`	过滤触发前的延迟（毫秒）
`itemTemplate`	`string`	列表项模板
`valueTemplate`	`string`	选中值显示模板
`noRecordsTemplate`	`string`	空状态消息

Common Use Cases

常见用例

Form field with validation → See references/dropdownlist-disabled-items-and-forms.md

Large list (1000+ items) → Enable

[enableVirtualization]="true"

— see references/dropdownlist-grouping-and-virtualization.md

Country/State/City cascading → See references/dropdownlist-how-to.md

Custom item rendering (icons, multi-column) → See references/dropdownlist-templates.md

Remote API data → See references/dropdownlist-data-binding.md

带验证的表单字段 → 参见references/dropdownlist-disabled-items-and-forms.md

大型列表（1000+条） → 启用

[enableVirtualization]="true"

— 参见references/dropdownlist-grouping-and-virtualization.md

国家/州/城市级联 → 参见references/dropdownlist-how-to.md

自定义项渲染（图标、多列）→ 参见references/dropdownlist-templates.md

远程API数据 → 参见references/dropdownlist-data-binding.md

ListBox

A list-based selection component enabling single or multi-item selection. Supports data binding, templates, drag-and-drop reordering and transfer, sorting, grouping, and comprehensive accessibility features.

基于列表的选择组件，支持单项或多项选择。支持数据绑定、模板、拖放重新排序和传输、排序、分组以及全面的无障碍功能。

Component Overview

组件概述

The Syncfusion ListBox is a high-performance dropdown list replacement with advanced features:

Feature	Benefit
Multiple Selection Modes	Single, multiple, or checkbox selection
Data Binding	Local arrays, complex objects, or remote services
Drag & Drop	Reorder items or transfer between lists
Customization	Icons, templates, grouping, sorting
Accessibility	WCAG 2.2, screen readers, keyboard navigation
Performance	Efficient rendering with large datasets

Syncfusion ListBox是高性能下拉列表替代品，具有以下高级功能：

功能	优势
多种选择模式	单项、多项或复选框选择
数据绑定	本地数组、复杂对象或远程服务
拖放	重新排序项或在列表间传输
自定义	图标、模板、分组、排序
无障碍	WCAG 2.2、屏幕阅读器、键盘导航
性能	高效渲染大型数据集

Documentation Navigation Guide

文档导航指南

Getting Started

快速入门

📄 Read: references/listbox-getting-started.md

Installation and package setup
Angular standalone vs NgModule patterns
Basic component initialization
CSS imports and theme selection
Binding local data sources
Running and testing the application

📄 阅读： references/listbox-getting-started.md

安装和包设置
Angular独立组件与NgModule模式
基本组件初始化
CSS导入和主题选择
绑定本地数据源
运行和测试应用

Selection Modes and Interactions

选择模式与交互

📄 Read: references/listbox-selection-modes.md

Single item selection
Multiple item selection with SHIFT/CTRL
Checkbox selection mode
Select all functionality
Handling change events
Getting selected items programmatically

📄 阅读： references/listbox-selection-modes.md

单项选择
使用SHIFT/CTRL的多项选择
复选框选择模式
全选功能
处理更改事件
以编程方式获取选中项

Data Binding and Field Mapping

数据绑定与字段映射

📄 Read: references/listbox-data-binding.md

Binding array of strings
Binding array of objects
Binding complex nested objects
Remote data with DataManager and Query
Field mapping (text, value, groupBy, iconCss)
Troubleshooting data binding issues

📄 阅读： references/listbox-data-binding.md

绑定字符串数组
绑定对象数组
绑定复杂嵌套对象
使用DataManager和Query的远程数据
字段映射（text、value、groupBy、iconCss）
数据绑定问题排查

Drag-and-Drop Features

拖放功能

📄 Read: references/listbox-drag-and-drop-features.md

Single ListBox drag-and-drop reordering
Dual ListBox drag-and-drop transfer
Drag and drop events (dragStart, drag, drop)
Scope configuration for multiple lists
Event handling and item manipulation
Real-world dual ListBox patterns

📄 阅读： references/listbox-drag-and-drop-features.md

单个ListBox的拖放重新排序
双ListBox的拖放传输
拖放事件（dragStart、drag、drop）
多个列表的范围配置
事件处理和项操作
实际双ListBox模式

Customization and Styling

自定义与样式

📄 Read: references/listbox-customization.md

Icons and iconCss field mapping
Custom item templates
Grouping items by category
Sorting items (ascending/descending)
CSS styling and theming
Theme Studio integration
Responsive design

📄 阅读： references/listbox-customization.md

图标和iconCss字段映射
自定义项模板
按类别分组项
项排序（升序/降序）
CSS样式和主题
Theme Studio集成
响应式设计

Practical Implementation Examples

实际实现示例

📄 Read: references/listbox-practical-examples.md

Filtering ListBox items
Form submission with selected items
Enable/disable items conditionally
Scroller for large datasets
Real-world use cases
Common troubleshooting scenarios

📄 阅读： references/listbox-practical-examples.md

过滤ListBox项
表单提交选中项
有条件地启用/禁用项
大型数据集的滚动器
实际用例
常见问题排查场景

How-To Guides and Common Tasks

操作指南与常见任务

📄 Read: references/listbox-how-to-guides.md

Add items programmatically
Select items programmatically
Enable or disable items dynamically
Enable scroller for large datasets
Filter ListBox data with input
Submit selected items in forms

📄 阅读： references/listbox-how-to-guides.md

以编程方式添加项
以编程方式选择项
动态启用或禁用项
为大型数据集启用滚动器
用输入框过滤ListBox数据
在表单中提交选中项

API Reference

API参考

📄 Read: references/listbox-api.md

All component properties with types, defaults, and examples
All public methods with parameter signatures and usage examples
All events with event argument interfaces and handler patterns

Interface definitions:

FieldSettingsModel

SelectionSettingsModel

ToolbarSettingsModel

Event arg interfaces:

ListBoxChangeEventArgs

DragEventArgs

DropEventArgs

BeforeItemRenderEventArgs

FilteringEventArgs

SourceDestinationModel

Enum definitions:

SelectionMode

SortOrder

FilterType

ToolBarPosition

CheckBoxPosition

📄 阅读： references/listbox-api.md

所有组件属性，包含类型、默认值和示例
所有公共方法的参数签名和用法示例
所有事件的参数接口和处理模式

接口定义：

FieldSettingsModel

、

SelectionSettingsModel

、

ToolbarSettingsModel

事件参数接口：

ListBoxChangeEventArgs

、

DragEventArgs

、

DropEventArgs

、

BeforeItemRenderEventArgs

、

FilteringEventArgs

、

SourceDestinationModel

枚举定义：

SelectionMode

、

SortOrder

、

FilterType

、

ToolBarPosition

、

CheckBoxPosition

Quick Start Example

快速入门示例

Basic ListBox with Local Data

带本地数据的基础ListBox

typescript

import { Component, OnInit } from '@angular/core';
import { ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  imports: [ListBoxModule],
  standalone: true,
  selector: 'app-listbox',
  template: `
    <ejs-listbox 
      [dataSource]="items"
      [selectionSettings]="{ mode: 'Multiple' }">
    </ejs-listbox>
  `
})
export class ListBoxComponent implements OnInit {
  public items: { [key: string]: Object }[] = [];

  ngOnInit(): void {
    this.items = [
      { text: 'Option 1', id: '1' },
      { text: 'Option 2', id: '2' },
      { text: 'Option 3', id: '3' }
    ];
  }
}

typescript

import { Component, OnInit } from '@angular/core';
import { ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  imports: [ListBoxModule],
  standalone: true,
  selector: 'app-listbox',
  template: `
    <ejs-listbox 
      [dataSource]="items"
      [selectionSettings]="{ mode: 'Multiple' }">
    </ejs-listbox>
  `
})
export class ListBoxComponent implements OnInit {
  public items: { [key: string]: Object }[] = [];

  ngOnInit(): void {
    this.items = [
      { text: '选项1', id: '1' },
      { text: '选项2', id: '2' },
      { text: '选项3', id: '3' }
    ];
  }
}

With Styles

带样式

⚠️ Security note: These imports are resolved from
node_modules
at build time. Ensure the installed Syncfusion packages match your pinned versions in
package-lock.json
or
yarn.lock
before building. Do not source these files from a CDN without Subresource Integrity (SRI) hashes.

css

/* In your global styles.css */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-dropdowns/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';
@import '@syncfusion/ej2-lists/styles/material3.css';

⚠️ 安全提示： 这些导入在构建时从
node_modules
解析。构建前确保已安装的Syncfusion包与
package-lock.json
或
yarn.lock
中的固定版本匹配。请勿从CDN获取这些文件，除非带有子资源完整性（SRI）哈希。

css

/* 在全局styles.css中 */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-dropdowns/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';
@import '@syncfusion/ej2-lists/styles/material3.css';

Common Patterns

常见模式

Selection with Change Event

带更改事件的选择

typescript

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

selectedValues: string[] = [];

onSelectionChange(args: ListBoxChangeEventArgs): void {
  this.selectedValues = args.value as string[];
}

Template:

html

<ejs-listbox
  [dataSource]="items"
  (change)="onSelectionChange($event)">
</ejs-listbox>

typescript

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

selectedValues: string[] = [];

onSelectionChange(args: ListBoxChangeEventArgs): void {
  this.selectedValues = args.value as string[];
}

模板：

html

<ejs-listbox
  [dataSource]="items"
  (change)="onSelectionChange($event)">
</ejs-listbox>

Dual ListBox for Transfer

用于传输的双ListBox

typescript

sourceItems = [
  { text: 'Available Item 1', id: '1' },
  { text: 'Available Item 2', id: '2' }
];

selectedItems = [];

Template:

html

<div style="display: flex; gap: 20px;">
  <div>
    <h4>Available Items</h4>
    <ejs-listbox
      [dataSource]="sourceItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
  
  <div>
    <h4>Selected Items</h4>
    <ejs-listbox
      [dataSource]="selectedItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
</div>

typescript

sourceItems = [
  { text: '可用项1', id: '1' },
  { text: '可用项2', id: '2' }
];

selectedItems = [];

模板：

html

<div style="display: flex; gap: 20px;">
  <div>
    <h4>可用项</h4>
    <ejs-listbox
      [dataSource]="sourceItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
  
  <div>
    <h4>已选项目</h4>
    <ejs-listbox
      [dataSource]="selectedItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
</div>

Filtered ListBox

过滤后的ListBox

typescript

allItems = [
  { text: 'Apple', category: 'Fruit' },
  { text: 'Carrot', category: 'Vegetable' },
  { text: 'Banana', category: 'Fruit' }
];

get filteredItems() {
  return this.allItems.filter(item => 
    item.text.toLowerCase().includes(this.searchTerm.toLowerCase())
  );
}

typescript

allItems = [
  { text: 'Apple', category: 'Fruit' },
  { text: 'Carrot', category: 'Vegetable' },
  { text: 'Banana', category: 'Fruit' }
];

get filteredItems() {
  return this.allItems.filter(item => 
    item.text.toLowerCase().includes(this.searchTerm.toLowerCase())
  );
}

Key Props

关键属性

Selection Configuration

选择配置

selectionSettings
:

{ mode: 'Single' | 'Multiple', showCheckbox: boolean, showSelectAll: boolean, checkboxPosition: 'Left' | 'Right' }

> Note: When using

showCheckbox: true

, you must inject

CheckBoxSelection

typescript

import { ListBoxComponent, CheckBoxSelection, ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';
ListBoxComponent.Inject(CheckBoxSelection);
@Component({ imports: [ListBoxModule] })
```- **`maximumSelectionLength`**: Limit how many items can be selected

value
: Get or set selected values (
```
string[] | number[] | boolean[]
```
)

selectionSettings
:

{ mode: 'Single' | 'Multiple', showCheckbox: boolean, showSelectAll: boolean, checkboxPosition: 'Left' | 'Right' }

> 注意： 使用

showCheckbox: true

时，必须注入

CheckBoxSelection

typescript

import { ListBoxComponent, CheckBoxSelection, ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';
ListBoxComponent.Inject(CheckBoxSelection);
@Component({ imports: [ListBoxModule] })
```- **`maximumSelectionLength`**: 限制可选择的项数

value
: 获取或设置选中值（
```
string[] | number[] | boolean[]
```
）

Data and Display

数据与显示

dataSource
: Array or DataManager with items

fields
:

{ text, value, groupBy, iconCss, disabled, htmlAttributes }

itemTemplate
: Template for rendering each list item
noRecordsTemplate
: Template shown when no items match

dataSource
: 数组或带项的DataManager

fields
:

{ text, value, groupBy, iconCss, disabled, htmlAttributes }

itemTemplate
: 渲染每个列表项的模板
noRecordsTemplate
: 无匹配项时显示的模板

Interactions

交互

allowDragAndDrop
: Enable drag-and-drop reordering/transfer
scope
: Identify related ListBoxes for drag-drop transfer
allowFiltering
: Show built-in filter search bar
filterBarPlaceholder
: Placeholder text for the filter bar

filterType
:

'StartsWith' | 'EndsWith' | 'Contains'

toolbarSettings
: Configure toolbar buttons for dual-ListBox transfer

allowDragAndDrop
: 启用拖放重新排序/传输
scope
: 标识用于拖放传输的相关ListBox
allowFiltering
: 显示内置过滤搜索栏
filterBarPlaceholder
: 过滤栏的占位符文本

filterType
:

'StartsWith' | 'EndsWith' | 'Contains'

toolbarSettings
: 配置双ListBox传输的工具栏按钮

Appearance

外观

height
: Height of the ListBox

sortOrder
:

'None' | 'Ascending' | 'Descending'

enabled
: Enable/disable component
enableRtl
: Right-to-left rendering
cssClass
: Additional CSS class

height
: ListBox的高度

sortOrder
:

'None' | 'Ascending' | 'Descending'

enabled
: 启用/禁用组件
enableRtl
: 从右到左渲染
cssClass
: 附加CSS类

Next Steps

下一步

Get Started: Read references/listbox-getting-started.md for setup instructions
Choose Selection Mode: Review references/listbox-selection-modes.md for your use case
Bind Data: See references/listbox-data-binding.md for data source options
Add Interactions: Explore references/listbox-drag-and-drop-features.md for advanced features
Customize: Check references/listbox-customization.md for styling options
See Examples: Review references/listbox-practical-examples.md for real-world implementations
API Reference: Consult references/listbox-api.md for the complete properties, methods, events, and interface definitions

快速入门: 阅读references/listbox-getting-started.md获取设置说明
选择选择模式: 查看references/listbox-selection-modes.md选择适合你的用例
绑定数据: 参见references/listbox-data-binding.md获取数据源选项
添加交互: 探索references/listbox-drag-and-drop-features.md获取高级功能
自定义: 查看references/listbox-customization.md获取样式选项
查看示例: 查看references/listbox-practical-examples.md获取实际实现
API参考: 查阅references/listbox-api.md获取完整的属性、方法、事件和接口定义

Common Use Cases

常见用例

Selection Forms: Multi-select dropdown replacement
Transfer Lists: Move items between lists (dual ListBox)
Categories: Group-based item organization
Filtering: Filter large datasets
Data Display: Show structured list data
Accessibility: Compliant selection interfaces

选择表单: 多选下拉框替代品
传输列表: 在列表间移动项（双ListBox）
分类: 基于分组的项组织
过滤: 过滤大型数据集
数据显示: 显示结构化列表数据
无障碍: 合规的选择界面

Mention

An autocomplete suggestion popup triggered by a typed character (default

) inside a target element. Supports user tagging, custom trigger characters, rich text integration, remote data, templates, and full accessibility.

当用户在目标元素中输入触发字符（默认

）时，会弹出自动完成建议框。支持用户标记、自定义触发字符、富文本集成、远程数据、模板以及完整的无障碍功能。

Component Overview & Architecture

组件概述与架构

The Mention component renders an autocomplete suggestion popup when the user types a trigger character (default

) inside a target element (a

div[contenteditable]

textarea

, or similar). It is designed for:

User tagging — tag people, teams, or resources using
```
@
```
Hashtag suggestions — use any custom character (
```
#
```
,
```
/
```
, etc.) as the trigger
Rich text integration — works with
```
contenteditable
```
divs and editors
Data binding — supports local arrays (strings, objects, complex objects) and remote DataManager sources
Filtering —
```
Contains
```
,
```
StartsWith
```
,
```
EndsWith
```
with configurable min-length, debounce, and spacing
Template customization — item, display, no-records, spinner, and group templates
Disabled items — mark individual list items as non-selectable
Accessibility — WCAG 2.2 compliant with full keyboard navigation and ARIA attributes

Mention组件在用户在目标元素（

div[contenteditable]

、

textarea

或类似元素）中输入触发字符（默认

）时，会渲染自动完成建议框。它适用于：

用户标记 — 使用
```
@
```
标记人员、团队或资源
标签建议 — 使用任何自定义字符（
```
#
```
、
```
/
```
等）作为触发符
富文本集成 — 适用于
```
contenteditable
```
div和编辑器
数据绑定 — 支持本地数组（字符串、对象、复杂对象）和远程DataManager源
过滤 —
```
Contains
```
、
```
StartsWith
```
、
```
EndsWith
```
，可配置最小长度、防抖和空格
模板自定义 — 项、显示、无数据、加载器和分组模板
禁用项 — 将单个列表项标记为不可选择
无障碍 — 符合WCAG 2.2标准，支持完整键盘导航和ARIA属性

Key Characteristics

关键特性

Aspect	Details
Trigger	Any single character via `mentionChar` (default `@` )
Target	Any `HTMLElement` or CSS selector string set via `target`
Data Sources	Local arrays (strings, objects), remote `DataManager` (OData, Web API)
Filtering	Built-in: `Contains` , `StartsWith` , `EndsWith` ; configurable `minLength` , `allowSpaces`
Display	`showMentionChar` controls whether the trigger character is shown with selected text
Suffix	`suffixText` appends a space or newline after the selected item
Accessibility	WCAG 2.2, Section 508, ADA; keyboard shortcuts: Arrow keys, Enter, Tab, Escape
Localization	`L10n.load()` for `noRecordsTemplate` locale key

方面	详情
触发符	通过 `mentionChar` 设置任何单个字符（默认 `@` ）
目标元素	通过 `target` 设置任何 `HTMLElement` 或CSS选择器字符串
数据源	本地数组（字符串、对象）、远程 `DataManager` （OData、Web API）
过滤	内置： `Contains` 、 `StartsWith` 、 `EndsWith` ；可配置 `minLength` 、 `allowSpaces`
显示	`showMentionChar` 控制选中文本是否显示触发字符
后缀	`suffixText` 在选中项后追加空格或换行符
无障碍	WCAG 2.2、Section 508、ADA；键盘快捷键：箭头键、Enter、Tab、Escape
本地化	使用 `L10n.load()` 设置 `noRecordsTemplate` 的区域键

Documentation Navigation Guide

文档导航指南

📄 Getting Started

📄 快速入门

Read: references/mention-getting-started.md

Install
```
@syncfusion/ej2-angular-dropdowns
```
package
Set up Angular 21+ project with standalone components
Import
```
MentionModule
```
and required CSS themes
Create a target
```
contenteditable
```
div
Bind
```
target
```
and basic
```
dataSource
```
Display/customize the mention character with
```
showMentionChar
```
and
```
mentionChar
```

阅读： references/mention-getting-started.md

安装
```
@syncfusion/ej2-angular-dropdowns
```
包
设置Angular 21+独立组件项目
导入
```
MentionModule
```
和所需CSS主题
创建目标
```
contenteditable
```
div
绑定
```
target
```
和基础
```
dataSource
```
使用
```
showMentionChar
```
和
```
mentionChar
```
显示/自定义标记字符

📄 Data Binding

📄 数据绑定

Read: references/mention-data-binding.md

Bind to local arrays of strings, JSON objects, and complex objects
Map
```
text
```
,
```
value
```
,
```
groupBy
```
, and
```
iconCss
```
via
```
fields
```
property
Remote data binding (restricted — requires security review; see Security & Trust Boundary)
Use the
```
query
```
property to scope remote requests

阅读： references/mention-data-binding.md

绑定到字符串、JSON对象和复杂对象的本地数组
通过
```
fields
```
属性映射
```
text
```
、
```
value
```
、
```
groupBy
```
和
```
iconCss
```
远程数据绑定（受限 — 需要安全审查；参见安全与信任边界）
使用
```
query
```
属性限制远程请求范围

📄 Filtering

📄 过滤

Read: references/mention-filtering.md

Control filter strategy with
```
filterType
```
(
```
Contains
```
,
```
StartsWith
```
,
```
EndsWith
```
)
Set minimum input length before triggering with
```
minLength
```
Allow spaces in the middle of a mention search with
```
allowSpaces
```
Limit visible suggestion count with
```
suggestionCount
```
Tune debounce delay for remote sources with
```
debounceDelay
```

阅读： references/mention-filtering.md

使用
```
filterType
```
控制过滤策略（
```
Contains
```
、
```
StartsWith
```
、
```
EndsWith
```
）
使用
```
minLength
```
设置触发过滤的最小输入长度
使用
```
allowSpaces
```
允许标记搜索中间包含空格
使用
```
suggestionCount
```
限制可见建议数量
使用
```
debounceDelay
```
调整远程源的防抖延迟

📄 Templates

📄 模板

Read: references/mention-templates.md

Customize suggestion list item layout with
```
itemTemplate
```
Customize the inserted text representation with
```
displayTemplate
```
Handle empty results with
```
noRecordsTemplate
```
Show a loading indicator while fetching remote data with
```
spinnerTemplate
```
Customize grouped items with
```
groupTemplate
```

阅读： references/mention-templates.md

使用
```
itemTemplate
```
自定义建议列表项布局
使用
```
displayTemplate
```
自定义插入文本的表示
使用
```
noRecordsTemplate
```
处理空结果
使用
```
spinnerTemplate
```
在获取远程数据时显示加载指示器
使用
```
groupTemplate
```
自定义分组项

📄 Customization

📄 自定义

Read: references/mention-customization.md

Show/hide the trigger character alongside selected text with
```
showMentionChar
```
Append a suffix (space, newline) after selection with
```
suffixText
```
Resize the popup with
```
popupHeight
```
and
```
popupWidth
```
Change the trigger character with
```
mentionChar
```
Control leading space requirement with
```
requireLeadingSpace
```
Apply custom CSS classes with
```
cssClass
```
Highlight searched characters with
```
highlight
```
Configure
```
ignoreCase
```
and
```
ignoreAccent
```
for search behavior

阅读： references/mention-customization.md

使用
```
showMentionChar
```
显示/隐藏选中文本旁的触发字符
使用
```
suffixText
```
在选择后追加后缀（空格、换行符）
使用
```
popupHeight
```
和
```
popupWidth
```
调整弹出框大小
使用
```
mentionChar
```
更改触发字符
使用
```
requireLeadingSpace
```
控制前置空格要求
使用
```
cssClass
```
应用自定义CSS类
使用
```
highlight
```
高亮搜索字符
配置
```
ignoreCase
```
和
```
ignoreAccent
```
控制搜索行为

📄 Sorting & Disabled Items

📄 排序与禁用项

Read: references/mention-sorting-and-disabled-items.md

Sort suggestions with
```
sortOrder
```
(
```
None
```
,
```
Ascending
```
,
```
Descending
```
)
Mark items as non-selectable via
```
fields.disabled
```
Dynamically disable items at runtime using the
```
disableItem
```
method

阅读： references/mention-sorting-and-disabled-items.md

使用
```
sortOrder
```
对建议排序（
```
None
```
、
```
Ascending
```
、
```
Descending
```
）
通过
```
fields.disabled
```
标记项为不可选择
使用
```
disableItem
```
方法在运行时动态禁用项

📄 Accessibility & Localization

📄 无障碍与本地化

Read: references/mention-accessibility-and-localization.md

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

ARIA attributes:

aria-selected

aria-activedescendent

aria-owns

Localize
```
noRecordsTemplate
```
with
```
L10n.load()
```
RTL support with
```
enableRtl
```

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

符合WCAG 2.2、Section 508和ADA标准
完整键盘快捷键（箭头Down/Up、Enter、Tab、Escape）

ARIA属性：

aria-selected

、

aria-activedescendent

、

aria-owns

使用
```
L10n.load()
```
本地化
```
noRecordsTemplate
```
使用
```
enableRtl
```
启用RTL支持

📄 API Reference

📄 API参考

Read: references/mention-api.md

Complete properties reference with types, defaults, and descriptions

All methods:

addItem

disableItem

getDataByValue

getItems

hidePopup

showPopup

search

destroy

All events:
```
dataBound
```
,
```
actionFailureTemplate
```

阅读： references/mention-api.md

完整的属性参考，包含类型、默认值和描述

所有方法：

addItem

、

disableItem

、

getDataByValue

、

getItems

、

hidePopup

、

showPopup

、

search

、

destroy

所有事件：
```
dataBound
```
、
```
actionFailureTemplate
```

Quick Start Example

快速入门示例

typescript

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

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MentionModule],
  template: `
    <label style="font-size: 15px; font-weight: 600;">Comments</label>
    <div id="mentionElement"
         placeholder="Type @ and tag a user"
         style="min-height: 100px; border: 1px solid #D7D7D7; border-radius: 4px; padding: 8px;">
    </div>
    <ejs-mention [dataSource]="userData" [target]="mentionTarget"></ejs-mention>
  `
})
export class AppComponent {
  public userData: string[] = ['Selma Rose', 'Garth', 'Robert', 'William', 'Joseph'];
  public mentionTarget: string = '#mentionElement';
}

Install the package:

⚠️ Security note: Pin the package to a specific version to prevent unintended upgrades to potentially compromised releases. Verify the installed version against your lockfile (
package-lock.json
/
yarn.lock
) after installation.

bash

ng add @syncfusion/ej2-angular-dropdowns@<version>

Add CSS (
styles.css
):

⚠️ Security note: These imports are resolved from
node_modules
at build time. Ensure the installed Syncfusion packages match your pinned versions in
package-lock.json
or
yarn.lock
before building. Do not source these files from a CDN without Subresource Integrity (SRI) hashes.

css

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

typescript

// app.component.ts (Angular 21 独立组件)
import { Component } from '@angular/core';
import { MentionModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MentionModule],
  template: `
    <label style="font-size: 15px; font-weight: 600;">评论</label>
    <div id="mentionElement"
         placeholder="输入@并标记用户"
         style="min-height: 100px; border: 1px solid #D7D7D7; border-radius: 4px; padding: 8px;">
    </div>
    <ejs-mention [dataSource]="userData" [target]="mentionTarget"></ejs-mention>
  `
})
export class AppComponent {
  public userData: string[] = ['Selma Rose', 'Garth', 'Robert', 'William', 'Joseph'];
  public mentionTarget: string = '#mentionElement';
}

安装包：

⚠️ 安全提示： 将包固定到特定版本，防止意外升级到可能存在风险的版本。安装后验证锁文件（
package-lock.json
/
yarn.lock
）中的已安装版本。

bash

ng add @syncfusion/ej2-angular-dropdowns@<version>

添加CSS（styles.css）：

⚠️ 安全提示： 这些导入在构建时从
node_modules
解析。构建前确保已安装的Syncfusion包与
package-lock.json
或
yarn.lock
中的固定版本匹配。请勿从CDN获取这些文件，除非带有子资源完整性（SRI）哈希。

css

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

Common Patterns

常见模式

Pattern 1: Object Data with Field Mapping

模式1：带字段映射的对象数据

typescript

public userData: { [key: string]: Object }[] = [
  { Name: 'Selma Rose', EmailId: 'selma@gmail.com' },
  { Name: 'Maria', EmailId: 'maria@gmail.com' },
  { Name: 'Robert', EmailId: 'robert@gmail.com' }
];
public fields: Object = { text: 'Name' };
public mentionTarget: string = '#mentionElement';

html

<ejs-mention [dataSource]="userData" [fields]="fields" [target]="mentionTarget"></ejs-mention>

typescript

public userData: { [key: string]: Object }[] = [
  { Name: 'Selma Rose', EmailId: 'selma@gmail.com' },
  { Name: 'Maria', EmailId: 'maria@gmail.com' },
  { Name: 'Robert', EmailId: 'robert@gmail.com' }
];
public fields: Object = { text: 'Name' };
public mentionTarget: string = '#mentionElement';

html

<ejs-mention [dataSource]="userData" [fields]="fields" [target]="mentionTarget"></ejs-mention>

Pattern 2: Custom Trigger Character with showMentionChar

模式2：带showMentionChar的自定义触发字符

html

<ejs-mention
  [dataSource]="userData"
  [target]="mentionTarget"
  [mentionChar]="'#'"
  [showMentionChar]="true">
</ejs-mention>

html

<ejs-mention
  [dataSource]="userData"
  [target]="mentionTarget"
  [mentionChar]="'#'"
  [showMentionChar]="true">
</ejs-mention>

Pattern 3: Remote Data with Popup Width

模式3：带弹出框宽度的远程数据

🔒 Security policy — remote data is a restricted pattern. Binding Mention to a remote endpoint requires a security review (see Security & Trust Boundary) before use in production. Remote data binding details and requirements are documented in references/mention-data-binding.md. No remote
DataManager
example is provided here by default.

🔒 安全策略 — 远程数据是受限模式。 将Mention绑定到远程端点需要经过安全审查（参见安全与信任边界）才能在生产环境中使用。远程数据绑定的详细信息和要求记录在references/mention-data-binding.md中。默认不提供远程
DataManager
示例。

Pattern 4: Allow Spaces in Mention Search

模式4：允许标记搜索中包含空格

html

<ejs-mention
  [dataSource]="userData"
  [fields]="fields"
  [allowSpaces]="true"
  [target]="mentionTarget">
</ejs-mention>

html

<ejs-mention
  [dataSource]="userData"
  [fields]="fields"
  [allowSpaces]="true"
  [target]="mentionTarget">
</ejs-mention>

Key Properties Quick Reference

关键属性速查

Property	Type	Default	Purpose
`target`	HTMLElement \| string	—	Target element where mention suggestions appear
`dataSource`	Array \| DataManager	`[]`	Source data for suggestions
`fields`	FieldSettingsModel	`{ text: null, value: null }`	Map data columns to component
`mentionChar`	string	`'@'`	Character that triggers the suggestion popup
`showMentionChar`	boolean	`false`	Show trigger character with inserted text
`suffixText`	string	`null`	Text appended after the selected item
`filterType`	FilterType	`'Contains'`	How suggestions are matched
`minLength`	number	`0`	Minimum chars to trigger filtering
`allowSpaces`	boolean	`false`	Allow spaces in mid-mention search
`suggestionCount`	number	`25`	Max number of suggestions shown
`debounceDelay`	number	`300`	Delay (ms) before filtering fires
`sortOrder`	SortOrder	`'None'`	Sort suggestions order
`popupHeight`	string \| number	`'300px'`	Popup list height
`popupWidth`	string \| number	`'auto'`	Popup list width
`highlight`	boolean	`false`	Highlight matched characters
`ignoreCase`	boolean	`true`	Case-insensitive search
`ignoreAccent`	boolean	—	Ignore diacritics in search
`requireLeadingSpace`	boolean	`true`	Require space before trigger character
`cssClass`	string	`null`	Custom CSS class(es) on the component
`locale`	string	`'en-US'`	Localization culture
`enableRtl`	boolean	`false`	Right-to-left rendering
`enablePersistence`	boolean	`false`	Persist state between reloads
`zIndex`	number	`1000`	Popup z-index

属性	类型	默认值	用途
`target`	HTMLElement \| string	—	显示标记建议的目标元素
`dataSource`	Array \| DataManager	`[]`	建议的数据源
`fields`	FieldSettingsModel	`{ text: null, value: null }`	将数据列映射到组件
`mentionChar`	string	`'@'`	触发建议弹出框的字符
`showMentionChar`	boolean	`false`	在插入文本中显示触发字符
`suffixText`	string	`null`	在选中项后追加的文本
`filterType`	FilterType	`'Contains'`	建议匹配方式
`minLength`	number	`0`	触发过滤的最小字符数
`allowSpaces`	boolean	`false`	允许标记搜索中间包含空格
`suggestionCount`	number	`25`	显示的最大建议数
`debounceDelay`	number	`300`	过滤触发前的延迟（毫秒）
`sortOrder`	SortOrder	`'None'`	建议排序顺序
`popupHeight`	string \| number	`'300px'`	弹出列表高度
`popupWidth`	string \| number	`'auto'`	弹出列表宽度
`highlight`	boolean	`false`	高亮匹配字符
`ignoreCase`	boolean	`true`	大小写不敏感搜索
`ignoreAccent`	boolean	—	搜索时忽略变音符号
`requireLeadingSpace`	boolean	`true`	要求触发字符前有空格
`cssClass`	string	`null`	组件上的自定义CSS类(es)
`locale`	string	`'en-US'`	本地化文化
`enableRtl`	boolean	`false`	从右到左渲染
`enablePersistence`	boolean	`false`	在重新加载之间保持状态
`zIndex`	number	`1000`	弹出框z-index

Workflow Decision Tree

工作流决策树

Need to implement Mention / @mention tagging?
│
├─ What's your data source?
│   ├─ Local strings/array  → See Data Binding: "Array of simple data"
│   ├─ Local objects        → See Data Binding: "Array of JSON data" + fields mapping
│   └─ Remote API           → See Data Binding: "Binding remote data"
│
├─ Custom trigger character (not @)?
│   └─ YES → [mentionChar]="'#'" (or any single char)
│
├─ Show trigger char in inserted text?
│   └─ YES → [showMentionChar]="true"
│
├─ Multi-word names (e.g., "John Doe")?
│   └─ YES → [allowSpaces]="true"
│
├─ Custom item layout in popup?
│   └─ YES → See Templates: itemTemplate / displayTemplate
│
├─ Need sorted suggestions?
│   └─ YES → See Sorting & Disabled Items: sortOrder
│
├─ Some items should not be selectable?
│   └─ YES → See Sorting & Disabled Items: fields.disabled / disableItem
│
├─ Filtering behavior?
│   ├─ By default (Contains)  → No extra config
│   ├─ StartsWith / EndsWith  → filterType="StartsWith"
│   └─ Minimum typed chars    → [minLength]="3"
│
└─ Need accessibility or localization?
    └─ YES → See Accessibility & Localization reference

需要实现Mention / @标记功能？
│
├─ 你的数据源是什么？
│   ├─ 本地字符串/数组  → 参见数据绑定："简单数据数组"
│   ├─ 本地对象        → 参见数据绑定："JSON数据数组" + 字段映射
│   └─ 远程API           → 参见数据绑定："绑定远程数据"
│
├─ 使用自定义触发字符（非@）？
│   └─ 是 → [mentionChar]="'#'"（或任何单个字符）
│
├─ 在插入文本中显示触发字符？
│   └─ 是 → [showMentionChar]="true"
│
├─ 多词名称（如"John Doe"）？
│   └─ 是 → [allowSpaces]="true"
│
├─ 弹出框中自定义项布局？
│   └─ 是 → 参见模板：itemTemplate / displayTemplate
│
├─ 需要排序建议？
│   └─ 是 → 参见排序与禁用项：sortOrder
│
├─ 某些项不应被选择？
│   └─ 是 → 参见排序与禁用项：fields.disabled / disableItem
│
├─ 过滤行为？
│   ├─ 默认（Contains）  → 无需额外配置
│   ├─ StartsWith / EndsWith  → filterType="StartsWith"
│   └─ 最小输入字符数    → [minLength]="3"
│
└─ 需要无障碍或本地化？
    └─ 是 → 参见无障碍与本地化参考文档

MultiSelect

A multi-value selection dropdown (

ejs-multiselect

) supporting four visual modes (Default/Box/Delimiter/CheckBox), rich filtering, templates, grouping, remote data, virtualization, and full Angular form integration.

支持四种视觉模式（默认/框/分隔符/复选框）的多值选择下拉框（

ejs-multiselect

），支持丰富过滤、模板、分组、远程数据、虚拟化以及完整的Angular表单集成。

Component Overview

组件概述

Mode	Behavior	Use When
`Default`	Selected items shown as chips in input	Standard multi-select
`Box`	Same as Default, explicit box display	Visual clarity needed
`Delimiter`	Selected items as comma-separated text	Space-constrained layouts
`CheckBox`	Popup shows checkboxes per item	Bulk selection workflows

模式	行为	适用场景
`Default`	选中项在输入框中显示为芯片	标准多选
`Box`	与默认模式相同，显式框显示	需要视觉清晰度时
`Delimiter`	选中项显示为逗号分隔文本	空间受限布局
`CheckBox`	弹出框中每个项显示复选框	批量选择工作流

Documentation Navigation Guide

文档导航指南

Getting Started

快速入门

📄 Read: references/multiselect-getting-started.md

Installation and package setup (
```
ng add
```
)
CSS imports and theme configuration
Basic
```
<ejs-multiselect>
```
in standalone Angular component
Popup height/width configuration
Angular version notes (standalone default in Angular 19+)

📄 阅读： references/multiselect-getting-started.md

安装和包设置（
```
ng add
```
）
CSS导入和主题配置
独立Angular组件中的基础
```
<ejs-multiselect>
```
弹出框高度/宽度配置
Angular版本说明（Angular 19+默认独立组件）

Data Binding & Value Binding

数据绑定与值绑定

📄 Read: references/multiselect-data-binding.md

Local arrays (strings, numbers, objects)
```
fields
```
mapping:
```
text
```
,
```
value
```
,
```
groupBy
```
,
```
iconCss
```
,
```
disabled
```
Remote data with DataManager (OData, Web API)
Pre-selecting values programmatically
Object binding with
```
allowObjectBinding
```

📄 阅读： references/multiselect-data-binding.md

本地数组（字符串、数字、对象）
```
fields
```
映射：
```
text
```
、
```
value
```
、
```
groupBy
```
、
```
iconCss
```
、
```
disabled
```
使用DataManager的远程数据（OData、Web API）
以编程方式预选择值
使用
```
allowObjectBinding
```
的对象绑定

Selection Modes, Chips & Item Control

选择模式、芯片与项控制

📄 Read: references/multiselect-selection-modes.md

```
mode
```
property: Default / Box / Delimiter / CheckBox

CheckBox mode:

CheckBoxSelection

showSelectAll

maximumSelectionLength

Chip customization via
```
tagging
```
event
Custom values with
```
allowCustomValue
```
Disabling specific items:
```
fields.disabled
```
,
```
disableItem()
```
```
addTagOnBlur
```
and
```
changeOnBlur
```
behaviors

📄 阅读： references/multiselect-selection-modes.md

```
mode
```
属性：Default / Box / Delimiter / CheckBox

复选框模式：

CheckBoxSelection

、

showSelectAll

、

maximumSelectionLength

通过
```
tagging
```
事件自定义芯片
使用
```
allowCustomValue
```
自定义值
禁用特定项：
```
fields.disabled
```
、
```
disableItem()
```
```
addTagOnBlur
```
和
```
changeOnBlur
```
行为

Filtering

过滤

📄 Read: references/multiselect-filtering.md

Enabling
```
allowFiltering
```
+
```
filtering
```
event +
```
updateData()
```
```
filterType
```
:
```
startsWith
```
,
```
contains
```
,
```
endsWith
```
Minimum character threshold before query fires
Remote filtering with DataManager
Case-insensitive matching

📄 阅读： references/multiselect-filtering.md

启用
```
allowFiltering
```
+
```
filtering
```
事件 +
```
updateData()
```
```
filterType
```
:
```
startsWith
```
、
```
contains
```
、
```
endsWith
```
查询触发前的最小字符阈值
使用DataManager的远程过滤
大小写不敏感匹配

Templates

模板

📄 Read: references/multiselect-templates.md

```
itemTemplate
```
— custom list item rendering with
```
ng-template
```
```
valueTemplate
```
— customize chip/selected value display
```
groupTemplate
```
— custom group header content
```
headerTemplate
```
/
```
footerTemplate
```
— popup top/bottom
```
noRecordsTemplate
```
/
```
actionFailureTemplate
```

📄 阅读： references/multiselect-templates.md

```
itemTemplate
```
— 使用
```
ng-template
```
自定义列表项渲染
```
valueTemplate
```
— 自定义芯片/选中值显示
```
groupTemplate
```
— 自定义分组页眉内容
```
headerTemplate
```
/
```
footerTemplate
```
— 弹出框顶部/底部
```
noRecordsTemplate
```
/
```
actionFailureTemplate
```

Grouping & Cascading

分组与级联

📄 Read: references/multiselect-grouping-and-items.md

```
fields.groupBy
```
— organize items into categories
Fixed vs inline group headers
```
enableGroupCheckBox
```
for group-level Select All
Cascading MultiSelect: parent
```
change
```
event → filter child data
Country → State → City cascade pattern

📄 阅读： references/multiselect-grouping-and-items.md

```
fields.groupBy
```
— 将项组织为类别
固定与内联分组页眉
```
enableGroupCheckBox
```
用于分组级全选
级联MultiSelect：父
```
change
```
事件 → 过滤子数据
国家 → 州 → 城市级联模式

Form Integration

表单集成

📄 Read: references/multiselect-form-support.md

Template-driven forms:
```
FormsModule
```
,
```
ngModel
```
, two-way binding
Reactive forms:
```
ReactiveFormsModule
```
,
```
FormGroup
```
,
```
FormControl
```
```
formControlName
```
usage and validation
Required field and custom validator patterns

📄 阅读： references/multiselect-form-support.md

模板驱动表单：
```
FormsModule
```
、
```
ngModel
```
、双向绑定
响应式表单：
```
ReactiveFormsModule
```
、
```
FormGroup
```
、
```
FormControl
```
```
formControlName
```
用法和验证
必填字段和自定义验证器模式

Advanced Features

高级功能

📄 Read: references/multiselect-advanced-features.md

Virtualization for large datasets (
```
enableVirtualization
```
)
Popup resize (
```
allowResize
```
, resize events)
Icons in list items (
```
iconCss
```
field)
Localization (
```
L10n.load()
```
, locale key overrides)
Accessibility: WAI-ARIA, keyboard navigation, WCAG 2.2
RTL support

📄 阅读： references/multiselect-advanced-features.md

大型数据集虚拟化（
```
enableVirtualization
```
）
弹出框调整大小（
```
allowResize
```
、调整大小事件）
列表项中的图标（
```
iconCss
```
字段）
本地化（
```
L10n.load()
```
、区域键覆盖）
无障碍：WAI-ARIA、键盘导航、WCAG 2.2
RTL支持

API Reference

API参考

📄 Read: references/multiselect-api.md

Complete list of all properties with types and defaults
All public methods with signatures, parameters, and return types
All events with argument types and usage examples
Module injection notes (
```
CheckBoxSelectionService
```
)

📄 阅读： references/multiselect-api.md

所有属性的完整列表，包含类型和默认值
所有公共方法的签名、参数和返回类型
所有事件的参数类型和用法示例
模块注入说明（
```
CheckBoxSelectionService
```
）

Quick Start

快速入门

⚠️ Security note: Pin the package to a specific version to prevent unintended upgrades to potentially compromised releases. Verify the installed version against your lockfile (
package-lock.json
/
yarn.lock
) after installation.

bash

ng add @syncfusion/ej2-angular-dropdowns@<version>

typescript

// app.component.ts — Standalone Angular 19+
import { Component } from '@angular/core';
import { MultiSelectModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [MultiSelectModule],
  selector: 'app-root',
  template: `
    <ejs-multiselect
      [dataSource]="skills"
      [fields]="fields"
      placeholder="Select skills"
      [(value)]="selectedSkills"
      (change)="onChange($event)">
    </ejs-multiselect>
  `
})
export class AppComponent {
  public skills = [
    { id: 1, name: 'Angular' },
    { id: 2, name: 'React' },
    { id: 3, name: 'TypeScript' },
    { id: 4, name: 'Node.js' },
  ];
  public fields = { text: 'name', value: 'id' };
  public selectedSkills: number[] = [1, 3]; // pre-select Angular & TypeScript

  onChange(args: any): void {
    this.selectedSkills = args.value;
  }
}

⚠️ Security note: These imports are resolved from
node_modules
at build time. Ensure the installed Syncfusion packages match your pinned versions in
package-lock.json
or
yarn.lock
before building. Do not source these files from a CDN without Subresource Integrity (SRI) hashes.

css

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

⚠️ 安全提示： 将包固定到特定版本，防止意外升级到可能存在风险的版本。安装后验证锁文件（
package-lock.json
/
yarn.lock
）中的已安装版本。

bash

ng add @syncfusion/ej2-angular-dropdowns@<version>

typescript

// app.component.ts — Angular 19+独立组件
import { Component } from '@angular/core';
import { MultiSelectModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [MultiSelectModule],
  selector: 'app-root',
  template: `
    <ejs-multiselect
      [dataSource]="skills"
      [fields]="fields"
      placeholder="选择技能"
      [(value)]="selectedSkills"
      (change)="onChange($event)">
    </ejs-multiselect>
  `
})
export class AppComponent {
  public skills = [
    { id: 1, name: 'Angular' },
    { id: 2, name: 'React' },
    { id: 3, name: 'TypeScript' },
    { id: 4, name: 'Node.js' },
  ];
  public fields = { text: 'name', value: 'id' };
  public selectedSkills: number[] = [1, 3]; // 预选择Angular & TypeScript

  onChange(args: any): void {
    this.selectedSkills = args.value;
  }
}

⚠️ 安全提示： 这些导入在构建时从
node_modules
解析。构建前确保已安装的Syncfusion包与
package-lock.json
或
yarn.lock
中的固定版本匹配。请勿从CDN获取这些文件，除非带有子资源完整性（SRI）哈希。

css

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

Common Patterns

常见模式

Checkbox Mode with Select All

带全选的复选框模式

typescript

import { MultiSelectModule, CheckBoxSelectionService } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [MultiSelectModule],
  providers: [CheckBoxSelectionService],
  template: `
    <ejs-multiselect
      [dataSource]="items"
      mode="CheckBox"
      [showSelectAll]="true"
      selectAllText="Select All"
      unSelectAllText="Unselect All"
      [maximumSelectionLength]="5">
    </ejs-multiselect>
  `
})

typescript

import { MultiSelectModule, CheckBoxSelectionService } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [MultiSelectModule],
  providers: [CheckBoxSelectionService],
  template: `
    <ejs-multiselect
      [dataSource]="items"
      mode="CheckBox"
      [showSelectAll]="true"
      selectAllText="全选"
      unSelectAllText="取消全选"
      [maximumSelectionLength]="5">
    </ejs-multiselect>
  `
})

Filtering with Remote Data

带远程数据的过滤

🔒 Security policy — remote data is a restricted pattern. Binding MultiSelect to a remote endpoint requires a security review (see Security & Trust Boundary) before use in production. Remote filtering details and requirements are documented in references/multiselect-filtering.md. No remote
DataManager
example is provided here by default.

🔒 安全策略 — 远程数据是受限模式。 将MultiSelect绑定到远程端点需要经过安全审查（参见安全与信任边界）才能在生产环境中使用。远程过滤的详细信息和要求记录在references/multiselect-filtering.md中。默认不提供远程
DataManager
示例。

Reactive Form Integration

响应式表单集成

typescript

import { ReactiveFormsModule, FormControl } from '@angular/forms';

// In component:
public skillsControl = new FormControl([1, 3]); // pre-selected IDs

// In template:
// <ejs-multiselect [formControl]="skillsControl" [dataSource]="skills" [fields]="fields">
// </ejs-multiselect>

typescript

import { ReactiveFormsModule, FormControl } from '@angular/forms';

// 在组件中：
public skillsControl = new FormControl([1, 3]); // 预选中ID

// 在模板中：
// <ejs-multiselect [formControl]="skillsControl" [dataSource]="skills" [fields]="fields">
// </ejs-multiselect>

Key Props

关键属性

Property	Type	Purpose
`dataSource`	`any[] \| DataManager`	Items to display
`fields`	`FieldSettingsModel`	Maps `text` , `value` , `groupBy` , `disabled` , `iconCss`
`value`	`any[]`	Currently selected values (use `[(value)]` for two-way)
`mode`	`string`	`Default` , `Box` , `Delimiter` , `CheckBox`
`allowFiltering`	`boolean`	Enables search within the dropdown
`filterType`	`string`	`startsWith` , `contains` , `endsWith`
`showSelectAll`	`boolean`	Shows Select All in CheckBox mode
`maximumSelectionLength`	`number`	Caps the number of selectable items
`allowCustomValue`	`boolean`	Lets users add values not in the list
`enableVirtualization`	`boolean`	Optimizes rendering for large lists
`popupHeight` / `popupWidth`	`string`	Constrains popup dimensions
`allowResize`	`boolean`	Lets users drag-resize the popup
`placeholder`	`string`	Input hint text

属性	类型	用途
`dataSource`	`any[] \| DataManager`	要显示的项
`fields`	`FieldSettingsModel`	映射 `text` 、 `value` 、 `groupBy` 、 `disabled` 、 `iconCss`
`value`	`any[]`	当前选中值（使用 `[(value)]` 进行双向绑定）
`mode`	`string`	`Default` 、 `Box` 、 `Delimiter` 、 `CheckBox`
`allowFiltering`	`boolean`	在下拉框中启用搜索
`filterType`	`string`	`startsWith` 、 `contains` 、 `endsWith`
`showSelectAll`	`boolean`	在复选框模式中显示全选
`maximumSelectionLength`	`number`	限制可选择的项数
`allowCustomValue`	`boolean`	允许用户添加列表中不存在的值
`enableVirtualization`	`boolean`	优化大型列表的渲染
`popupHeight` / `popupWidth`	`string`	限制弹出框尺寸
`allowResize`	`boolean`	允许用户拖动调整弹出框大小
`placeholder`	`string`	输入提示文本

MultiColumn ComboBox

The MultiColumn ComboBox (

ejs-multicolumncombobox

) is a dropdown component that displays data in a multi-column grid-like popup. It supports column configuration, data binding (local/remote), filtering, sorting, grouping, templates, virtualization, events, and accessibility.

MultiColumn ComboBox（

ejs-multicolumncombobox

）是一个下拉组件，在弹出框中以多列网格形式显示数据。它支持列配置、数据绑定（本地/远程）、过滤、排序、分组、模板、虚拟化、事件和无障碍功能。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup (
```
ng add @syncfusion/ej2-angular-multicolumn-combobox@<version>
```
)
⚠️ Security note: Pin the package to a specific version to prevent unintended upgrades to potentially compromised releases. Verify the installed version against your lockfile (
```
package-lock.json
```
/
```
yarn.lock
```
) after installation.
CSS/theme imports for Material and other themes
Basic standalone component usage with
```
<ejs-multicolumncombobox>
```
Binding
```
dataSource
```
and
```
fields
```
properties
Configuring
```
<e-columns>
```
and
```
<e-column>
```
child elements
Popup height and width configuration (
```
popupHeight
```
,
```
popupWidth
```
)

📄 阅读： references/getting-started.md

安装和包设置（
```
ng add @syncfusion/ej2-angular-multicolumn-combobox@<version>
```
）
⚠️ 安全提示： 将包固定到特定版本，防止意外升级到可能存在风险的版本。安装后验证锁文件（
```
package-lock.json
```
/
```
yarn.lock
```
）中的已安装版本。
Material和其他主题的CSS/主题导入
使用
```
<ejs-multicolumncombobox>
```
的基础独立组件用法
绑定
```
dataSource
```
和
```
fields
```
属性
配置
```
<e-columns>
```
和
```
<e-column>
```
子元素
弹出框高度和宽度配置（
```
popupHeight
```
、
```
popupWidth
```
）

Columns Configuration

列配置

📄 Read: references/columns.md

Defining columns with
```
field
```
,
```
header
```
,
```
width
```
Setting text alignment with
```
textAlign
```
Using column
```
template
```
with
```
ng-template
```
Displaying boolean values as checkboxes with
```
displayAsCheckBox
```
Applying custom CSS attributes via
```
customAttributes
```
Custom column headers with
```
headerTemplate
```
Formatting values with
```
format
```

📄 阅读： references/columns.md

使用
```
field
```
、
```
header
```
、
```
width
```
定义列
使用
```
textAlign
```
设置文本对齐
使用
```
ng-template
```
的列
```
template
```
使用
```
displayAsCheckBox
```
将布尔值显示为复选框
通过
```
customAttributes
```
应用自定义CSS属性
使用
```
headerTemplate
```
自定义列页眉
使用
```
format
```
格式化值

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding local object arrays via
```
dataSource
```
Remote data binding (restricted — requires security review; see Security & Trust Boundary)
Mapping
```
fields
```
:
```
text
```
,
```
value
```
, and
```
groupBy
```
Using the
```
query
```
property to filter/limit remote results

📄 阅读： references/data-binding.md

通过
```
dataSource
```
绑定本地对象数组
远程数据绑定（受限 — 需要安全审查；参见安全与信任边界）
映射
```
fields
```
:
```
text
```
、
```
value
```
和
```
groupBy
```
使用
```
query
```
属性过滤/限制远程结果

Items and Display Configuration

项与显示配置

📄 Read: references/items.md

Setting pre-selected text with
```
text
```
property
Setting pre-selected value with
```
value
```
property
Setting selected item by index with
```
index
```
property
Placeholder text with
```
placeholder
```
Float label behavior with
```
floatLabelType
```
(Never/Always/Auto)
Adding HTML attributes via
```
htmlAttributes
```
Setting component width with
```
width
```
Configuring popup dimensions (
```
popupWidth
```
,
```
popupHeight
```
)
Show/hide clear button with
```
showClearButton
```
Applying custom CSS class with
```
cssClass
```
Disabled state with
```
disabled
```
Read-only mode with
```
readonly
```

Configuring grid settings (

gridSettings

gridLines

rowHeight

enableAltRow

)

📄 阅读： references/items.md

使用
```
text
```
属性设置预选中文本
使用
```
value
```
属性设置预选中值
使用
```
index
```
属性按索引设置选中项
使用
```
placeholder
```
设置占位符文本
使用
```
floatLabelType
```
设置浮动标签行为（Never/Always/Auto）
通过
```
htmlAttributes
```
添加HTML属性
使用
```
width
```
设置组件宽度
配置弹出框尺寸（
```
popupWidth
```
、
```
popupHeight
```
）
使用
```
showClearButton
```
显示/隐藏清除按钮
使用
```
cssClass
```
应用自定义CSS类
使用
```
disabled
```
设置禁用状态
使用
```
readonly
```
设置只读模式

配置网格设置（

gridSettings

gridLines

、

rowHeight

、

enableAltRow

）

Filtering

过滤

📄 Read: references/filtering.md

Enable/disable filtering with
```
allowFiltering
```
Changing filter type with
```
filterType
```
(StartsWith/EndsWith/Contains)

📄 阅读： references/filtering.md

使用
```
allowFiltering
```
启用/禁用过滤
使用
```
filterType
```
更改过滤类型（StartsWith/EndsWith/Contains）

Sorting

排序

📄 Read: references/sorting.md

Enable/disable sorting with
```
allowSorting
```
Setting initial sort order with
```
sortOrder
```
(None/Ascending/Descending)
Sorting single vs. multiple columns with
```
sortType
```

📄 阅读： references/sorting.md

使用
```
allowSorting
```
启用/禁用排序
使用
```
sortOrder
```
设置初始排序顺序（None/Ascending/Descending）
使用
```
sortType
```
对单列或多列排序

Grouping

分组

📄 Read: references/grouping.md

Grouping items using the
```
groupBy
```
field in
```
fields
```
property

📄 阅读： references/grouping.md

使用
```
fields
```
属性中的
```
groupBy
```
字段分组项

Templates

模板

📄 Read: references/templates.md

Customizing row items with
```
itemTemplate
```
Custom column headers with
```
headerTemplate
```
Group headers with
```
groupTemplate
```
Footer content with
```
footerTemplate
```
No-records placeholder with
```
noRecordsTemplate
```
Remote failure display with
```
actionFailureTemplate
```

📄 阅读： references/templates.md

使用
```
itemTemplate
```
自定义行项
使用
```
headerTemplate
```
自定义列页眉
使用
```
groupTemplate
```
自定义分组页眉
使用
```
footerTemplate
```
自定义页脚内容
使用
```
noRecordsTemplate
```
自定义无数据占位符
使用
```
actionFailureTemplate
```
自定义远程失败显示

Events

事件

📄 Read: references/events.md

```
actionBegin
```
,
```
actionComplete
```
,
```
actionFailure
```
— data lifecycle events
```
select
```
— item selection event
```
change
```
— value change event
```
filtering
```
— text input filtering event
```
open
```
/
```
close
```
— popup state events
```
created
```
— component rendered event

📄 阅读： references/events.md

```
actionBegin
```
、
```
actionComplete
```
、
```
actionFailure
```
— 数据生命周期事件
```
select
```
— 项选择事件
```
change
```
— 值更改事件
```
filtering
```
— 文本输入过滤事件
```
open
```
/
```
close
```
— 弹出框状态事件
```
created
```
— 组件渲染事件

Virtualization

虚拟化

📄 Read: references/virtualization.md

Enabling virtual scrolling with
```
enableVirtualization
```
Virtual scrolling with local and remote large datasets

📄 阅读： references/virtualization.md

使用
```
enableVirtualization
```
启用虚拟滚动
本地和远程大型数据集的虚拟滚动

Accessibility and Localization

无障碍与本地化

📄 Read: references/accessibility.md

WCAG 2.2, Section 508 compliance
WAI-ARIA attributes used by the component
Keyboard navigation shortcuts
RTL support with
```
enableRtl
```
Localization of
```
noRecordsTemplate
```
text using
```
L10n
```

📄 阅读： references/accessibility.md

符合WCAG 2.2、Section 508标准
组件使用的WAI-ARIA属性
键盘导航快捷键
使用
```
enableRtl
```
启用RTL支持
使用
```
L10n
```
本地化
```
noRecordsTemplate
```
文本

API Reference

API参考

📄 Read: references/api.md

Complete list of properties, methods, and events
```
ColumnModel
```
interface properties
```
GridSettingsModel
```
interface

Methods:

showPopup

hidePopup

focusIn

focusOut

getDataByValue

getItems

addItems

📄 阅读： references/api.md

属性、方法和事件的完整列表
```
ColumnModel
```
接口属性
```
GridSettingsModel
```
接口

方法：

showPopup

、

hidePopup

、

focusIn

、

focusOut

、

getDataByValue

、

getItems

、

addItems

Quick Start

快速入门

typescript

import { Component } from '@angular/core';
import { MultiColumnComboBoxModule } from '@syncfusion/ej2-angular-multicolumn-combobox';

@Component({
  imports: [MultiColumnComboBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-multicolumncombobox
      id='multicolumn'
      [dataSource]='empData'
      [fields]='fields'
      [placeholder]='waterMark'>
      <e-columns>
        <e-column field='EmpID' header='Employee ID' width='100'></e-column>
        <e-column field='Name' header='Name' width='90'></e-column>
        <e-column field='Designation' header='Designation' width='100'></e-column>
        <e-column field='Country' header='Country' width='90'></e-column>
      </e-columns>
    </ejs-multicolumncombobox>`
})
export class AppComponent {
  public empData: Object[] = [
    { EmpID: 1001, Name: 'Andrew Fuller', Designation: 'Team Lead', Country: 'England' },
    { EmpID: 1002, Name: 'Robert', Designation: 'Developer', Country: 'USA' },
    { EmpID: 1003, Name: 'Michael', Designation: 'HR', Country: 'Russia' }
  ];
  public fields: Object = { text: 'Name', value: 'EmpID' };
  public waterMark: string = 'Select an employee';
}

typescript

import { Component } from '@angular/core';
import { MultiColumnComboBoxModule } from '@syncfusion/ej2-angular-multicolumn-combobox';

@Component({
  imports: [MultiColumnComboBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-multicolumncombobox
      id='multicolumn'
      [dataSource]='empData'
      [fields]='fields'
      [placeholder]='waterMark'>
      <e-columns>
        <e-column field='EmpID' header='员工ID' width='100'></e-column>
        <e-column field='Name' header='姓名' width='90'></e-column>
        <e-column field='Designation' header='职位' width='100'></e-column>
        <e-column field='Country' header='国家' width='90'></e-column>
      </e-columns>
    </ejs-multicolumncombobox>`
})
export class AppComponent {
  public empData: Object[] = [
    { EmpID: 1001, Name: 'Andrew Fuller', Designation: '团队主管', Country: '英国' },
    { EmpID: 1002, Name: 'Robert', Designation: '开发人员', Country: '美国' },
    { EmpID: 1003, Name: 'Michael', Designation: 'HR', Country: '俄罗斯' }
  ];
  public fields: Object = { text: 'Name', value: 'EmpID' };
  public waterMark: string = '选择员工';
}

Common Patterns

常见模式

Remote data with DataManager

带DataManager的远程数据

When data comes from an API, use

DataManager

→ Read

references/data-binding.md

数据来自API时，使用

DataManager

→ 阅读

references/data-binding.md

Large datasets (150+ rows)

大型数据集（150+行）

Enable

enableVirtualization

to avoid performance issues → Read

references/virtualization.md

启用

enableVirtualization

避免性能问题 → 阅读

references/virtualization.md

Rich row display

富行显示

Use column

template

with

ng-template

for images, badges, or custom HTML → Read

references/columns.md

使用列

template

和

ng-template

显示图片、徽章或自定义HTML → 阅读

references/columns.md

Grouped dropdown

分组下拉框

Set

groupBy

fields

to categorize items → Read

references/grouping.md

在

fields

中设置

groupBy

对项分类 → 阅读

references/grouping.md

Programmatic open/close

以编程方式打开/关闭

Use

showPopup()

hidePopup()

methods → Read

references/api.md

使用

showPopup()

hidePopup()

方法 → 阅读

references/api.md