syncfusion-angular-dropdownlist（syncfusion Angular dropdownlist 搜索）

Syncfusion Angular DropDownList

The DropDownList component allows users to select a single value from a predefined list. It supports local and remote data sources, filtering, grouping, custom templates, virtualization for large datasets, and full Angular forms integration.

Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and Angular CLI setup
• Installing @syncfusion/ej2-angular-dropdowns
• CSS/theme imports for Material3
• Adding <ejs-dropdownlist> to the template
• Basic data binding with [dataSource]
• Popup height/width configuration
• Two-way binding with [(value)]

Data Binding

📄 Read: references/data-binding.md

• Binding primitive arrays (strings, numbers)
• Binding arrays of objects with [fields] mapping
• Binding to nested/complex objects
• Remote data via DataManager (OData, Web API)
• Async pipe with Observable data streams
• Value binding (primitive and object types with allowObjectBinding)

Filtering

📄 Read: references/filtering.md

• Enabling search with [allowFiltering]
• Using the filtering event and updateData() method
• Minimum character threshold before filtering starts
• Filter types: contains, startsWith, endsWith
• Case-sensitive filtering
• Diacritics/accent-insensitive filtering
• Debounce delay for performance optimization

Templates

📄 Read: references/templates.md

• Item template: customize each list item
• Value template: customize the selected value display
• Group template: customize group header appearance
• Header template: static element at popup top
• Footer template: static element at popup bottom
• No-records template: empty state display
• Action failure template: error state display

Grouping & Virtualization

📄 Read: references/grouping-and-virtualization.md

• Grouping items with groupBy field
• Inline and fixed floating group headers
• Virtual scrolling with [enableVirtualization] for large lists
• Virtual scrolling with remote data
• Combining filtering and virtualization
• Customizing item count in virtual mode

Disabled Items & Forms

📄 Read: references/disabled-items-and-forms.md

• Disabling specific items via fields.disabled
• Dynamic disableItem() method (by value, index, or element)
• Disabling the entire component with [enabled]="false"
• Template-driven forms with [(ngModel)]
• Reactive forms with FormControl and FormGroup

Customization & Styling

📄 Read: references/customization-and-styling.md

• CSS overrides for wrapper, icon, focus states
• Outline theme focus customization
• Popup appearance and list item styles
• Float label and placeholder styling
• Mandatory asterisk pattern
• Localization with L10n class
• RTL (right-to-left) support

How-To Recipes

📄 Read: references/how-to.md

• Add / remove / clear items dynamically
• Close popup programmatically
• Cascading DropDownLists
• Customize group header template
• Highlight filtered characters
• Incremental search behavior
• Modify remote data results
• Remote data item count display
• Tooltip on list items
• Value change event handling
• Icon support in list items

API Reference

📄 Read: references/api.md

• Complete properties reference with types, defaults, and usage examples
• All methods with signatures, parameters, and return types
• All events with argument interfaces and usage examples
• Interface details: FieldSettingsModel, ChangeEventArgs, SelectEventArgs, PopupEventArgs, FilteringEventArgs
• Quick-reference summary tables for properties, methods, and events

Quick Start Example

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

Common Patterns

Searchable Dropdown

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

Remote Data Dropdown

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

public remoteData: DataManager = new DataManager({
  url: 'https://your-api-endpoint.com/Customers', // replace with your own OData or Web API URL
  adaptor: new ODataV4Adaptor(),
  crossDomain: true
});
public remoteQuery = new Query().select(['CustomerID', 'ContactName']).take(6);
public remoteFields = { text: 'ContactName', value: 'CustomerID' };
// Template: <ejs-dropdownlist [dataSource]="remoteData" [query]="remoteQuery" [fields]="remoteFields">

Reactive Form Integration

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>

Key Props

Common Use Cases

Form field with validation → See references/disabled-items-and-forms.md

Large list (1000+ items) → Enable [enableVirtualization]="true" — see references/grouping-and-virtualization.md

Country/State/City cascading → See references/how-to.md

Custom item rendering (icons, multi-column) → See references/templates.md

Remote API data → See references/data-binding.md