syncfusion-angular-dropdownlist

用途

Syncfusion Angular DropDownList 组件允许用户从预定义列表中选取单个值。它适用于需要在 Angular 应用中提供下拉选择器的场景，支持本地与远程数据源、筛选、分组、自定义模板、大数据集虚拟化，以及与 Angular 表单的完整集成。

主要能力

数据绑定

• 绑定原始类型数组（字符串、数字）
• 通过 [fields] 映射绑定对象数组
• 绑定嵌套/复杂对象
• 通过 DataManager 绑定远程数据（OData、Web API）
• 使用异步管道绑定 Observable 数据流
• 值绑定（原始类型与对象类型，配合 allowObjectBinding）

筛选

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

模板

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

分组与虚拟化

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

禁用项与表单

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

自定义与样式

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

使用方式

快速开始示例

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

安装涉及 @syncfusion/ej2-angular-dropdowns 包，并导入 Material3 的 CSS/主题，同时将 <ejs-dropdownlist> 添加到模板。

常见模式

可搜索下拉：

// 在模板中启用筛选
// <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);
}

远程数据下拉：

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

public remoteData: DataManager = new DataManager({
  url: 'https://your-api-endpoint.com/Customers', // 替换为你自己的 OData 或 Web API URL
  adaptor: new ODataV4Adaptor(),
  crossDomain: true
});
public remoteQuery = new Query().select(['CustomerID', 'ContactName']).take(6);
public remoteFields = { text: 'ContactName', value: 'CustomerID' };
// 模板：<ejs-dropdownlist [dataSource]="remoteData" [query]="remoteQuery" [fields]="remoteFields">

响应式表单集成：

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

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

关键属性

属性	类型	说明
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/disabled-items-and-forms.md
• 大型列表（1000+ 项） → 启用 [enableVirtualization]="true" → 参见 references/grouping-and-virtualization.md
• 国家/州/城市级联 → 参见 references/how-to.md
• 自定义项渲染（图标、多列） → 参见 references/templates.md
• 远程 API 数据 → 参见 references/data-binding.md

导航指南

• 入门 → references/getting-started.md（安装与 Angular CLI 配置）
• 数据绑定 → references/data-binding.md
• 筛选 → references/filtering.md
• 模板 → references/templates.md
• 分组与虚拟化 → references/grouping-and-virtualization.md
• 禁用项与表单 → references/disabled-items-and-forms.md
• 自定义与样式 → references/customization-and-styling.md
• 操作指南 → references/how-to.md（动态增删/清空项、以编程方式关闭弹窗、级联 DropDownList、自定义分组标题模板、高亮筛选字符、增量搜索行为、修改远程数据结果、远程数据项数显示、列表项工具提示、值变更事件处理、列表项图标支持）
• API 参考 → references/api.md（完整属性参考、方法签名、事件与参数接口：FieldSettingsModel、ChangeEventArgs、SelectEventArgs、PopupEventArgs、FilteringEventArgs，以及属性/方法/事件速查表）

限制

资料未提供关于价格、授权方式、浏览器兼容性范围或性能基准的具体说明。