Back to Details

syncfusion-angular-list-box

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Angular ListBox

实现Syncfusion Angular ListBox

The ListBox component enables users to select one or more items from a predefined list with support for data binding, templates, drag-and-drop, sorting, grouping, and comprehensive accessibility features.
ListBox组件支持用户从预定义列表中选择一个或多个条目，具备数据绑定、模板、拖拽、排序、分组以及全面的无障碍特性。

Component Overview

组件概览

The Syncfusion ListBox is a high-performance dropdown list replacement with advanced features:
FeatureBenefit
Multiple Selection ModesSingle, multiple, or checkbox selection
Data BindingLocal arrays, complex objects, or remote services
Drag & DropReorder items or transfer between lists
CustomizationIcons, templates, grouping, sorting
AccessibilityWCAG 2.2, screen readers, keyboard navigation
PerformanceEfficient rendering with large datasets
Syncfusion ListBox是高性能下拉列表替代组件，具备以下高级特性：
特性优势
多种选择模式支持单选、多选或复选框选择
数据绑定支持本地数组、复杂对象或远程服务
拖拽功能可重排列表项或在列表间转移条目
自定义能力支持图标、模板、分组、排序
无障碍适配符合WCAG 2.2标准，支持屏幕阅读器、键盘导航
性能表现可高效渲染大规模数据集

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and package setup
  • Angular standalone vs NgModule patterns
  • Basic component initialization
  • CSS imports and theme selection
  • Binding local data sources
  • Running and testing the application
📄 阅读： references/getting-started.md
  • 安装与包配置
  • Angular standalone与NgModule模式
  • 基础组件初始化
  • CSS导入与主题选择
  • 绑定本地数据源
  • 运行与测试应用

Selection Modes and Interactions

选择模式与交互

📄 Read: references/selection-modes.md
  • Single item selection
  • Multiple item selection with SHIFT/CTRL
  • Checkbox selection mode
  • Select all functionality
  • Handling change events
  • Getting selected items programmatically
📄 阅读： references/selection-modes.md
  • 单条目选择
  • 配合SHIFT/CTRL的多条目选择
  • 复选框选择模式
  • 全选功能
  • 变更事件处理
  • 编程式获取选中条目

Data Binding and Field Mapping

数据绑定与字段映射

📄 Read: references/data-binding.md
  • Binding array of strings
  • Binding array of objects
  • Binding complex nested objects
  • Remote data with DataManager and Query
  • Field mapping (text, value, groupBy, iconCss)
  • Troubleshooting data binding issues
📄 阅读： references/data-binding.md
  • 绑定字符串数组
  • 绑定对象数组
  • 绑定复杂嵌套对象
  • 通过DataManager和Query绑定远程数据
  • 字段映射（text、value、groupBy、iconCss）
  • 数据绑定问题排查

Drag-and-Drop Features

拖拽功能

📄 Read: references/drag-and-drop-features.md
  • Single ListBox drag-and-drop reordering
  • Dual ListBox drag-and-drop transfer
  • Drag and drop events (dragStart, drag, drop)
  • Scope configuration for multiple lists
  • Event handling and item manipulation
  • Real-world dual ListBox patterns
📄 阅读： references/drag-and-drop-features.md
  • 单ListBox内拖拽重排序
  • 双ListBox间拖拽转移条目
  • 拖拽事件（dragStart、drag、drop）
  • 多列表拖拽的作用域配置
  • 事件处理与条目操作
  • 实际场景中的双ListBox模式

Customization and Styling

自定义与样式

📄 Read: references/customization.md
  • Icons and iconCss field mapping
  • Custom item templates
  • Grouping items by category
  • Sorting items (ascending/descending)
  • CSS styling and theming
  • Theme Studio integration
  • Responsive design
📄 阅读： references/customization.md
  • 图标与iconCss字段映射
  • 自定义条目模板
  • 按类别分组条目
  • 条目排序（升序/降序）
  • CSS样式与主题定制
  • Theme Studio集成
  • 响应式设计

