syncfusion-javascript-dropdowns

Syncfusion javascript 下拉框

DropDownList

Syncfusion DropDownList 组件提供单选下拉框，支持本地／远程数据绑定、筛选、分组、自定义模板、虚拟滚动、无障碍功能和级联模式，全部使用 TypeScript 实现。

文档和导航指南

入门

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

• 安装和软件包依赖项
• 在 input、select 和 UL 标签上初始化 DropDownList
• 绑定简单的数据数组
• 配置弹出窗口的高度和宽度
• 使用 appendTo 首次渲染

数据绑定

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

• 绑定字符串数组、JSON 对象和复杂嵌套数据
• 使用 fields 映射 text、value、iconCss、groupBy 和 disabled 列
• 使用 DataManager 处理远程数据（OData、ODataV4 适配器）
• 使用 query 筛选／排序远程数据
• 基本类型值与对象值绑定（allowObjectBinding）

筛选

📄 阅读： references/dropdownlist-filtering.md

• 启用 allowFiltering 和筛选栏
• 使用 updateData 处理 filtering 事件
• 筛选类型：startsWith、endsWith、contains
• 最少字符数限制、区分大小写的筛选、变音符号（ignoreAccent）
• 用于提升性能的 debounceDelay
• 使用 highlightSearch 高亮匹配字符
• 限制搜索结果数量

分组

📄 阅读： references/dropdownlist-grouping.md

• 映射 groupBy 字段以按类别分组
• 行内和固定分组标题
• 支持带有 <optgroup> 的 HTML <select>
• 使用 groupTemplate 自定义分组标题
• 通过 CSS 禁用固定分组标题

模板

📄 阅读： references/dropdownlist-templates.md

• itemTemplate — 自定义每个列表项
• valueTemplate — 自定义所选值的显示方式
• groupTemplate — 自定义分组标题
• headerTemplate 和 footerTemplate — 静态弹出窗口页眉／页脚
• noRecordsTemplate 和 actionFailureTemplate

功能和配置

📄 阅读： references/dropdownlist-features.md

• 通过 fields.disabled 和 disableItem 方法禁用项目
• 使用 showClearButton 或通过编程方式清除选择
• 使用 allowResize 调整弹出窗口大小
• 使用 enableVirtualization 对大型数据集启用虚拟滚动
• 增量搜索（内置）
• floatLabelType、enabled、readonly、sortOrder
• htmlAttributes、cssClass、width、zIndex

事件和方法

📄 阅读： references/dropdownlist-events-and-methods.md

• 带有 isInteracted 标志的 change 事件
• open、close、beforeOpen、select、dataBound 事件
• 远程数据的 actionBegin、actionComplete、actionFailure
• filtering、focus、blur 事件
• showPopup、hidePopup、addItem、getItems、getDataByValue
• dataBind、clear、refresh、destroy、focusIn、focusOut

级联 DropDownList

📄 阅读： references/dropdownlist-cascading.md

• Country → State → City 级联模式
• 使用 change 事件和 Query 筛选子级下拉框数据
• 属性更改后调用 dataBind
• 在级联下拉框中预选项目

样式和无障碍功能

📄 阅读： references/dropdownlist-style-and-accessibility.md

• 用于自定义包装元素、图标、焦点、悬停和弹出窗口的 CSS 类
• 带星号的浮动标签
• WAI-ARIA 角色和属性
• 完整的键盘快捷键参考
• 使用 enableRtl 支持 RTL
• 使用 L10n 进行本地化

API 参考

📄 阅读： references/dropdownlist-api.md

• 完整的属性列表，包含类型和默认值
• 所有方法及其参数和返回类型
• 所有事件及其说明
• FieldSettingsModel 参考

---

安装

npm install @syncfusion/ej2-dropdowns
npm audit

快速入门

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

// Simple string array
let dropDownListObject: DropDownList = new DropDownList({
    dataSource: ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'],
    placeholder: 'Select a game'
});
dropDownListObject.appendTo('#ddlelement');

<input type="text" id="ddlelement" />

---

常见模式

使用字段映射的 JSON 数据

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

let sportsData: { [key: string]: Object }[] = [
    { Id: 'game1', Game: 'Badminton' },
    { Id: 'game2', Game: 'Football' },
    { Id: 'game3', Game: 'Tennis' }
];

let ddl: DropDownList = new DropDownList({
    dataSource: sportsData,
    fields: { text: 'Game', value: 'Id' },
    placeholder: 'Select a game'
});
ddl.appendTo('#ddlelement');

使用 OData 的远程数据

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

let ddl: DropDownList = new DropDownList({
    dataSource: new DataManager({
        url: 'url', // Replace with your trusted API endpoint
        adaptor: new ODataV4Adaptor,
        crossDomain: true  // Enable only when the API origin differs from your app; use only with trusted endpoints
    }),
    query: new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6),
    fields: { text: 'ContactName', value: 'CustomerID' },
    placeholder: 'Select a customer',
    sortOrder: 'Ascending'
});
ddl.appendTo('#ddlelement');

使用搜索框筛选

import { DropDownList, FilteringEventArgs } from '@syncfusion/ej2-dropdowns';
import { DataManager, Query } from '@syncfusion/ej2-data';

let ddl: DropDownList = new DropDownList({
    dataSource: searchData,
    fields: { text: 'Country', value: 'Index' },
    allowFiltering: true,
    placeholder: 'Select a country',
    filtering: (e: FilteringEventArgs) => {
        let query = new Query();
        query = e.text !== '' ? query.where('Country', 'startswith', e.text, true) : query;
        e.updateData(searchData, query);
    }
});
ddl.appendTo('#ddlelement');

处理值变更

let ddl: DropDownList = new DropDownList({
    dataSource: sportsData,
    fields: { text: 'Game', value: 'Id' },
    placeholder: 'Select a game',
    change: (args) => {
        if (args.isInteracted) {
            console.log('User selected:', args.value);
        } else {
            console.log('Programmatic change:', args.value);
        }
    }
});

---

核心属性一览

属性	类型	用途
dataSource	array | DataManager	用于填充列表的数据
fields	FieldSettingsModel	映射 text、value、groupBy、iconCss、disabled
value	string | number | boolean | object	选定的值
text	string	选定项的显示文本
index	number	选定项的索引
placeholder	string	输入框占位文本
allowFiltering	boolean	显示筛选栏
enableVirtualization	boolean	对大型列表启用虚拟滚动
sortOrder	'None' | 'Ascending' | 'Descending'	对列表项排序
showClearButton	boolean	显示清除（×）按钮
enabled	boolean	启用／禁用组件
readonly	boolean	禁止用户交互
popupHeight	string | number	弹出窗口高度（默认 300px）
popupWidth	string | number	弹出窗口宽度（默认 100%）

---

MultiSelect

Syncfusion TypeScript MultiSelect 组件是功能丰富的下拉框，允许用户从列表中选择一个或多个值。它支持数据绑定、筛选、分组、级联、自定义模板和全面的无障碍功能。

文档导航指南

入门

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

• 安装和软件包设置
• CSS 导入和主题配置
• 元素初始化（SELECT、UL、INPUT 标签）
• 使用数据进行基本组件设置

数据绑定与数据源

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

• 绑定本地数据数组（字符串和对象）
• 连接远程数据源
• 使用适配器配置 DataManager
• 字段映射和数据格式规范

