syncfusion-angular-dropdowns

实现 Syncfusion Angular 下拉框

安全与信任边界

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

本技能中的所有下拉框组件默认使用本地内存数据源。 将组件绑定到远程 HTTP 端点（通过 DataManager 或任何 Observable/HTTP 数据源）属于非默认、高风险操作，生产代码中使用前必须经过明确的安全审查。

⛔ 除非使用方应用已通过安全审查并确认以下各项，否则不要生成或建议远程 DataManager / HTTP 数据源配置：

1. 目标端点由与应用相同的团队所有并运营。
2. 端点会执行身份验证、授权和输入验证。
3. 所有响应在绑定到组件 dataSource 之前都会经过净化。
4. 已设置覆盖该来源的内容安全策略（CSP）。

强制安全要求

#	要求
1	默认使用本地数据。 除非已明确批准远程数据源，否则 dataSource 应使用普通 TypeScript 数组。
2	不得使用公共或第三方 URL。 切勿配置从应用自身来源之外的端点获取数据的数据源。
3	绑定前净化所有外部数据。 任何源自应用外部的值（API 响应、本地存储读取值）都必须先移除 HTML/脚本内容，再赋值给 dataSource 或 value。
4	净化用户筛选输入。 将输入的文本转发到任何服务器查询之前，移除非字母数字字符以防止注入。
5	默认不得设置 crossDomain: true。 必须对 DataManager 中放宽 CORS 的做法进行明确说明并审核。
6	固定软件包版本。 每个 @syncfusion/ej2-* 依赖都必须在 package.json 中锁定为精确版本；每次安装后都要与锁文件核对。
7	未经 SRI 验证，不得加载 CDN 资源。 CSS/JS 必须在构建时从 node_modules 解析，不得在运行时从 CDN 获取，除非带有子资源完整性哈希。
8	不得在本地存储中存放敏感数据。 enablePersistence 绝不能存储令牌、凭据或个人身份信息（PII）；使用读取回来的任何值前都必须先净化。

---

AutoComplete

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

组件概述与架构

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

1. 输入时建议 — 根据用户输入，从数据源显示匹配项
2. 自由输入 — 用户可以输入任意值，不受列表限制
3. 搜索/筛选 — 支持多种筛选策略（StartsWith、Contains、EndsWith）
4. 自动填充 — 自动在输入框中补全第一个匹配的建议
5. 分组建议 — 按 groupBy 字段对项目分类
6. 虚拟滚动 — 高效处理数千个项目
7. 模板自定义 — 支持项目、分组、页眉、页脚和空状态模板

主要特性

方面	详情
选择	单选；用户也可以输入任意自由文本值
数据源	本地数组、远程 DataManager、OData、Web API、Observable（async pipe）
筛选	内置筛选：StartsWith、EndsWith、Contains
自动填充	用户输入时在行内补全第一个匹配项
性能	使用虚拟滚动处理大型数据集（1,000 个以上项目）
表单	支持模板驱动（ngModel）和响应式（FormControl）表单集成
无障碍访问	符合 WCAG 2.2 标准，支持完整的键盘导航和 ARIA 属性
自定义	项目、分组、页眉、页脚、noRecords、actionFailure 模板；CSS 主题

---

文档导航指南

📄 快速入门

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

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

📄 数据绑定

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

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

📄 筛选与搜索

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

• 配置 filterType（StartsWith、Contains、EndsWith）
• 使用 suggestionCount 限制建议数量
• 使用 minLength 设置最少字符数阈值
• 使用 ignoreCase 启用不区分大小写的筛选
• 使用 ignoreAccent 启用不区分变音符号／重音符号的筛选
• 使用 debounceDelay 设置防抖延迟，优化远程筛选
• 通过 filtering 事件和 updateData 自定义筛选

📄 分组与模板

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

• 使用 fields.groupBy 按类别对建议进行分组
• 使用项目模板自定义渲染
• 使用分组标题模板（内联和固定）
• 为弹出窗口设置页眉和页脚模板
• 使用 noRecordsTemplate 设置空状态
• 为远程数据错误设置操作失败模板