Practical Implementation Examples

实际实现示例

📄 Read: references/practical-examples.md
  • Filtering ListBox items
  • Form submission with selected items
  • Enable/disable items conditionally
  • Scroller for large datasets
  • Real-world use cases
  • Common troubleshooting scenarios
📄 阅读： references/practical-examples.md
  • 筛选ListBox条目
  • 选中条目表单提交
  • 条件启用/禁用条目
  • 大规模数据集的滚动器适配
  • 实际使用场景
  • 常见问题排查

How-To Guides and Common Tasks

操作指南与常见任务

📄 Read: references/how-to-guides.md
  • Add items programmatically
  • Select items programmatically
  • Enable or disable items dynamically
  • Enable scroller for large datasets
  • Filter ListBox data with input
  • Submit selected items in forms
📄 阅读： references/how-to-guides.md
  • 编程式添加条目
  • 编程式选中条目
  • 动态启用或禁用条目
  • 为大规模数据集开启滚动器
  • 通过输入框筛选ListBox数据
  • 提交表单中的选中条目

API Reference

API参考

📄 Read: references/api.md
  • All component properties with types, defaults, and examples
  • All public methods with parameter signatures and usage examples
  • All events with event argument interfaces and handler patterns
  • Interface definitions: 
    FieldSettingsModel
    , 
    SelectionSettingsModel
    , 
    ToolbarSettingsModel
  • Event arg interfaces: 
    ListBoxChangeEventArgs
    , 
    DragEventArgs
    , 
    DropEventArgs
    , 
    BeforeItemRenderEventArgs
    , 
    FilteringEventArgs
    , 
    SourceDestinationModel
  • Enum definitions: 
    SelectionMode
    , 
    SortOrder
    , 
    FilterType
    , 
    ToolBarPosition
    , 
    CheckBoxPosition
📄 阅读： references/api.md
  • 所有组件属性，含类型、默认值与示例
  • 所有公开方法，含参数签名与使用示例
  • 所有事件，含事件参数接口与处理模式
  • 接口定义：
    FieldSettingsModel
    、
    SelectionSettingsModel
    、
    ToolbarSettingsModel
  • 事件参数接口：
    ListBoxChangeEventArgs
    、
    DragEventArgs
    、
    DropEventArgs
    、
    BeforeItemRenderEventArgs
    、
    FilteringEventArgs
    、
    SourceDestinationModel
  • 枚举定义：
    SelectionMode
    、
    SortOrder
    、
    FilterType
    、
    ToolBarPosition
    、
    CheckBoxPosition

Quick Start Example

快速入门示例

Basic ListBox with Local Data

使用本地数据的基础ListBox

typescript
import { Component, OnInit } from '@angular/core';
import { ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  imports: [ListBoxModule],
  standalone: true,
  selector: 'app-listbox',
  template: `
    <ejs-listbox 
      [dataSource]="items"
      [selectionSettings]="{ mode: 'Multiple' }">
    </ejs-listbox>
  `
})
export class ListBoxComponent implements OnInit {
  public items: { [key: string]: Object }[] = [];

  ngOnInit(): void {
    this.items = [
      { text: 'Option 1', id: '1' },
      { text: 'Option 2', id: '2' },
      { text: 'Option 3', id: '3' }
    ];
  }
}
typescript
import { Component, OnInit } from '@angular/core';
import { ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  imports: [ListBoxModule],
  standalone: true,
  selector: 'app-listbox',
  template: `
    <ejs-listbox 
      [dataSource]="items"
      [selectionSettings]="{ mode: 'Multiple' }">
    </ejs-listbox>
  `
})
export class ListBoxComponent implements OnInit {
  public items: { [key: string]: Object }[] = [];

  ngOnInit(): void {
    this.items = [
      { text: 'Option 1', id: '1' },
      { text: 'Option 2', id: '2' },
      { text: 'Option 3', id: '3' }
    ];
  }
}