选择模式和值

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

• 单选和多选模式
• 使用 value 属性（选定值数组）
• 以编程方式获取／设置选定值
• 选择变更事件和处理程序

复选框与多选功能

📄 阅读： references/multiselect-checkbox-multiselect.md

• 启用复选框模式以进行可视化多选
• 全选／取消全选功能
• 分隔符模式与可视化标签显示
• 自定义复选框外观

筛选与搜索

📄 阅读： references/multiselect-filtering-search.md

• 启用实时筛选
• 自定义筛选逻辑和表达式
• 搜索前的最少字符数验证
• 区分大小写和不区分大小写的筛选

分组与排序

📄 阅读： references/multiselect-grouping-sorting.md

• 按类别字段对项进行分组
• 按升序／降序排序
• 自定义分组模板
• 层级数据分组

级联下拉框

📄 阅读： references/multiselect-cascading-dropdowns.md

• 两级和多级级联
• 处理父子数据同步
• 级联时加载远程数据
• 父级变更时重置子级下拉框

自定义与模板

📄 阅读： references/multiselect-customization-templates.md

• 列表项的项目模板
• 显示区域的值模板
• 分组项目的分组模板
• 页眉和页脚模板
• CSS 自定义与样式设置

性能：虚拟滚动

📄 阅读： references/multiselect-virtual-scrolling.md

• 为大型数据集启用虚拟滚动
• 性能优化技巧
• 虚拟滚动与筛选和分组
• 内存与渲染注意事项

无障碍与标准

📄 阅读： references/multiselect-accessibility.md

• 符合 WCAG 2.2 及相关标准
• 键盘导航（方向键、Tab、Enter、Escape）
• ARIA 属性和角色
• 屏幕阅读器支持与焦点管理

使用指南与故障排除

📄 阅读： references/multiselect-how-to-guide.md

• 常见实现模式与范例
• 边缘情况与解决方法
• 性能技巧与最佳实践
• 常见问题的故障排除

API 参考

📄 阅读： references/multiselect-api.md

• 所有属性及其类型和默认值的完整列表
• 所有公共方法及其参数签名和返回类型
• 所有事件及其参数类型和用法
• FieldSettingsModel 字段映射参考
• 事件参数类型定义（MultiSelectChangeEventArgs、SelectEventArgs、RemoveEventArgs、TaggingEventArgs、FilteringEventArgs 等）
• CheckBoxSelection 和 VirtualScroll 的模块注入指南

快速入门示例

基本设置

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

// Initialize with simple string data
const multiSelect = new MultiSelect({
  dataSource: ['Apple', 'Banana', 'Orange', 'Mango'],
  placeholder: 'Select fruits'
});

multiSelect.appendTo('#select');

带复选框的多选

import { MultiSelect, CheckBoxSelection } from '@syncfusion/ej2-dropdowns';

MultiSelect.Inject(CheckBoxSelection);

const multiSelect = new MultiSelect({
  dataSource: [
    { id: '1', name: 'Apple' },
    { id: '2', name: 'Banana' },
    { id: '3', name: 'Orange' }
  ],
  fields: { text: 'name', value: 'id' },
  mode: 'CheckBox',
  showSelectAll: true,
  placeholder: 'Select fruits'
});

multiSelect.appendTo('#select');

带筛选功能

import { MultiSelect, FilteringEventArgs } from '@syncfusion/ej2-dropdowns';
import { Query } from '@syncfusion/ej2-data';

const data = [
  { id: '1', city: 'New York' },
  { id: '2', city: 'Los Angeles' },
  { id: '3', city: 'Chicago' }
];

const multiSelect = new MultiSelect({
  dataSource: data,
  fields: { text: 'city', value: 'id' },
  allowFiltering: true,
  filtering: (e: FilteringEventArgs) => {
    const query = new Query();
    if (e.text !== '') {
      query.where('city', 'startswith', e.text, true);
    }
    e.updateData(data, query);
  },
  placeholder: 'Search cities'
});

multiSelect.appendTo('#select');

常见模式

模式 1：级联下拉列表

// Country dropdown
const countrySelect = new MultiSelect({
  dataSource: countries,
  fields: { text: 'name', value: 'id' },
  change: () => {
    const selectedCountry = countrySelect.value;
    // Update state dropdown based on selected country
    stateSelect.dataSource = states.filter(s => s.countryId === selectedCountry);
    stateSelect.refresh();
  }
});

countrySelect.appendTo('#country');

模式 2：远程数据绑定

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

const multiSelect = new MultiSelect({
  dataSource: new DataManager({
    url: 'url', // Replace with your trusted API endpoint
    adaptor: new ODataV4Adaptor(),
    crossDomain: true  // Enable only when the API origin differs from your app; use only with trusted endpoints
  }),
  query: new Query().select(['ContactName', 'CustomerID']).take(10),
  fields: { text: 'ContactName', value: 'CustomerID' },
  placeholder: 'Select customer'
});

multiSelect.appendTo('#select');

模式 3：自定义项目模板

⚠️ 安全提示： 模板字符串使用 ${field} 插值。如果字段值来自用户输入或远程源，请在绑定前对其进行清理或编码，以防止 XSS 注入。

const multiSelect = new MultiSelect({
  dataSource: employees,
  fields: { text: 'firstName', value: 'id' },
  itemTemplate: '<div><span>${firstName}</span><span>${department}</span></div>',
  valueTemplate: '<span>${firstName} - ${department}</span>',
  placeholder: 'Select employee'
});

multiSelect.appendTo('#select');

关键属性速查

属性	类型	默认值	用途
dataSource	array | DataManager	[]	将数据绑定到组件
fields	FieldSettingsModel	{}	映射数据字段（text、value、groupBy、iconCss）
value	string[] | number[] | boolean[] | object[]	null	获取/设置所选值
mode	'Box' | 'Delimiter' | 'Default' | 'CheckBox'	'Default'	选择显示模式
allowFiltering	boolean	null	启用搜索/筛选功能
enableVirtualization	boolean	false	启用虚拟滚动以提升性能
itemTemplate	string | Function	null	列表项的自定义 HTML
valueTemplate	string | Function	null	所选内容的自定义 HTML
placeholder	string	null	输入框占位文本
showSelectAll	boolean	false	在 CheckBox 模式下显示“全选”选项
enableGroupCheckBox	boolean	false	在 CheckBox 模式下启用分组标题复选框
maximumSelectionLength	number	1000	限制可选项数量
allowCustomValue	boolean	false	允许输入列表中不存在的值
closePopupOnSelect	boolean	true	每次选择后保持弹出窗口打开
hideSelectedItem	boolean	true	在下拉列表中隐藏已选项
delimiterChar	string	','	Delimiter 模式下的分隔符
showClearButton	boolean	true	在每个标签上显示移除图标
showDropDownIcon	boolean	false	显示下拉箭头按钮
enabled	boolean	true	启用/禁用组件
readonly	boolean	false	将组件设为只读
zIndex	number	1000	弹出元素的 z-index

📘 如需查看包含所有属性、方法和事件的完整 API，请参阅 references/multiselect-api.md。

相关功能

• 数据格式： JSON、XML、OData、Web API
• 主题： Material、Bootstrap、Fabric、Tailwind
• 分组： 使用自定义模板按类别对项分组
• 排序： 升序、降序
• 本地化： 多语言支持
• RTL 支持： 从右向左语言支持
• 键盘导航： 完整的键盘辅助功能

