syncfusion-angular-multi-select

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing the Syncfusion Angular MultiSelect Dropdown

实现Syncfusion Angular多选下拉组件

The MultiSelect Dropdown (

ejs-multiselect

) allows users to select one or more values from a predefined list. It supports four visual modes (Default/Box/Delimiter/CheckBox), rich filtering, templates, grouping, remote data, virtualization, and full Angular form integration.

多选下拉组件（

ejs-multiselect

）允许用户从预定义列表中选择一个或多个值。它支持四种展示模式（默认/Box/分隔符/CheckBox）、丰富的过滤能力、模板、分组、远程数据、虚拟化，以及完整的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`	选中项以Chip的形式展示在输入框中	标准多选场景
`Box`	与默认模式一致，有明确的框体展示	需要更高视觉清晰度的场景
`Delimiter`	选中项以逗号分隔的文本展示	空间受限的布局
`CheckBox`	弹出层中每个选项都带复选框	批量选择的工作流

Navigation Guide

导航指南

Getting Started

入门

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

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

Data Binding & Value Binding

数据绑定与值绑定

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

本地数组（字符串、数字、对象）
```
fields
```
映射：
```
text
```
、
```
value
```
、
```
groupBy
```
、
```
iconCss
```
、
```
disabled
```
基于DataManager的远程数据（OData、Web API）
编程式预选中值
配合
```
allowObjectBinding
```
的对象绑定

Selection Modes, Chips & Item Control

选择模式、Chip与选项控制

📄 Read: references/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/selection-modes.md

```
mode
```
属性：默认 / Box / 分隔符 / CheckBox

复选框模式：

CheckBoxSelection

、

showSelectAll

、

maximumSelectionLength

通过
```
tagging
```
事件自定义Chip
配合
```
allowCustomValue
```
使用自定义值
禁用指定选项：
```
fields.disabled
```
、
```
disableItem()
```
```
addTagOnBlur
```
与
```
changeOnBlur
```
行为

Filtering

过滤

📄 Read: references/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/filtering.md

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

Templates

模板

📄 Read: references/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/templates.md

```
itemTemplate
```
— 通过
```
ng-template
```
自定义列表项渲染
```
valueTemplate
```
— 自定义Chip/选中值的展示
```
groupTemplate
```
— 自定义分组头部内容
```
headerTemplate
```
/
```
footerTemplate
```
— 弹出层顶部/底部
```
noRecordsTemplate
```
/
```
actionFailureTemplate
```

Grouping & Cascading

分组与级联

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

```
fields.groupBy
```
— 将选项归类到不同分类下
固定与行内分组头部
分组级全选功能
```
enableGroupCheckBox
```
级联多选：父组件
```
change
```
事件 → 过滤子组件数据
国家→省份→城市级联模式

Form Integration

表单集成

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

模板驱动表单：
```
FormsModule
```
、
```
ngModel
```
、双向绑定
响应式表单：
```
ReactiveFormsModule
```
、
```
FormGroup
```
、
```
FormControl
```
```
formControlName
```
使用与验证
必填字段与自定义校验规则

Advanced Features

高级功能

📄 Read: references/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/advanced-features.md

大数据集虚拟化（
```
enableVirtualization
```
）
弹出层可调整大小（
```
allowResize
```
、resize事件）
列表项图标（
```
iconCss
```
字段）
国际化（
```
L10n.load()
```
、locale键覆写）
无障碍支持：WAI-ARIA、键盘导航、WCAG 2.2
RTL支持

API Reference

API参考

📄 Read: references/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/api.md

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

Quick Start

快速开始

bash

ng add @syncfusion/ej2-angular-dropdowns

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 {
    console.log('Selected IDs:', args.value);
  }
}

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

bash

ng add @syncfusion/ej2-angular-dropdowns

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="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]; // 预选中Angular与TypeScript

  onChange(args: any): void {
    console.log('Selected IDs:', args.value);
  }
}

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="Select All"
      unSelectAllText="Unselect All"
      [maximumSelectionLength]="5">
    </ejs-multiselect>
  `
})

Filtering with Remote Data

远程数据过滤

typescript

template: `
  <ejs-multiselect
    [dataSource]="data"
    [allowFiltering]="true"
    filterType="contains"
    (filtering)="onFilter($event)">
  </ejs-multiselect>
`

onFilter(args: FilteringEventArgs): void {
  const query = new Query().where('name', 'contains', args.text, true);
  args.updateData(this.data, query);
}

typescript

template: `
  <ejs-multiselect
    [dataSource]="data"
    [allowFiltering]="true"
    filterType="contains"
    (filtering)="onFilter($event)">
  </ejs-multiselect>
`

onFilter(args: FilteringEventArgs): void {
  const query = new Query().where('name', 'contains', args.text, true);
  args.updateData(this.data, query);
}

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`	输入框提示文本