📄 功能配置

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

• 自动填充：使用 autofill 属性以内联方式补全建议
• 使用 highlight 属性突出显示匹配的字符
• 使用 fields.disabled 或 disableItem 方法禁用单个项目
• 使用 enabled 属性禁用整个组件
• 使用 allowResize 使弹出窗口可调整大小
• 使用 enableVirtualization 为大型数据集启用虚拟滚动
• 使用 showPopupButton 显示／隐藏弹出窗口按钮
• 使用 showClearButton 显示／隐藏清除按钮
• 使用 enableRtl 启用 RTL 支持
• 使用 sortOrder 设置排序顺序

📄 表单支持与验证

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

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

📄 无障碍访问与本地化

阅读： 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 语言

📄 高级模式与操作指南

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

• 使用 autofill 属性实现自动填充功能
• 使用 highlight 属性突出显示搜索字符
• 使用 Predicate 进行多字段自定义筛选（同时按名称和代码筛选）
• 通过 fields.iconCss 支持图标
• 聚焦时显示来自浏览器本地存储的建议列表

  ⚠️ 安全提示： 同一来源下运行的任何 JavaScript 都可以访问本地存储， 因此它是常见的 XSS 攻击面。切勿在本地存储中存储敏感数据（令牌、个人身份信息）。 将从本地存储读取的任何值绑定到组件的 dataSource 或 value 之前，请先进行清理。

• 自定义搜索和高亮样式

📄 API 参考

阅读： references/autocomplete-api.md

• 完整的属性参考，包含类型、默认值和说明
• 所有方法及其签名和用法
• 所有事件及其负载类型和处理程序示例

---

快速入门示例

// 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 = '';
}

安装软件包：

⚠️ 安全提示： 将软件包固定到特定版本，以防意外升级到可能已遭入侵的版本。 安装后，请根据锁文件（package-lock.json / yarn.lock）验证已安装的版本。

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

添加 CSS（styles.css）：

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

@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';

---

常见模式

模式 1：使用复杂对象数据进行筛选

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

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

适用场景： 当数据是对象数组，且需要将其中一个字段显示为建议文本时。

---

模式 2：自动填充 + 高亮

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

适用场景： 用户希望获得行内补全，并通过视觉效果突出显示匹配文本的搜索栏。

---

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

🔒 安全策略 — 远程数据属于受限模式。 将 AutoComplete 绑定到远程端点前，必须先进行安全审查（参见上文 安全与信任边界），之后才能在生产环境中使用。 远程数据绑定的详细信息和要求见 references/autocomplete-data-binding.md。 此处默认不提供远程 DataManager 示例。

适用场景： 由 API 支持的自动补全，希望降低请求频率时——仅当端点和数据管道已按照上述安全要求完成审查后使用。

---

模式 4：大型数据集的虚拟滚动

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

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

适用场景： 包含 1,000 项以上的数据集，因为一次性渲染所有 DOM 元素的成本较高。

---

关键属性速查

属性	类型	默认值	用途
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	触发筛选前的延迟（ms）
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	启用从右向左的渲染

---

工作流决策树

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

ComboBox

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

组件概览与架构

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

1. 从列表中选择预定义选项
2. 在启用 allowCustom 时输入自定义值
3. 在输入时搜索/筛选项目
4. 按类别对项目分组
5. 使用项目、分组、页眉和页脚模板自定义显示内容

主要特征

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

---

文档导航指南

📄 入门

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

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

📄 数据绑定与数据源

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

• 绑定到本地数组（字符串、数字、对象）
• 为复杂数据映射文本和值字段
• 从 Web API、OData 服务获取远程数据
• 为不同的数据适配器配置 DataManager
• 使用 RxJS Observable 的异步管道
• 处理动态数据更新

📄 筛选与搜索

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