AutoComplete

AutoComplete 组件会在用户向输入框中输入内容时显示匹配的建议列表。它扩展了 ComboBox，采用筛选优先的行为——默认情况下，只有用户输入时才会打开弹出窗口，而不会在获得焦点时打开。

主要功能：

• 按 StartsWith、EndsWith 或 Contains（默认）筛选建议
• 绑定本地数组（字符串、数字、对象）或远程 DataManager 数据源
• 在建议列表中高亮匹配字符
• 控制触发筛选前所需的最少字符数（minLength）
• 通过 filtering 事件处理或覆盖筛选逻辑
• 通过 showPopup() / hidePopup() 以编程方式打开/关闭弹出窗口
• 支持浮动标签以及完整的辅助功能/键盘导航

---

导航指南

快速入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• HTML 元素设置（<input>）
• 使用 new AutoComplete() 进行基本实例化
• 使用 appendTo() 绑定到 DOM
• CSS 和主题导入
• 最小可运行示例

筛选配置

📄 阅读： references/filtering.md

• filterType：StartsWith、EndsWith、Contains
• minLength：运行筛选前所需的最少字符数
• ignoreCase：区分大小写或不区分大小写的搜索
• filtering 事件：使用 updateData() 编写自定义筛选逻辑
• filter() 方法：以编程方式筛选
• 使用 DataManager 筛选远程数据

数据绑定

📄 阅读： references/data-binding.md

• 本地字符串、数字和对象数组
• fields 映射：text、value、iconCss、groupBy
• 使用 DataManager 的 query 属性
• 用于自定义 HTML 属性的 htmlAttributes
• 远程数据源模式

高亮与建议控制

📄 阅读： references/highlight-and-suggestions.md

• highlight：以视觉方式高亮匹配的字符
• suggestionCount：限制弹出列表项的数量
• showPopupButton：切换弹出触发按钮
• showPopup() / hidePopup()：以编程方式控制弹出框

自定义与无障碍功能

📄 阅读： references/customization.md

• floatLabelType：Never、Always、Auto
• CSS 类覆盖与主题设置
• 键盘导航与 ARIA 支持
• 禁用状态
• RTL 支持

虚拟化

📄 阅读： references/virtualization.md

• AutoComplete.Inject(VirtualScroll) — 必需的模块注入
• enableVirtualization: true — 启用虚拟滚动
• 使用大型数组进行本地数据虚拟化
• 使用 DataManager 进行远程数据虚拟化
• 使用 query.take() 自定义批次大小
• 虚拟化分组

完整 API 参考

📄 阅读： references/api.md

• 全部 37 个属性，包含类型、默认值和 TypeScript 示例
• 全部 19 个方法，包含完整签名、参数和返回类型
• 全部 18 个事件，包含事件参数详情和用法示例
• 涵盖：actionFailureTemplate、allowCustom、allowObjectBinding、allowResize、autofill、cssClass、dataSource、debounceDelay、enablePersistence、enableRtl、enableVirtualization、enabled、fields、filterType、floatLabelType、footerTemplate、groupTemplate、headerTemplate、highlight、htmlAttributes、ignoreAccent、ignoreCase、isDeviceFullScreen、itemTemplate、locale、minLength、noRecordsTemplate、placeholder、popupHeight、popupWidth、query、readonly、showClearButton、showPopupButton、sortOrder、suggestionCount、value、width、zIndex
• 查询特定属性、方法或事件名称时，请参阅此处

---

快速开始

<input id="atc" type="text" />

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

// Local string array
const sports: string[] = ['Badminton', 'Basketball', 'Cricket', 'Football', 'Hockey', 'Tennis'];

const atcObj: AutoComplete = new AutoComplete({
  dataSource: sports,
  placeholder: 'Find a sport'
});

atcObj.appendTo('#atc');

/* Import a built-in theme */
@import '../node_modules/@syncfusion/ej2/material.css';

输入任意字符——匹配项会显示在建议弹出框中。按 Enter 或点击某条建议即可选择。

---

常见模式

按 StartsWith 而不是 Contains 进行筛选

const atcObj: AutoComplete = new AutoComplete({
  dataSource: sports,
  filterType: 'StartsWith',
  placeholder: 'Search'
});
atcObj.appendTo('#atc');

使用字段映射的对象数据

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

const employees: { [key: string]: Object }[] = [
  { id: 1, name: 'Alice', dept: 'Engineering' },
  { id: 2, name: 'Bob',   dept: 'Design' },
  { id: 3, name: 'Carol', dept: 'Engineering' }
];

const atcObj: AutoComplete = new AutoComplete({
  dataSource: employees,
  fields: { value: 'id', text: 'name', groupBy: 'dept' },
  placeholder: 'Find employee'
});
atcObj.appendTo('#atc');

通过事件进行自定义筛选

import { AutoComplete, FilteringEventArgs } from '@syncfusion/ej2-dropdowns';
import { Query } from '@syncfusion/ej2-data';

const atcObj: AutoComplete = new AutoComplete({
  dataSource: sports,
  filtering: (e: FilteringEventArgs) => {
    let query: Query = new Query().where('', 'startswith', e.text, true);
    e.updateData(sports, query);
  }
});
atcObj.appendTo('#atc');

高亮匹配文本并限制建议数量

const atcObj: AutoComplete = new AutoComplete({
  dataSource: sports,
  highlight: true,
  suggestionCount: 5,
  placeholder: 'Search (max 5 results)'
});
atcObj.appendTo('#atc');

---

关键属性

属性	类型	默认值	用途
dataSource	Object[] | DataManager | string[]	[]	要搜索的数据
fields	FieldSettingsModel	{ value: null, iconCss: null, groupBy: null }	将对象键映射到显示值/值
filterType	FilterType	'Contains'	输入内容与数据的匹配方式
minLength	number	1	触发筛选前输入的最少字符数
ignoreCase	boolean	true	匹配时不区分大小写
ignoreAccent	boolean	false	筛选时忽略变音符号/重音字符
highlight	boolean	false	在弹出框中高亮匹配的字符
suggestionCount	number	20	弹出框中显示的最多项目数
autofill	boolean	false	将第一个匹配项自动填入输入框
allowCustom	boolean	true	允许使用数据源中不存在的值
allowObjectBinding	boolean	false	选择时将完整对象作为 value 返回
allowResize	boolean	false	在弹出框上显示调整大小手柄
showPopupButton	boolean	false	显示下拉箭头按钮
showClearButton	boolean	true	显示 ✕ 清除按钮
floatLabelType	FloatLabelType	'Never'	标签浮动行为
htmlAttributes	{ [key: string]: string }	{}	输入框的额外 HTML 属性
query	Query	null	DataManager 的自定义查询
debounceDelay	number	300	按键后执行筛选前的延迟时间（毫秒）
sortOrder	SortOrder	null	弹出列表的排序顺序：None、Ascending、Descending
enableVirtualization	boolean	false	对大型数据集启用虚拟滚动
isDeviceFullScreen	boolean	true	在移动设备上筛选时以全屏显示弹出框
enablePersistence	boolean	false	页面重新加载后保留 value
enableRtl	boolean	false	从右向左渲染
popupHeight	string | number	'300px'	建议弹出框的高度
popupWidth	string | number	'100%'	建议弹出框的宽度
zIndex	number	1000	弹出元素的 Z-index

