syncfusion-angular-drop-down-list

用途

Syncfusion Angular DropDownList 组件用于让用户从预定义列表中选取单个值。它适用于构建下拉选择器，支持本地和远程数据源，并可与 Angular 表单体系配合使用。

主要能力

• 数据绑定：支持绑定原始类型数组（字符串、数字）、通过 [fields] 映射的对象数组、嵌套/复杂对象；支持通过 DataManager 绑定远程数据（OData、Web API）；支持 Observable 数据流配合 async 管道；支持原始类型和对象类型的值绑定（allowObjectBinding）。
• 筛选：通过 [allowFiltering] 启用搜索框；支持 filtering 事件与 updateData() 方法；可设置最小字符阈值、筛选类型（contains、startsWith、endsWith）、大小写敏感、变音符号不敏感筛选，以及 debounceDelay 延迟优化性能。
• 模板：提供 itemTemplate（列表项）、valueTemplate（选中值显示）、groupTemplate（分组头）、headerTemplate（弹窗顶部静态元素）、footerTemplate（弹窗底部静态元素）、noRecordsTemplate（空状态）、actionFailureTemplate（错误状态）。
• 分组与虚拟化：通过 groupBy 字段分组，支持内联和固定浮动分组头；通过 [enableVirtualization] 为大数据集启用虚拟滚动，支持远程数据虚拟滚动，可与筛选组合使用，并可自定义虚拟模式下的项数。
• 禁用项与表单：可通过 fields.disabled 禁用特定项，使用 disableItem() 方法按值、索引或元素动态禁用；通过 [enabled]="false" 禁用整个组件；支持模板驱动表单（[(ngModel)]）和响应式表单（FormControl、FormGroup）。
• 自定义与样式：支持 CSS 覆盖（wrapper、图标、焦点状态）、Outline 主题焦点自定义、弹窗外观与列表项样式、浮动标签与占位符样式、必填星号模式、通过 L10n 类本地化、RTL（从右到左）支持。

使用方式

安装 @syncfusion/ej2-angular-dropdowns 包，导入 Material3 等主题的 CSS，在模板中添加 <ejs-dropdownlist> 标签，并通过 [dataSource]、[fields]、[(value)] 等属性进行绑定。

快速开始示例：

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

可搜索下拉列表示例：

// 模板中启用筛选
// <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://services.odata.org/V4/Northwind/Northwind.svc/Customers',
  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	空状态消息

适用场景

• 带验证的表单字段
• 大数据集（1000+ 项）——启用 [enableVirtualization]="true"
• 国家/州/城市级联选择
• 自定义项渲染（图标、多列）
• 远程 API 数据

限制

资料中未提供关于收费、价格、平台兼容性、性能指标或具体使用步骤的更多信息。