• 使用 allowFiltering 属性启用筛选
• 配置筛选类型（StartsWith、Contains、EndsWith 等）
• 区分大小写筛选，以进行严格匹配
• 忽略变音符号的筛选，以支持不区分重音符号的搜索
• 设置防抖延迟，以优化远程请求
• 设置筛选所需的最少字符数
• 使用远程查询进行自定义筛选

📄 分组与模板

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

• 使用 groupBy 字段按类别对项进行分组
• 使用项模板自定义项的呈现方式
• 使用组标题模板（内联和固定）
• 使用页脚模板展示补充信息
• 有效地组合多个模板
• 优化模板性能

📄 高级功能配置

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

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

📄 表单支持与验证

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

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

📄 无障碍支持与本地化

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

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

📄 高级模式与操作指南

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

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

📄 API 参考

阅读： references/combobox-api.md

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

---

快速入门示例

最简设置（5 分钟）

// 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' }
  ];
}

具体说明：

1. 从 @syncfusion/ej2-angular-dropdowns 导入 ComboBoxComponent
2. 定义包含对象（id、text）的数据数组
3. 使用 fields 映射文本字段和值字段
4. 使用 [(ngModel)] 绑定所选值
5. 为空状态设置占位符

---

常见模式与工作流

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

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

适用场景： 技能、标签、电子邮件域（用户输入“j”时显示“JavaScript”）

参见：高级模式

---

模式 2：级联依赖下拉列表

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

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

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

参见：高级模式

---

模式 3：带图标的分组项

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

适用场景： 可视化分类（带图标的语言、文件类型）

参见：高级模式

---

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

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

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

参见：高级模式

---

关键属性与配置

基本属性

属性	类型	默认值	使用场景
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	双向值绑定

高级属性

属性	类型	使用场景
itemTemplate	string | TemplateRef	自定义项目渲染
groupTemplate	string | TemplateRef	自定义分组标题显示
footerTemplate	string | TemplateRef	在列表下方添加信息
enableVirtualization	boolean	10,000 个以上项目（性能优化）
groupBy	string	按类别整理项目
filterType	string	StartsWith | Contains | EndsWith
debounceDelay	number	远程数据请求延迟

---

组件生命周期

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

需要处理的关键事件：

• change：所选值发生变化时
• filtering：用户输入时（筛选查询）
• select：选中项目时
• focus：组件获得焦点时
• blur：组件失去焦点时

---

工作流决策树

需要实现 ComboBox？请遵循此决策树：

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

---

后续步骤

1. 从这里开始： 入门指南 - 设置你的第一个 ComboBox
2. 绑定数据： 数据绑定与来源 - 连接到你的数据
3. 添加搜索： 筛选与搜索 - 启用用户筛选
4. 自定义： 分组与模板 - 设置样式并整理显示内容
5. 高级： 高级模式与操作指南 - 自动填充、级联、图标、调整大小
6. 功能： 功能配置 - 启用高级功能
7. 集成： 表单支持 - 连接到表单
8. 完善： 无障碍功能 - 确保符合规范
9. 参考： API 参考 - 完整的属性、方法和事件参考

---

其他资源

• Syncfusion Angular ComboBox API 参考
• Angular 版本支持
• DataManager 文档
• 组件主题与样式

DropDownList

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

文档导航指南

入门指南

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

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

数据绑定

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

• 绑定基本类型数组（字符串、数字）
• 使用 [fields] 映射绑定对象数组
• 绑定嵌套对象或复杂对象
• 通过 DataManager 绑定远程数据（OData、Web API）
• 使用 Async Pipe 处理 Observable 数据流
• 值绑定（基本类型和对象类型，搭配 allowObjectBinding）

筛选

📄 阅读： references/dropdownlist-filtering.md

• 使用 [allowFiltering] 启用搜索
• 使用 filtering 事件和 updateData() 方法
• 开始筛选前所需的最少字符数
• 筛选类型：contains、startsWith、endsWith
• 区分大小写的筛选
• 忽略变音符号／重音符号的筛选
• 用于性能优化的防抖延迟

模板

📄 阅读： references/dropdownlist-templates.md