关键事件：

事件	触发时机
filtering	每次按键时触发——使用 e.updateData() 提供自定义结果
change	通过选择或用户输入导致值发生变化时触发
select	用户从弹出框中选择项目时触发
open / close	弹出框打开或关闭时触发
beforeOpen	弹出框即将打开时触发
focus / blur	组件获得或失去焦点时触发
dataBound	数据源加载到弹出框中时触发
actionBegin / actionComplete / actionFailure	远程数据获取生命周期事件
customValueSpecifier	用户输入数据源中不存在的值时触发（allowCustom: true）
resizeStart / resizing / resizeStop	弹出框调整大小的生命周期事件（allowResize: true）
created / destroyed	组件创建和销毁时触发

关键方法： showPopup()、hidePopup()、filter(dataSource, query?, fields?)、clear()、addItem()、disableItem()、getDataByValue()、getItems()、focusIn()、focusOut()、showSpinner()、hideSpinner()、refresh()、destroy()。

ComboBox

ComboBox 组件允许用户直接在输入框中输入值，或从预定义选项的下拉列表中选择选项。它介于普通文本输入框和严格的 DropDownList 之间，灵活性适中——默认情况下，用户无需选择现有项目（除非将 allowCustom 设为 false）。

与 DropDownList 的主要区别：

• 用户可以自由输入；默认接受自定义值（allowCustom: true）
• 用户输入时，autofill 会在输入框中显示第一个匹配项作为建议
• customValueSpecifier 事件允许你格式化和转换用户输入的自定义值
• 支持通过 allowFiltering 实现行内搜索体验（无需单独的筛选栏）

---

组件概览

功能	ComboBox 行为
用户输入	可编辑 — 用户可直接在输入框中键入内容
自定义值	默认允许（allowCustom: true）
内联建议	可通过 autofill: true 启用
筛选	可通过 allowFiltering: true 和 filtering 事件启用
虚拟化	支持通过 ComboBox.Inject(VirtualScroll) 启用
数据绑定	本地数组、对象数组、DataManager（远程）
对象绑定	通过 allowObjectBinding: true 绑定完整对象值

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序包设置
• CSS/主题导入
• HTML 元素设置（<select> 或 <input>）
• 使用 new ComboBox({}).appendTo('#id') 进行基本实例化
• 初始化 value、text、index
• showClearButton、placeholder、width
• 销毁组件

数据绑定

📄 阅读： references/data-binding.md

• 本地字符串数组
• 使用 fields 映射（text、value、groupBy）的本地对象数组
• 使用 htmlAttributes 自定义输入元素
• 使用 DataManager 连接远程数据
• 使用 query 属性自定义数据查询
• 使用 allowObjectBinding 绑定完整对象值

筛选

📄 阅读： references/filtering.md

• 使用 allowFiltering: true 启用搜索
• filtering 事件和 FilteringEventArgs 的用法
• 使用 filter() 方法自定义筛选本地和远程数据
• 移动设备上的 isDeviceFullScreen 行为
• 无匹配项模板处理

自定义值

📄 阅读： references/custom-values.md

• allowCustom: true/false — 控制是否接受键入的值
• autofill — 用户键入时显示内联建议
• 用于格式化自定义键入值的 customValueSpecifier 事件
• CustomValueSpecifierEventArgs 接口（text、item）
• 使用 clear() 和 showClearButton 清除自定义值
• 将 allowObjectBinding 与自定义值结合使用

自定义

📄 阅读： references/customization.md

• floatLabelType：Never / Always / Auto
• 用于自定义样式的 cssClass
• 用于弹出窗口页眉和页脚的 headerTemplate / footerTemplate
• placeholder、width、popupHeight、popupWidth
• readonly 模式
• 弹出窗口控制：showPopup() / hidePopup()
• 焦点控制：focusIn() / focusOut()
• 加载指示器：showSpinner() / hideSpinner()

虚拟化

📄 阅读： references/virtualization.md

• ⚠️ 必须注入模块：ComboBox.Inject(VirtualScroll)
• 使用 enableVirtualization: true 处理大型数据集
• 本地数据虚拟化
• 远程 DataManager 虚拟化
• 与 allowCustom 和 allowFiltering 的交互

完整 API 参考

📄 阅读： references/api.md

• 全部 37 个公共属性，包含类型、默认值和示例
• 18 个事件及其参数接口
• 19 个方法，包含签名和用法
• CustomValueSpecifierEventArgs 接口

---

快速开始

import { ComboBox } from '@syncfusion/ej2-dropdowns';
import '@syncfusion/ej2-base/styles/material.css';
import '@syncfusion/ej2-inputs/styles/material.css';
import '@syncfusion/ej2-popups/styles/material.css';
import '@syncfusion/ej2-dropdowns/styles/material.css';

const sportsData: string[] = ['Badminton', 'Basketball', 'Cricket', 'Football', 'Tennis'];

const comboBox: ComboBox = new ComboBox({
  dataSource: sportsData,
  placeholder: 'Select or type a sport',
  allowCustom: true
});
comboBox.appendTo('#combo-element');

<input id="combo-element" />

---

常见模式

仅允许现有值

const comboBox: ComboBox = new ComboBox({
  dataSource: sportsData,
  allowCustom: false,        // reject values not in the list
  placeholder: 'Select a sport'
});
comboBox.appendTo('#combo-element');

内联自动填充建议

const comboBox: ComboBox = new ComboBox({
  dataSource: sportsData,
  autofill: true,            // suggests first match inline as user types
  placeholder: 'Start typing...'
});
comboBox.appendTo('#combo-element');

使用远程数据进行筛选

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

const comboBox: ComboBox = new ComboBox({
  dataSource: new DataManager({ url: 'url', adaptor: new ODataV4Adaptor() }),
  fields: { text: 'ContactName', value: 'CustomerID' },
  allowFiltering: true,
  filtering: (args: FilteringEventArgs) => {
    const query = new Query().select(['ContactName', 'CustomerID']).take(6);
    args.updateData(comboBox.dataSource as DataManager, query);
  },
  placeholder: 'Search customers'
});
comboBox.appendTo('#combo-element');

自定义值格式化

import { ComboBox, CustomValueSpecifierEventArgs } from '@syncfusion/ej2-dropdowns';

const comboBox: ComboBox = new ComboBox({
  dataSource: [{ text: 'Cricket', id: '1' }],
  fields: { text: 'text', value: 'id' },
  allowCustom: true,
  customValueSpecifier: (args: CustomValueSpecifierEventArgs) => {
    args.item = { text: args.text, id: args.text.toLowerCase() };
  }
});
comboBox.appendTo('#combo-element');

---

关键属性

属性	类型	默认值	用途
dataSource	Object[] | DataManager | string[]	[]	下拉列表的数据
fields	FieldSettingsModel	{}	映射 text、value、groupBy 键
value	number | string | boolean | object | null	null	选中的值
text	string | null	null	选中项的显示文本
index	number | null	null	选中项的索引
allowCustom	boolean	true	允许用户输入列表中没有的值
autofill	boolean	false	输入时显示行内建议
allowFiltering	boolean	false	在弹出窗口中显示搜索框
showClearButton	boolean	true	显示 ✕ 按钮以清除选择
placeholder	string	null	输入框占位文本
floatLabelType	FloatLabelType	'Never'	浮动标签行为
readonly	boolean	false	禁止用户交互
allowObjectBinding	boolean	false	将完整对象绑定为值
enableVirtualization	boolean	false	启用虚拟滚动 ⚠️ 需要 Inject