With Styles

样式配置

css
/* In your global styles.css */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-dropdowns/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';
@import '@syncfusion/ej2-lists/styles/material3.css';
css
/* In your global styles.css */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-dropdowns/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';
@import '@syncfusion/ej2-lists/styles/material3.css';

Common Patterns

常用模式

Selection with Change Event

带变更事件的选择功能

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

selectedValues: string[] = [];

onSelectionChange(args: ListBoxChangeEventArgs): void {
  this.selectedValues = args.value as string[];
  console.log('Selected values:', args.value);
  console.log('Selected items:', args.items);
}
Template:
html
<ejs-listbox
  [dataSource]="items"
  (change)="onSelectionChange($event)">
</ejs-listbox>
typescript
import { ListBoxChangeEventArgs } from '@syncfusion/ej2-dropdowns';

selectedValues: string[] = [];

onSelectionChange(args: ListBoxChangeEventArgs): void {
  this.selectedValues = args.value as string[];
  console.log('Selected values:', args.value);
  console.log('Selected items:', args.items);
}
模板：
html
<ejs-listbox
  [dataSource]="items"
  (change)="onSelectionChange($event)">
</ejs-listbox>

Dual ListBox for Transfer

用于条目转移的双ListBox

typescript
sourceItems = [
  { text: 'Available Item 1', id: '1' },
  { text: 'Available Item 2', id: '2' }
];

selectedItems = [];
Template:
html
<div style="display: flex; gap: 20px;">
  <div>
    <h4>Available Items</h4>
    <ejs-listbox
      [dataSource]="sourceItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
  
  <div>
    <h4>Selected Items</h4>
    <ejs-listbox
      [dataSource]="selectedItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
</div>
typescript
sourceItems = [
  { text: 'Available Item 1', id: '1' },
  { text: 'Available Item 2', id: '2' }
];

selectedItems = [];
模板：
html
<div style="display: flex; gap: 20px;">
  <div>
    <h4>Available Items</h4>
    <ejs-listbox
      [dataSource]="sourceItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
  
  <div>
    <h4>Selected Items</h4>
    <ejs-listbox
      [dataSource]="selectedItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
</div>

Filtered ListBox

带筛选功能的ListBox

typescript
allItems = [
  { text: 'Apple', category: 'Fruit' },
  { text: 'Carrot', category: 'Vegetable' },
  { text: 'Banana', category: 'Fruit' }
];

get filteredItems() {
  return this.allItems.filter(item => 
    item.text.toLowerCase().includes(this.searchTerm.toLowerCase())
  );
}
typescript
allItems = [
  { text: 'Apple', category: 'Fruit' },
  { text: 'Carrot', category: 'Vegetable' },
  { text: 'Banana', category: 'Fruit' }
];

get filteredItems() {
  return this.allItems.filter(item => 
    item.text.toLowerCase().includes(this.searchTerm.toLowerCase())
  );
}

Key Props

核心属性

Selection Configuration