• 项目模板：自定义每个列表项
• 值模板：自定义选中值的显示
• 分组模板：自定义分组标题的外观
• 页眉模板：弹出窗口顶部的静态元素
• 页脚模板：弹出窗口底部的静态元素
• 无记录模板：空状态显示
• 操作失败模板：错误状态显示

分组与虚拟化

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

• 使用 groupBy 字段对项目进行分组
• 内联和固定浮动分组标题
• 使用 [enableVirtualization] 对大型列表启用虚拟滚动
• 对远程数据启用虚拟滚动
• 结合使用筛选和虚拟化
• 自定义虚拟模式下的项目数量

禁用项与表单

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

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

自定义与样式

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

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

操作指南

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

• 动态添加／移除／清除项目
• 以编程方式关闭弹出窗口
• 级联 DropDownLists
• 自定义分组标题模板
• 高亮筛选出的字符
• 增量搜索行为
• 修改远程数据结果
• 显示远程数据项目数量
• 为列表项添加工具提示
• 处理值更改事件
• 在列表项中支持图标

API 参考

📄 阅读： references/dropdownlist-api.md

• 完整的属性参考，包含类型、默认值和用法示例
• 所有方法及其签名、参数和返回类型
• 所有事件及其参数接口和用法示例
• 接口详情：FieldSettingsModel、ChangeEventArgs、SelectEventArgs、PopupEventArgs、FilteringEventArgs
• 属性、方法和事件的快速参考汇总表

快速入门示例

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

常见模式

可搜索下拉列表

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

远程数据下拉列表

🔒 安全策略 — 远程数据属于受限模式。 将 DropDownList 绑定到远程端点前，必须先进行安全审查（参见 安全与信任边界），之后才能在生产环境中使用。 远程数据绑定的详情和要求记录在 references/dropdownlist-data-binding.md 中。 此处默认不提供远程 DataManager 示例。

响应式表单集成

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>

关键属性

属性	类型	描述
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	空状态提示

常见用例

带验证的表单字段 → 参见 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

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

组件概览

Syncfusion ListBox 是一款高性能的下拉列表替代组件，具备以下高级功能：

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

文档导航指南

入门

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

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

选择模式和交互

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

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

数据绑定和字段映射

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

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

拖放功能

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

• 单个 ListBox 的拖放排序
• 双 ListBox 的拖放传输
• 拖放事件（dragStart、drag、drop）
• 配置多个列表的 scope
• 事件处理和项目操作
• 双 ListBox 的实际应用模式

自定义和样式

📄 阅读： references/listbox-customization.md

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

实用实现示例

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

• 筛选 ListBox 项目
• 使用所选项目提交表单
• 根据条件启用/禁用项目
• 为大型数据集启用滚动条
• 实际应用场景
• 常见问题排查场景

操作指南和常见任务

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

• 以编程方式添加项目
• 以编程方式选择项目
• 动态启用或禁用项目
• 为大型数据集启用滚动条
• 使用输入框筛选 ListBox 数据
• 在表单中提交所选项目

API 参考

📄 阅读： references/listbox-api.md

• 所有组件属性及其类型、默认值和示例
• 所有公共方法及其参数签名和用法示例
• 所有事件及其事件参数接口和处理程序模式
• 接口定义：FieldSettingsModel、SelectionSettingsModel、ToolbarSettingsModel
• 事件参数接口：ListBoxChangeEventArgs、DragEventArgs、DropEventArgs、BeforeItemRenderEventArgs、FilteringEventArgs、SourceDestinationModel
• 枚举定义：SelectionMode、SortOrder、FilterType、ToolBarPosition、CheckBoxPosition

快速入门示例

使用本地数据的基本 ListBox

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' }
    ];
  }
}

添加样式

⚠️ 安全提示： 这些导入项会在构建时从 node_modules 解析。 构建前，请确保已安装的 Syncfusion 软件包与 package-lock.json 或 yarn.lock 中固定的版本一致。请勿在未提供子资源完整性（SRI）哈希的情况下 从 CDN 获取这些文件。