Mention

Mention 组件会监视目标元素（textarea、input 或 contenteditable div），并在用户输入配置的触发字符（默认为 @）时打开建议弹出窗口。用户选择一个项目后，该项目会以样式化标签的形式插入目标元素中。

主要功能：

• 通过 target 关联任意 <textarea>、<input> 或 contenteditable 元素
• 通过 mentionChar 配置触发字符（默认为 @）
• 绑定本地数组（字符串、对象）或远程 DataManager 数据源
• 使用 StartsWith、EndsWith 或 Contains（默认值）筛选建议
• 通过 highlight 在弹出窗口中高亮匹配的字符
• 使用 itemTemplate 自定义弹出项布局，并使用 displayTemplate 自定义插入的标签
• 控制弹出窗口的打开时机：minLength、requireLeadingSpace、debounceDelay
• 通过事件处理选择、更改和筛选
• 通过 search() 以编程方式触发搜索，并使用 disableItem() / addItem() 管理项目

---

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• CSS 和主题导入
• HTML 目标元素设置（textarea、input、contenteditable）
• 基本实例化：new Mention({ target: '#myTextarea', dataSource: [...] })
• appendTo() 的用法
• mentionChar — 触发字符配置
• 最小可运行示例

数据绑定

📄 阅读： references/data-binding.md

• 本地字符串和数字数组
• 使用 fields 映射（text、value、iconCss、groupBy）的对象数组
• 带有 actionBegin / actionComplete / actionFailure 事件的远程 DataManager
• 用于自定义数据查询的 query 属性
• sortOrder：None / Ascending / Descending
• 用于处理远程错误的 actionFailureTemplate

筛选

📄 阅读： references/filtering.md

• filterType：StartsWith、EndsWith、Contains
• minLength：弹出窗口显示前所需的最少字符数
• 使用 ignoreCase 和 ignoreAccent 实现灵活匹配
• debounceDelay：优化按键筛选性能
• filtering 事件和 FilteringEventArgs — 使用 updateData() 自定义筛选逻辑
• 远程数据筛选模式

弹出窗口和显示

📄 阅读： references/popup-and-display.md

• target：关联到 textarea、input 或 contenteditable
• requireLeadingSpace：要求在 @ 前输入空格
• allowSpaces：允许在 Mention 搜索词中包含空格
• popupWidth / popupHeight 尺寸设置
• 通过 showPopup() / hidePopup() 以编程方式控制
• 用于控制层叠顺序的 zIndex
• noRecordsTemplate / spinnerTemplate
• 弹出窗口生命周期事件：beforeOpen、opened、closed

模板和自定义

📄 阅读： references/templates-and-customization.md

• itemTemplate：自定义弹出列表中的每个建议项
• displayTemplate：自定义插入的标签 HTML
• groupTemplate：自定义弹出列表中的分组标题
• showMentionChar：在插入的标签中包含 @
• suffixText：在插入内容后追加空格或换行符
• highlight：将建议中的匹配字符加粗
• cssClass：用于组件级样式设置

事件和方法

📄 阅读： references/events-and-methods.md

• select 事件（SelectEventArgs）——用户选择项目时触发
• change 事件（MentionChangeEventArgs）——包含 value、previousItem、element
• filtering 事件——拦截并覆盖建议数据
• search(text, x, y)——在屏幕坐标处以编程方式触发搜索
• disableItem(item)——禁用指定的弹出列表项目
• addItem(items, index?)——向建议列表添加新项目
• getItems() / getDataByValue(value)——查询列表状态
• created / destroyed 生命周期事件

完整 API 参考

📄 阅读： references/api.md

• 所有 30 个公共属性的类型、默认值和说明
  • 所有 15 个方法的签名、参数和返回类型
  • 所有 12 个事件的事件参数接口详情
• MentionChangeEventArgs 接口字段
• 查询特定属性、方法或事件时使用此参考

---

快速入门

<textarea id="mentionTarget" rows="5" cols="40" placeholder="Type @ to mention someone"></textarea>
<div id="mention-default"></div>

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

const userData: { [key: string]: Object }[] = [
  { name: 'Alice',   id: 'alice' },
  { name: 'Bob',     id: 'bob'   },
  { name: 'Carol',   id: 'carol' },
  { name: 'David',   id: 'david' }
];

const mentionObj: Mention = new Mention({
  target: '#mentionTarget',
  dataSource: userData,
  fields: { text: 'name', value: 'id' }
});

mentionObj.appendTo('#mention-default');

/* Import a built-in theme */
@import '../node_modules/@syncfusion/ej2/material.css';

在文本区域中输入 @，建议弹出列表随即打开。继续输入更多字符以筛选。按 Enter、Tab 或单击，即可将所选项目作为标签插入。

---

常见模式

自定义触发字符

const mentionObj: Mention = new Mention({
  target: '#mentionTarget',
  dataSource: ['JavaScript', 'TypeScript', 'Python', 'Rust'],
  mentionChar: '#'   // use # as trigger instead of @
});
mentionObj.appendTo('#mention-default');

要求输入最少字符后才打开弹出列表

const mentionObj: Mention = new Mention({
  target: '#mentionTarget',
  dataSource: userData,
  fields: { text: 'name', value: 'id' },
  minLength: 2     // popup only appears after typing @ + 2 characters
});
mentionObj.appendTo('#mention-default');

高亮匹配文本并限制建议数量

const mentionObj: Mention = new Mention({
  target: '#mentionTarget',
  dataSource: userData,
  fields: { text: 'name', value: 'id' },
  highlight: true,
  suggestionCount: 5
});
mentionObj.appendTo('#mention-default');

允许在提及搜索中使用空格

const mentionObj: Mention = new Mention({
  target: '#mentionTarget',
  dataSource: [
    { name: 'Alice Smith',  id: '1' },
    { name: 'Bob Jones',    id: '2' }
  ],
  fields: { text: 'name', value: 'id' },
  allowSpaces: true   // typing "@Alice Smith" still searches
});
mentionObj.appendTo('#mention-default');

在插入的标签中显示 @ 符号

const mentionObj: Mention = new Mention({
  target: '#mentionTarget',
  dataSource: userData,
  fields: { text: 'name', value: 'id' },
  showMentionChar: true,   // chip reads "@Alice" instead of "Alice"
  suffixText: ' '          // insert a space after the chip
});
mentionObj.appendTo('#mention-default');

---

关键属性

