syncfusion-angular-list-box

用途

Syncfusion Angular ListBox 组件用于让用户从预定义列表中选中一个或多个项目，适用于构建交互式列表界面。它可作为下拉列表的替代方案，支持数据绑定、模板、拖放、排序、分组以及较完整的无障碍特性。

主要能力

多种选择模式：支持单选、多选（配合 SHIFT/CTRL）以及复选框选择，并提供全选功能。
数据绑定：可绑定本地字符串数组、对象数组、复杂嵌套对象，或通过 DataManager 与 Query 绑定远程数据；支持字段映射（text、value、groupBy、iconCss 等）。
拖放：支持单个 ListBox 内拖放重排，也支持双 ListBox 之间拖放转移；提供 dragStart、drag、drop 等事件，并可通过 scope 配置关联多个列表。
自定义与样式：支持图标与 iconCss 字段映射、自定义项目模板、按类别分组、升序/降序排序、CSS 样式与主题定制、Theme Studio 集成以及响应式设计。
过滤与大数据集：支持内置过滤搜索栏、过滤类型（StartsWith、EndsWith、Contains），并可为大数据集启用滚动条。
无障碍：符合 WCAG 2.2，支持屏幕阅读器和键盘导航。
性能：针对大数据集进行高效渲染。

使用方式

安装并引入 @syncfusion/ej2-angular-dropdowns 中的 ListBoxModule，在组件模板中使用 <ejs-listbox> 标签，通过 [dataSource] 绑定数据，通过 [selectionSettings] 配置选择模式。样式需在全局样式文件中导入相关主题 CSS，例如 material3 主题下的 base、dropdowns、inputs、lists 样式。

基本示例：

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

样式导入：

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

选择变更事件示例：

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

<ejs-listbox
  [dataSource]="items"
  (change)="onSelectionChange($event)">
</ejs-listbox>

双列表转移示例：

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

selectedItems = [];

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

过滤示例：

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

关键属性：

selectionSettings：{ mode: 'Single' | 'Multiple', showCheckbox: boolean, showSelectAll: boolean, checkboxPosition: 'Left' | 'Right' }。注意：使用 showCheckbox: true 时必须注入 CheckBoxSelection：

import { ListBoxComponent, CheckBoxSelection, ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';
ListBoxComponent.Inject(CheckBoxSelection);
@Component({ imports: [ListBoxModule] })

maximumSelectionLength：限制最多可选项目数。
value：获取或设置选中值（string[] | number[] | boolean[]）。
dataSource：数组或带项目的 DataManager。
fields：{ text, value, groupBy, iconCss, disabled, htmlAttributes }。
itemTemplate：渲染每个列表项的模板。
noRecordsTemplate：无匹配项时显示的模板。
allowDragAndDrop：启用拖放重排/转移。
scope：标识用于拖放转移的相关 ListBox。
allowFiltering：显示内置过滤搜索栏。
filterBarPlaceholder：过滤栏占位文本。
filterType：'StartsWith' | 'EndsWith' | 'Contains'。
toolbarSettings：为双 ListBox 转移配置工具栏按钮。
height：ListBox 高度。
sortOrder：'None' | 'Ascending' | 'Descending'。
enabled：启用/禁用组件。
enableRtl：从右到左渲染。
cssClass：附加 CSS 类。

适用场景

选择表单：作为多选下拉的替代。
转移列表：在双 ListBox 之间移动项目。
分类：基于分组的项目组织。
过滤：筛选大数据集。
数据展示：展示结构化列表数据。
无障碍：构建符合无障碍要求的选择界面。

限制

资料未提供关于收费、价格、平台兼容性、性能上限或具体版本要求的信息，暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制