/* 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';

常见模式

使用 Change 事件进行选择

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

selectedValues: string[] = [];

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

模板：

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

用于传输的双 ListBox

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

selectedItems = [];

模板：

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

筛选后的 ListBox

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())
  );
}

关键属性

选择配置

• selectionSettings：{ mode: 'Single' | 'Multiple', showCheckbox: boolean, showSelectAll: boolean, checkboxPosition: 'Left' | 'Right' } > 注意： 使用 showCheckbox: true 时，必须注入 CheckBoxSelection：

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

• value：获取或设置所选值（string[] | number[] | boolean[]）

数据和显示

• dataSource：包含项目的数组或 DataManager
• fields：{ text, value, groupBy, iconCss, disabled, htmlAttributes }
• itemTemplate：用于渲染每个列表项目的模板
• noRecordsTemplate：没有匹配项目时显示的模板

交互

• allowDragAndDrop：启用拖放排序/转移
• scope：标识用于拖放转移的相关 ListBox
• allowFiltering：显示内置筛选搜索栏
• filterBarPlaceholder：筛选栏的占位文本
• filterType：'StartsWith' | 'EndsWith' | 'Contains'
• toolbarSettings：配置双 ListBox 转移的工具栏按钮

外观

• height：ListBox 的高度
• sortOrder：'None' | 'Ascending' | 'Descending'
• enabled：启用/禁用组件
• enableRtl：从右向左渲染
• cssClass：附加 CSS 类

后续步骤

1. 开始使用：阅读 references/listbox-getting-started.md 了解设置说明
2. 选择模式：查看 references/listbox-selection-modes.md，选择适合你使用场景的模式
3. 绑定数据：参阅 references/listbox-data-binding.md 了解数据源选项
4. 添加交互：探索 references/listbox-drag-and-drop-features.md 了解高级功能
5. 自定义：查看 references/listbox-customization.md 了解样式选项
6. 查看示例：参阅 references/listbox-practical-examples.md 了解实际应用
7. API 参考：查阅 references/listbox-api.md，了解完整的属性、方法、事件和接口定义

常见使用场景

• 选择表单：替代多选下拉列表
• 转移列表：在列表之间移动项目（双 ListBox）
• 分类：按组组织项目
• 筛选：筛选大型数据集
• 数据显示：显示结构化列表数据
• 无障碍访问：符合规范的选择界面

Mention

在目标元素中输入字符（默认为 @）时触发的自动补全建议弹出窗口。支持用户标记、自定义触发字符、富文本集成、远程数据、模板和完整的无障碍访问功能。

组件概览与架构

Mention 组件会在用户于目标元素（div[contenteditable]、textarea 或类似元素）中输入触发字符（默认为 @）时，呈现自动补全建议弹出窗口。它专为以下用途设计：

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

主要特征

方面	详情
触发字符	通过 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 区域设置键

---

文档导航指南

📄 入门指南

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

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

📄 数据绑定

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

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

📄 筛选

阅读： references/mention-filtering.md

• 使用 filterType（Contains、StartsWith、EndsWith）控制筛选策略
• 使用 minLength 设置触发筛选前的最小输入长度
• 使用 allowSpaces 允许提及搜索词中间包含空格
• 使用 suggestionCount 限制可见建议数量
• 为远程数据源调整防抖延迟 debounceDelay

📄 模板

阅读： references/mention-templates.md

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

📄 自定义

阅读： references/mention-customization.md

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

📄 排序与禁用项

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

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

📄 无障碍与本地化

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

• 符合 WCAG 2.2、Section 508 和 ADA 标准
• 完整的键盘快捷键支持（向下／向上箭头、Enter、Tab、Escape）
• ARIA 属性：aria-selected、aria-activedescendent、aria-owns
• 使用 L10n.load() 本地化 noRecordsTemplate
• 使用 enableRtl 支持 RTL

📄 API 参考

阅读： references/mention-api.md

• 完整的属性参考，包含类型、默认值和说明
• 所有方法：addItem、disableItem、getDataByValue、getItems、hidePopup、showPopup、search、destroy
• 所有事件：dataBound、actionFailureTemplate

---

快速入门示例

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

安装软件包：

⚠️ **安全提示：**请将软件包固定到特定版本，以防意外升级到可能已遭入侵的版本。 安装后，请对照锁定文件（package-lock.json / yarn.lock）验证已安装的版本。

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

添加 CSS（styles.css）：

⚠️ **安全提示：**这些导入项会在构建时从 node_modules 解析。 构建前，请确保已安装的 Syncfusion 软件包与 package-lock.json 或 yarn.lock 中固定的版本一致。不要在未使用 子资源完整性（SRI）哈希的情况下从 CDN 加载这些文件。

@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';

---

常见模式

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

public userData: { [key: string]: Object }[] = [
  { Name: 'Selma Rose', EmailId: '[email protected]' },
  { Name: 'Maria', EmailId: '[email protected]' },
  { Name: 'Robert', EmailId: '[email protected]' }
];
public fields: Object = { text: 'Name' };
public mentionTarget: string = '#mentionElement';

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

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

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

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

🔒 安全策略 — 远程数据属于受限模式。 将 Mention 绑定到远程端点前，必须先进行安全审查（参见 安全与信任边界），然后才能在生产环境中使用。 远程数据绑定的详细信息和要求见 references/mention-data-binding.md。 此处默认不提供远程 DataManager 示例。

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

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

---

关键属性速查

属性	类型	默认值	用途
target	HTMLElement | string	—	显示 Mention 建议项的目标元素
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	允许 Mention 搜索词中间包含空格
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 类
locale	string	'en-US'	本地化区域设置
enableRtl	boolean	false	启用从右到左的渲染
enablePersistence	boolean	false	在重新加载期间保留状态
zIndex	number	1000	弹出框的 z-index

---

工作流决策树

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

MultiSelect

多值选择下拉列表（ejs-multiselect），支持四种视觉模式（Default/Box/Delimiter/CheckBox）、丰富的筛选功能、模板、分组、远程数据、虚拟化，以及与 Angular 表单的完整集成。

组件概述

模式	行为	适用场景
Default	在输入框中以标签形式显示所选项	标准多选
Box	与 Default 相同，采用明确的方框显示	需要清晰的视觉效果
Delimiter	将所选项显示为逗号分隔的文本	空间受限的布局
CheckBox	弹出框中每个选项都显示复选框	批量选择工作流

文档导航指南

入门指南

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

• 安装和软件包设置（ng add）
• CSS 导入和主题配置
• 在独立 Angular 组件中使用基本的 <ejs-multiselect>
• 弹出窗口高度和宽度配置
• Angular 版本说明（Angular 19+ 默认采用独立模式）

数据绑定和值绑定

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

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

选择模式、标签和项目控制

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

• mode 属性：Default / Box / Delimiter / CheckBox
• CheckBox 模式：CheckBoxSelection、showSelectAll、maximumSelectionLength
• 通过 tagging 事件自定义标签
• 使用 allowCustomValue 添加自定义值
• 禁用特定项目：fields.disabled、disableItem()
• addTagOnBlur 和 changeOnBlur 行为

筛选

📄 阅读： references/multiselect-filtering.md

• 启用 allowFiltering，并使用 filtering 事件和 updateData()
• filterType：startsWith、contains、endsWith
• 查询触发前的最小字符数阈值
• 使用 DataManager 进行远程筛选
• 不区分大小写的匹配

模板

📄 阅读： references/multiselect-templates.md

• itemTemplate — 使用 ng-template 自定义列表项的呈现
• valueTemplate — 自定义标签／已选值的显示
• groupTemplate — 自定义分组标题内容
• headerTemplate / footerTemplate — 弹出窗口顶部／底部
• noRecordsTemplate / actionFailureTemplate

分组与级联

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

• fields.groupBy — 将项目整理到不同类别
• 固定式与内联式分组标题
• 使用 enableGroupCheckBox 实现组级别的“全选”
• 级联 MultiSelect：父项的 change 事件 → 筛选子项数据
• 国家 → 州 → 城市级联模式

表单集成

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

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

高级功能

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

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

API 参考

📄 阅读： references/multiselect-api.md

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

快速开始

⚠️ 安全提示： 将软件包固定到特定版本，以防意外升级到可能遭到入侵的版本。 安装后，请根据锁定文件（package-lock.json / yarn.lock）验证已安装的版本。

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

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

⚠️ 安全提示： 构建时会从 node_modules 解析这些导入。 构建前，请确保已安装的 Syncfusion 软件包与 package-lock.json 或 yarn.lock 中固定的版本一致。不要在未提供 Subresource Integrity（SRI）哈希的情况下从 CDN 获取这些文件。

/* 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';

常见模式

带全选的复选框模式

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>
  `
})

使用远程数据进行筛选

🔒 安全策略 — 远程数据属于受限模式。 将 MultiSelect 绑定到远程端点前，必须先进行安全审查（参见 安全与信任边界），之后才能在生产环境中使用。 远程筛选的详细信息和要求记录在 references/multiselect-filtering.md 中。 此处默认不提供远程 DataManager 示例。

响应式表单集成

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>

关键属性

属性	类型	用途
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	在 CheckBox 模式下显示“全选”
maximumSelectionLength	number	限制可选项目的数量
allowCustomValue	boolean	允许用户添加列表中不存在的值
enableVirtualization	boolean	优化大型列表的渲染
popupHeight / popupWidth	string	限制弹出窗口的尺寸
allowResize	boolean	允许用户拖动调整弹出窗口大小
placeholder	string	输入提示文本

多列组合框

多列组合框（ejs-multicolumncombobox）是一种下拉组件，可在类似网格的多列弹出窗口中显示数据。它支持列配置、数据绑定（本地/远程）、筛选、排序、分组、模板、虚拟化、事件和无障碍功能。

导航指南

入门

📄 阅读： 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）

列配置

📄 阅读： references/columns.md

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

数据绑定

📄 阅读： references/data-binding.md

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

项目和显示配置

📄 阅读： 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）

筛选

📄 阅读： references/filtering.md

• 使用 allowFiltering 启用/禁用筛选
• 使用 filterType（StartsWith/EndsWith/Contains）更改筛选类型

排序

📄 阅读： references/sorting.md

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

分组

📄 阅读： references/grouping.md

• 在 fields 属性中使用 groupBy 字段对项目分组

模板

📄 阅读： references/templates.md

• 使用 itemTemplate 自定义行项目
• 使用 headerTemplate 自定义列标题
• 使用 groupTemplate 自定义分组标题
• 使用 footerTemplate 设置页脚内容
• 使用 noRecordsTemplate 设置无记录时的占位内容
• 使用 actionFailureTemplate 设置远程请求失败时的显示内容

事件

📄 阅读： references/events.md

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

虚拟化

📄 阅读： references/virtualization.md

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

无障碍与本地化

📄 阅读： references/accessibility.md

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

API 参考

📄 阅读： references/api.md

• 属性、方法和事件的完整列表
• ColumnModel 接口属性
• GridSettingsModel 接口
• 方法：showPopup、hidePopup、focusIn、focusOut、getDataByValue、getItems、addItems

快速开始

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';
}

常见模式

使用 DataManager 加载远程数据

当数据来自 API 时，使用 DataManager → 阅读 references/data-binding.md

大型数据集（150+ 行）

启用 enableVirtualization，避免性能问题 → 阅读 references/virtualization.md

丰富的行显示

使用列 template 和 ng-template 显示图像、徽章或自定义 HTML → 阅读 references/columns.md

分组下拉列表

在 fields 中设置 groupBy，对项目进行分类 → 阅读 references/grouping.md

以编程方式打开/关闭

使用 showPopup() / hidePopup() 方法 → 阅读 references/api.md