属性	类型	默认值	用途
target	HTMLElement | string	—	必需。 要监测触发字符的元素
dataSource	Object[] | DataManager | string[]	[]	建议列表数据
fields	FieldSettingsModel	{ text: null, value: null, iconCss: null, groupBy: null }	映射对象键
mentionChar	string	'@'	打开弹出列表的字符
minLength	number	0	弹出列表显示前，触发字符后需输入的最少字符数
suggestionCount	number	25	弹出列表中显示的最大项目数
filterType	FilterType	'Contains'	输入字符的匹配策略
ignoreCase	boolean	true	不区分大小写进行匹配
highlight	boolean	false	将建议中的匹配字符加粗
allowSpaces	boolean	false	允许在提及搜索字符串中使用空格
requireLeadingSpace	boolean	true	要求 @ 前有空格才触发
showMentionChar	boolean	false	在插入的标签文本前添加 mentionChar
suffixText	string	null	在插入的标签后追加的文本（例如，' '）
debounceDelay	number	300	筛选前等待的毫秒数
popupHeight	string | number	'300px'	弹出列表高度
popupWidth	string | number	'auto'	弹出列表宽度

关键事件： select（选择项目时触发）、change（编辑器中的值更新时触发）、filtering（自定义筛选逻辑）、beforeOpen / opened / closed（弹出列表生命周期）。

关键方法： showPopup()、hidePopup()、search(text, x, y)、disableItem(item)、addItem(items, index?)、destroy()。

---

ListBox

Syncfusion TypeScript ListBox 组件可渲染可滚动的项目列表，供用户选择一个或多个值。与下拉列表不同，它始终可见，因此非常适合用于可用/已选项目列表、权限分配界面和偏好设置面板。它支持拖放、基于工具栏的双列表传输、筛选、分组、排序和复选框选择。

主要功能：

• 通过 selectionSettings.mode 进行单选或多选
• 通过复选框选择并支持“全选”——需要 ListBox.Inject(CheckBoxSelection)
• 通过 allowDragAndDrop + scope 在单个列表内或两个列表之间拖放并重新排序
• 使用 scope + toolbarSettings.items 实现双列表（传输列表）模式
• 通过 allowFiltering + filtering 事件添加筛选栏并实现自定义逻辑
• 使用 sortOrder: 'Ascending' | 'Descending' 对数据排序
• 使用 itemTemplate 自定义项目渲染
• 使用 enableItems() 或 fields.disabled 启用/禁用单个项目
• 完整的编程 API：addItems、removeItems、selectItems、moveTo、moveAllTo、getDataList

---

文档与导航指南

快速入门

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

• 安装：npm install @syncfusion/ej2-dropdowns
• CSS 主题导入（tailwind3、material、bootstrap5、fluent、fabric）
• HTML 设置：<div id="listbox"></div>
• 使用静态数据创建基本 ListBox
• change 事件处理程序
• 多选
• 常见设置问题的故障排除

数据绑定

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

• 简单字符串数组绑定
• 使用 fields 映射（text、value、iconCss、disabled）的对象数组
• 使用 fields.groupBy 分组
• 动态数据：addItems、dataBind
• 使用 DataManager 和 ODataV4Adaptor 获取远程数据

选择

📄 阅读： references/listbox-selection.md

• 单选（selectionSettings.mode: 'Single'）
• 多选（默认）
• 使用 value: ['id1', 'id2'] 预先选择
• 使用 maximumSelectionLength 限制选择数量
• 复选框选择：ListBox.Inject(CheckBoxSelection) + selectionSettings.showCheckbox: true
• 使用 selectionSettings.showSelectAll: true 实现“全选”
• 使用 selectItems() 和 selectAll() 以编程方式选择/取消选择
• 使用 getDataByValues() 获取已选数据

功能

📄 阅读： references/listbox-features.md

• 筛选栏：allowFiltering、filterBarPlaceholder、filterType
• 通过 filtering 事件 + args.updateData() 自定义筛选
• 使用 sortOrder: 'Ascending' | 'Descending' 排序
• 使用 scope 在单个列表内以及两个列表之间拖放
• 使用 enableItems() 或 fields.disabled 启用/禁用项目
• 固定高度并支持滚动

双列表 ListBox（传输列表）

📄 阅读： references/listbox-dual-list-box.md

• 通过 scope: '#target-id' + toolbarSettings.items 配置两个 ListBox
• 全部 6 种工具栏操作：moveUp、moveDown、moveTo、moveFrom、moveAllTo、moveAllFrom
• 仅重新排序模式、单向传输和双向传输
• 工具栏位置（Left / Right）
• 编程式传输：moveTo、moveAllTo、moveUp、moveDown、moveTop、moveBottom
• 使用 getDataList() 读取更新后的状态
• 权限分配示例

图标与模板

📄 阅读： references/listbox-icons-and-templates.md

• 通过 fields.iconCss 设置图标 CSS
• 在文本字段中使用表情符号图标
• 使用 ${} 字符串模板语法的 itemTemplate
• 包含图标和说明的模板布局
• 带状态徽标的模板
• 自定义 noRecordsTemplate

样式与外观

📄 阅读： references/listbox-style-and-appearance.md

• CSS 主题导入（tailwind3 / material / bootstrap5 / fluent / fabric）
• 覆盖 CSS 类：.e-listbox-wrapper、.e-list-item、.e-selected、.e-disabled、.e-list-group-item
• 使用 cssClass 应用范围限定的自定义样式
• 使用 itemTemplate 和 CSS 按条件设置项样式
• 响应式 height 和 width，支持 RTL

无障碍

📄 阅读： references/listbox-accessibility.md

• 符合 WCAG 2.2 AA / Section 508 / ARIA 1.2 标准
• 自动应用 ARIA 属性（role、aria-multiselectable、aria-selected）
• 通过 htmlAttributes 自定义 ARIA 属性
• 键盘快捷键表（Arrow、Space、Enter、Home、End、Shift+Arrow、Ctrl+A）
• 使用 <label> 和 aria-live 关联屏幕阅读器标签
• RTL：enableRtl: true 或全局设置 enableRtl(true)

操作指南

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

• 使用 addItems() 添加单个或多个项
• 防止重复项
• 使用 selectItems() 以编程方式选择项
• 使用 enableItems() 启用或禁用项
• 通过 filtering 事件自定义筛选逻辑
• 固定高度滚动器
• 表单集成：提交时使用 getDataByValues() 读取所选项

API 参考

📄 阅读： references/listbox-api.md

• 所有属性及其类型和默认值
• 所有方法：addItems、enableItems、filter、getDataByValue、getDataByValues、getDataList、getItems、getSortedList、moveAllTo、moveBottom、moveDown、moveTo、moveTop、moveUp、removeItem、removeItems、selectAll、selectItems
• 所有事件：change、created、dataBound、destroyed、drag、dragStart、drop、filtering、beforeDrop、beforeItemRender
• 子接口：FieldSettingsModel、SelectionSettingsModel、ToolbarSettingsModel

---

快速入门

<link href="node_modules/@syncfusion/ej2-base/styles/tailwind3.css" rel="stylesheet" />
<link href="node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css" rel="stylesheet" />
<link href="node_modules/@syncfusion/ej2-dropdowns/styles/tailwind3.css" rel="stylesheet" />

<div id="listbox"></div>

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

const data: { [key: string]: Object }[] = [
  { text: 'JavaScript', id: '1' },
  { text: 'TypeScript', id: '2' },
  { text: 'React', id: '3' },
  { text: 'Angular', id: '4' },
  { text: 'Vue', id: '5' }
];

const listBox: ListBox = new ListBox({
  dataSource: data,
  fields: { text: 'text', value: 'id' },
  change: (args) => {
    console.log('Selected values:', args.value);
  }
});

listBox.appendTo('#listbox');

使用复选框选择