选择配置

  • selectionSettings
    : 
    { mode: 'Single' | 'Multiple', showCheckbox: boolean, showSelectAll: boolean, checkboxPosition: 'Left' | 'Right' }
    > Note: When using 
    showCheckbox: true
    , you must inject 
    CheckBoxSelection
    :
    typescript
    import { ListBoxComponent, CheckBoxSelection, ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';
ListBoxComponent.Inject(CheckBoxSelection);
@Component({ imports: [ListBoxModule] })
```- **`maximumSelectionLength`**: Limit how many items can be selected
  • value
    : Get or set selected values (
    string[] | number[] | boolean[]
    )
  • selectionSettings
    : 
    { mode: 'Single' | 'Multiple', showCheckbox: boolean, showSelectAll: boolean, checkboxPosition: 'Left' | 'Right' }
    > 注意： 当使用
    showCheckbox: true
    时，必须注入
    CheckBoxSelection
    ：
    typescript
    import { ListBoxComponent, CheckBoxSelection, ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';
ListBoxComponent.Inject(CheckBoxSelection);
@Component({ imports: [ListBoxModule] })
```- **`maximumSelectionLength`**: 限制可选中的条目上限
  • value
    : 获取或设置选中值（
    string[] | number[] | boolean[]
    ）

Data and Display

数据与展示

  • dataSource
    : Array or DataManager with items
  • fields
    : 
    { text, value, groupBy, iconCss, disabled, htmlAttributes }
  • itemTemplate
    : Template for rendering each list item
  • noRecordsTemplate
    : Template shown when no items match
  • dataSource
    : 存放条目的数组或DataManager
  • fields
    : 
    { text, value, groupBy, iconCss, disabled, htmlAttributes }
  • itemTemplate
    : 列表条目渲染模板
  • noRecordsTemplate
    : 无匹配条目时展示的模板

Interactions

交互配置

  • allowDragAndDrop
    : Enable drag-and-drop reordering/transfer
  • scope
    : Identify related ListBoxes for drag-drop transfer
  • allowFiltering
    : Show built-in filter search bar
  • filterBarPlaceholder
    : Placeholder text for the filter bar
  • filterType
    : 
    'StartsWith' | 'EndsWith' | 'Contains'
  • toolbarSettings
    : Configure toolbar buttons for dual-ListBox transfer
  • allowDragAndDrop
    : 启用拖拽重排序/条目转移功能
  • scope
    : 标记可互相拖拽转移的关联ListBox
  • allowFiltering
    : 展示内置的筛选搜索栏
  • filterBarPlaceholder
    : 筛选栏的占位文本
  • filterType
    : 
    'StartsWith' | 'EndsWith' | 'Contains'
  • toolbarSettings
    : 为双ListBox转移场景配置工具栏按钮

Appearance

外观配置

  • height
    : Height of the ListBox
  • sortOrder
    : 
    'None' | 'Ascending' | 'Descending'
  • enabled
    : Enable/disable component
  • enableRtl
    : Right-to-left rendering
  • cssClass
    : Additional CSS class
  • height
    : ListBox的高度
  • sortOrder
    : 
    'None' | 'Ascending' | 'Descending'
  • enabled
    : 启用/禁用组件
  • enableRtl
    : 从右到左渲染
  • cssClass
    : 额外的CSS类名

Next Steps

后续步骤

  1. Get Started: Read references/getting-started.md for setup instructions
  2. Choose Selection Mode: Review references/selection-modes.md for your use case
  3. Bind Data: See references/data-binding.md for data source options
  4. Add Interactions: Explore references/drag-and-drop-features.md for advanced features
  5. Customize: Check references/customization.md for styling options
  6. See Examples: Review references/practical-examples.md for real-world implementations
  7. API Reference: Consult references/api.md for the complete properties, methods, events, and interface definitions
  1. 入门使用：阅读references/getting-started.md获取配置说明
  2. 选择适配模式：参考references/selection-modes.md匹配你的使用场景
  3. 数据绑定：查看references/data-binding.md了解数据源选项
  4. 添加交互能力：探索references/drag-and-drop-features.md获取高级功能
  5. 自定义配置：查阅references/customization.md了解样式配置选项
  6. 查看示例：参考references/practical-examples.md了解实际场景实现
  7. API参考：查阅references/api.md获取完整的属性、方法、事件与接口定义

Common Use Cases

常见使用场景

  • Selection Forms: Multi-select dropdown replacement
  • Transfer Lists: Move items between lists (dual ListBox)
  • Categories: Group-based item organization
  • Filtering: Filter large datasets
  • Data Display: Show structured list data
  • Accessibility: Compliant selection interfaces
  • 选择表单：多选下拉列表替代方案
  • 转移列表：在列表间移动条目（双ListBox）
  • 分类管理：基于分组的条目组织
  • 筛选场景：大规模数据集筛选
  • 数据展示：展示结构化列表数据
  • 无障碍适配：符合合规要求的选择界面