import { ListBox, CheckBoxSelection } from '@syncfusion/ej2-dropdowns';

ListBox.Inject(CheckBoxSelection);  // Must be called before instantiation

const listBox: ListBox = new ListBox({
  dataSource: data,
  fields: { text: 'text', value: 'id' },
  selectionSettings: {
    showCheckbox: true,
    showSelectAll: true
  }
});

listBox.appendTo('#listbox');

双 ListBox（传输列表）

<div id="available"></div>
<div id="selected"></div>

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

const available: ListBox = new ListBox({
  dataSource: data,
  fields: { text: 'text', value: 'id' },
  scope: '#selected',
  toolbarSettings: {
    items: ['moveTo', 'moveFrom', 'moveAllTo', 'moveAllFrom']
  }
});

const selected: ListBox = new ListBox({
  dataSource: [],
  fields: { text: 'text', value: 'id' }
});

available.appendTo('#available');
selected.appendTo('#selected');

---

常见模式

模式 1：使用“全选”进行复选框选择

import { ListBox, CheckBoxSelection } from '@syncfusion/ej2-dropdowns';

ListBox.Inject(CheckBoxSelection);

const listBox: ListBox = new ListBox({
  dataSource: frameworksData,
  fields: { text: 'text', value: 'id' },
  selectionSettings: { showCheckbox: true, showSelectAll: true },
  maximumSelectionLength: 3  // Allow up to 3 checkboxes
});

listBox.appendTo('#listbox');

模式 2：筛选

const listBox: ListBox = new ListBox({
  dataSource: data,
  fields: { text: 'text', value: 'id' },
  allowFiltering: true,
  filterBarPlaceholder: 'Search frameworks...',
  filterType: 'Contains'
});

listBox.appendTo('#listbox');

模式 3：提交表单时读取所选项

document.getElementById('submitBtn')!.addEventListener('click', () => {
  const selectedValues = listBox.value as string[];
  const selectedItems = listBox.getDataByValues(selectedValues);
  console.log('Submitted:', selectedItems);
});

---

主要属性

属性	类型	默认值	用途
dataSource	array | DataManager	[]	要在列表中显示的数据
fields	FieldSettingsModel	{}	映射文本、值、图标 CSS、分组字段和禁用状态
value	string[] | number[] | boolean[]	[]	预选值或当前选中的值
selectionSettings	SelectionSettingsModel	{ mode: 'Multiple' }	选择模式和复选框选项
toolbarSettings	ToolbarSettingsModel	{ items: [] }	双 ListBox 工具栏配置
scope	string	''	用于拖放或通过工具栏传输的目标 ListBox ID
allowFiltering	boolean	false	显示筛选/搜索栏
allowDragAndDrop	boolean	false	启用拖放排序
sortOrder	SortOrder	null	对项排序：'Ascending' | 'Descending'
height	string | number	''	固定高度并允许滚动
itemTemplate	string | Function	null	自定义项渲染模板
maximumSelectionLength	number	1000	可选择项的最大数量
enableRtl	boolean	false	从右向左渲染
cssClass	string	''	用于范围限定样式的自定义 CSS 类

---

多列组合框

Syncfusion EJ2 JavaScript MultiColumnComboBox 会渲染带有多列弹出网格的组合框，使用户能够从结构化表格数据中进行选择。它支持本地和远程数据、筛选、排序、分组、模板、虚拟化，并完全符合无障碍标准。

软件包： @syncfusion/ej2-multicolumn-combobox

导航指南

入门指南

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

• 安装和包配置（npm install @syncfusion/ej2-multicolumn-combobox）
• CSS 导入和主题配置（Tailwind 3、Material、Bootstrap 5、Fluent、Fabric）
• HTML <input> 目标设置
• 使用 new MultiColumnComboBox({...}).appendTo('#id') 初始化
• 绑定 dataSource、fields 和 columns: ColumnModel[]
• 配置 popupHeight 和 popupWidth
• 最小可运行示例

列

📄 阅读： references/multicolumn-combobox-columns.md

• 使用 ColumnModel 定义列（field、header、width、textAlign）
• 使用 template 自定义单元格渲染
• 使用 displayAsCheckBox 显示布尔列
• 使用 customAttributes 自定义列 CSS
• 使用 headerTemplate 自定义列标题
• 使用 format 格式化数据（货币使用 C2，日期使用骨架格式）

数据绑定

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

• 通过 dataSource 绑定本地对象数组
• 使用 DataManager 和 WebApiAdaptor / ODataAdaptor / ODataV4Adaptor 绑定远程数据
• 映射 fields（text、value、groupBy）
• 使用 query 属性筛选或限制数据集

筛选

📄 阅读： references/multicolumn-combobox-filtering.md

• 使用 allowFiltering 启用或禁用筛选
• 使用 filterType（StartsWith、EndsWith、Contains）更改筛选模式
• 使用 filtering 事件实现自定义筛选逻辑
• 在只读场景下禁用筛选

排序

📄 阅读： references/multicolumn-combobox-sorting.md

• 使用 allowSorting 启用排序
• 使用 sortOrder（None、Ascending、Descending）设置初始排序顺序
• 使用 sortType（OneColumn、MultipleColumns）对多列排序
• 点击列标题切换排序方向

分组

📄 阅读： references/multicolumn-combobox-grouping.md

• 使用 fields.groupBy 对数据分组
• 在弹出窗口中固定分组标题
• 使用 groupTemplate 自定义分组标题（${key}、${field}、${count} 标记）

模板

📄 阅读： references/multicolumn-combobox-templates.md

• 使用 itemTemplate 自定义每一行
• 使用 headerTemplate（位于 ColumnModel 上）自定义列标题
• 使用 groupTemplate 自定义分组标题
• 使用 footerTemplate 设置弹出窗口页脚内容
• 使用 noRecordsTemplate 显示空状态
• 使用 actionFailureTemplate 显示远程获取错误状态

项目和配置

📄 阅读： references/multicolumn-combobox-items.md

• 使用 text、value、index 设置初始选中项
• 使用 placeholder 和 floatLabelType 控制输入标签行为
• 使用 showClearButton 允许清除选中项
• disabled 和 readonly 状态
• 使用 width、popupWidth、popupHeight 设置尺寸
• 使用 cssClass 自定义样式
• 使用 htmlAttributes 添加 HTML 属性
• 使用 gridSettings 配置网格线、行高和交替行
• 编程方法：addItems、focusIn、focusOut、showPopup、hidePopup、getDataByValue、getItems

虚拟化

📄 阅读： references/multicolumn-combobox-virtualization.md

• 为大型数据集启用 enableVirtualization
• 对本地和远程数据使用虚拟滚动
• 配合 gridSettings.rowHeight 使用，以实现准确定位
• 包含 100 项以上数据集的最佳实践

事件

📄 阅读： references/multicolumn-combobox-events.md

• change — 值发生变化或选中项目时触发
• select — 选中项目时触发
• open / close — 弹出窗口打开／关闭生命周期
• filtering — 输入字符时触发，用于自定义筛选
• actionBegin / actionComplete / actionFailure — 数据获取生命周期
• created — 渲染后生命周期钩子

本地化

📄 阅读： references/multicolumn-combobox-localization.md

• 使用 L10n.load() 和 'multicolumncombobox' 区域设置键本地化 noRecordsTemplate 文本
• 设置 locale 属性以按特定区域设置进行渲染
• 加载翻译对象
• BCP 47 语言标签（例如 'en-US'、'fr-BE'、'de'）

无障碍

📄 阅读： references/multicolumn-combobox-accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 属性（role="combobox"、aria-expanded、aria-selected、aria-readonly、aria-disabled、aria-owns）
• 键盘导航快捷键（Alt+Down/Alt+Up、方向键、PageUp/PageDown、Enter、Esc、Home、End）
• 支持 RTL，设置 enableRtl: true
• 支持屏幕阅读器

API 参考

📄 阅读： references/multicolumn-combobox-api.md

• 所有属性的完整列表，包含类型和默认值
• 所有事件及其参数类型
• 所有方法：addItems、focusIn、focusOut、getDataByValue、getItems、showPopup、hidePopup
• ColumnModel 属性（field、header、width、textAlign、template、headerTemplate、displayAsCheckBox、customAttributes、format）
• GridSettingsModel 属性（rowHeight、gridLines、enableAltRow）
• FieldSettingsModel 属性（text、value、groupBy）

---

快速入门

// app.ts
import { MultiColumnComboBox, ColumnModel } from '@syncfusion/ej2-multicolumn-combobox';

const empData: { [key: string]: 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'  },
  { EmpID: 1004, Name: 'Steven Buchanan',  Designation: 'Product Manager', Country: 'Ukraine' }
];

const fields: object = { text: 'Name', value: 'EmpID' };

const columns: ColumnModel[] = [
  { field: 'EmpID',       header: 'Employee ID', width: 120 },
  { field: 'Name',        header: 'Name',        width: 120 },
  { field: 'Designation', header: 'Designation', width: 120 },
  { field: 'Country',     header: 'Country',     width: 100 }
];

const mccBox: MultiColumnComboBox = new MultiColumnComboBox({
  dataSource: empData,
  fields: fields,
  columns: columns,
  placeholder: 'Select an employee'
});

mccBox.appendTo('#multicolumn');

<input type="text" id="multicolumn" />

/* styles.css */
@import '~@syncfusion/ej2-base/styles/tailwind3.css';
@import '~@syncfusion/ej2-inputs/styles/tailwind3.css';
@import '~@syncfusion/ej2-grids/styles/tailwind3.css';
@import '~@syncfusion/ej2-popups/styles/tailwind3.css';
@import '~@syncfusion/ej2-multicolumn-combobox/styles/tailwind3.css';

---

常见模式

按文本预选项目

const mccBox: MultiColumnComboBox = new MultiColumnComboBox({
  dataSource: empData,
  fields: fields,
  text: 'Michael',
  columns: columns
});
mccBox.appendTo('#multicolumn');

启用 Contains 模式筛选

const mccBox: MultiColumnComboBox = new MultiColumnComboBox({
  dataSource: empData,
  fields: fields,
  allowFiltering: true,
  filterType: 'Contains',
  columns: columns
});
mccBox.appendTo('#multicolumn');

启用降序排序并支持多列

import { MultiColumnComboBox, SortOrder, ColumnModel } from '@syncfusion/ej2-multicolumn-combobox';

const mccBox: MultiColumnComboBox = new MultiColumnComboBox({
  dataSource: empData,
  fields: fields,
  allowSorting: true,
  sortOrder: SortOrder.Descending,
  sortType: 'MultipleColumns',
  columns: columns
});
mccBox.appendTo('#multicolumn');

使用 OData v4 绑定远程数据（安全优先）

安全： 请勿在客户端代码中调用任意第三方端点。应通过可信的服务端代理路由外部 API 请求，由其验证、认证并清理响应。

import { MultiColumnComboBox, ColumnModel } from '@syncfusion/ej2-multicolumn-combobox';
import { DataManager, ODataV4Adaptor } from '@syncfusion/ej2-data';

// Use a trusted server-side proxy. Do not embed third-party URLs directly.
const dataSource: DataManager = new DataManager({
  url: 'https://your-trusted-proxy.example/api/customers',
  adaptor: new ODataV4Adaptor(),
  crossDomain: true
});

const fields: object = { text: 'FirstName', value: 'EmployeeID' };

const columns: ColumnModel[] = [
  { field: 'EmployeeID',  header: 'Employee ID', width: 120 },
  { field: 'FirstName',   header: 'Name',        width: 130 },
  { field: 'Designation', header: 'Designation', width: 120 },
  { field: 'Country',     header: 'Country',     width: 90  }
];

const mccBox: MultiColumnComboBox = new MultiColumnComboBox({
  dataSource: dataSource,
  fields: fields,
  placeholder: 'Select a name',
  popupHeight: '230px',
  columns: columns
});
mccBox.appendTo('#multicolumn');

处理值变化事件

import { MultiColumnComboBox, ChangeEventArgs } from '@syncfusion/ej2-multicolumn-combobox';

const mccBox: MultiColumnComboBox = new MultiColumnComboBox({
  dataSource: empData,
  fields: fields,
  columns: columns,
  change: (args: ChangeEventArgs) => {
    console.log('Selected value:', args.value);
    console.log('Display text:', args.text);
    console.log('Item data:', args.itemData);
  }
});
mccBox.appendTo('#multicolumn');

---

主要属性

属性	类型	默认值	用途
dataSource	Object[] | DataManager	[]	用于填充弹出网格的数据
fields	FieldSettingsModel	{text:null, value:null, groupBy:null}	将数据键映射为显示文本、隐藏值和分组字段
columns	ColumnModel[]	[]	弹出网格的列定义
value	string	null	按值预选项目
text	string	null	按显示文本预选项目
index	number	null	按从零开始的索引预选项目
placeholder	string	null	输入框的提示文本
floatLabelType	'Never' | 'Always' | 'Auto'	'Never'	浮动标签行为
allowFiltering	boolean	true	启用筛选输入框
filterType	'StartsWith' | 'EndsWith' | 'Contains'	'StartsWith'	筛选匹配策略
allowSorting	boolean	true	启用列标题排序
sortOrder	SortOrder	SortOrder.None	初始排序方向
sortType	SortType	'OneColumn'	单列或多列排序
enableVirtualization	boolean	false	为大型数据集启用虚拟滚动
enableRtl	boolean	false	启用从右到左渲染
enablePersistence	boolean	false	在页面重新加载后保留 value
readonly	boolean	false	禁止用户输入
disabled	boolean	false	完全禁用组件
showClearButton	boolean	false	显示清除（×）按钮
cssClass	string	''	根元素上的自定义 CSS 类
popupHeight	string | number	'300px'	弹出窗口的高度
popupWidth	string | number	'100%'	弹出窗口的宽度
width	string | number	'100%'	输入元素的宽度
gridSettings	GridSettingsModel	{rowHeight:null, gridLines:'Default', enableAltRow:false}	弹出网格的外观
query	Query	null	远程数据查询
htmlAttributes	{ [key: string]: string }	{}	输入框上的 HTML 属性
locale	string	''	区域设置代码（例如 'fr-BE'）
itemTemplate	string | Function	null	自定义行模板
groupTemplate	string | Function	null	自定义分组标题模板
footerTemplate	string | Function	null	自定义页脚模板
noRecordsTemplate	string | Function	'No records found'	空状态模板
actionFailureTemplate	string | Function	'Request failed'	远程错误模板