syncfusion-aspnetcore-list-box

实现 Syncfusion ASP.NET Core ListBox

何时使用此技能

在以下情况下使用此技能：

• 在 ASP.NET Core 应用中实现 ListBox 控件，使用 TagHelper 语法
• 配置选择模式（单选或多选）
• 为 ListBox 组件绑定数据源
• 应用主题和样式，使其符合设计要求
• 处理高级功能，例如拖放、双列表和筛选
• 解决常见任务，例如添加项目、启用滚动器或集成表单
• 调试选择、数据绑定或渲染问题

组件概览

Syncfusion ASP.NET Core ListBox 组件是一种用途广泛的选择控件，支持：

• 单选和多选，支持键盘和鼠标导航
• 数据绑定，支持数组、对象和动态数据源
• 高级功能：拖放、模板、双列表、排序、分组
• 全面的主题支持，包括内置主题和自定义主题
• 完整的无障碍支持（符合 WCAG 标准、支持键盘导航）
• 丰富的自定义选项，可通过 CSS 类、属性和事件进行配置

适用于：下拉菜单、筛选器、选择界面、权限列表、批量操作

文档与导航指南

开始使用 ListBox

📄 阅读： references/getting-started.md

• NuGet 包安装步骤
• ASP.NET Core 项目设置（Razor Pages、MVC）
• 在 _ViewImports.cshtml 中注册 TagHelper
• CDN 样式表和脚本配置
• 注册 Syncfusion Script Manager
• 创建第一个 ListBox 控件
• 初始数据绑定示例

选择模式和用户交互

📄 阅读： references/selection-modes.md

• 单选模式（单选按钮样式）
• 多选模式（复选框样式）
• 选择事件（change、select、doubleClick）
• 键盘导航（方向键、空格键、Ctrl+A）
• 以编程方式管理选择
• 使用复选框实现全选功能
• 高级选择模式

数据绑定和数据源

📄 阅读： references/data-binding.md

• 将字符串数组绑定到 ListBox
• 绑定复杂对象数组
• 字段映射（Text 和 Value 属性）
• 通过 AJAX 动态加载数据
• 实时更新数据
• 主从列表和依赖列表
• 筛选和刷新数据

样式、主题和外观

📄 阅读： references/styling-and-appearance.md

• 内置主题（Material、Bootstrap、Fluent、Tailwind）
• 使用 Theme Studio 集成自定义主题
• 自定义 ListBox 元素的 CSS 类
• 实现水平 ListBox 布局
• 使用颜色、字体和间距自定义样式
• 移动设备和平板电脑的响应式设计模式
• 基于状态的项目着色和模板

ListBox 数据的排序和分组

📄 阅读： references/sorting-and-grouping.md

• 按升序或降序排列项目
• 按类别或类型对项目分组
• 结合排序和分组来整理列表
• 使用分组标题处理复杂数据
• 包含多个类别的实用示例
• 优化大型分组列表的性能

高级功能和配置

📄 阅读： references/features.md

• 在列表内及列表之间拖放
• 图标和自定义项目模板
• 双列表框（在列表之间传输项目）
• 对大型数据集使用虚拟滚动
• 为固定高度配置滚动器
• 复杂的选择场景和模式
• 事件处理最佳实践

常见任务和故障排除

📄 阅读： references/howto-common-tasks.md

• 动态添加和移除项目
• 启用/禁用特定项目
• 使用搜索筛选 ListBox 数据
• 提交包含所选值的表单
• 滚动定位和监控
• 在执行操作前验证用户输入
• 性能优化技巧
• 调试常见问题

快速入门示例

1. 安装 Syncfusion Package

// Package Manager Console
Install-Package Syncfusion.EJ2.AspNet.Core -Version 25.1.35

2. 注册 TagHelper

@addTagHelper *, Syncfusion.EJ2

3. 添加主题和脚本

<head>
    <link rel="stylesheet" href="https://cdn.syncfusion.com/ej2/25.1.35/fluent.css" />
</head>
<body>
    
    <script src="https://cdn.syncfusion.com/ej2/25.1.35/dist/ej2.min.js"></script>
    <ejs-scripts></ejs-scripts>
</body>

4. 创建基本 ListBox

// ~/Pages/Index.cshtml.cs
public class IndexModel : PageModel
{
    public List<string> Fruits { get; set; }
    
    public void OnGet()
    {
        Fruits = new List<string> { "Apple", "Banana", "Cherry", "Date" };
    }
}

@page
@model IndexModel

<ejs-listbox id="fruitBox" dataSource="@Model.Fruits"></ejs-listbox>

常见模式

模式 1：单选（类似单选按钮）

<ejs-listbox id="categoryBox" 
             dataSource="@Model.Categories"
             selectionSettings="@(new Syncfusion.EJ2.DropDowns.ListBoxSelectionSettings 
             { 
                 Mode = Syncfusion.EJ2.DropDowns.SelectionMode.Single 
             })"
             change="onCategoryChange">
</ejs-listbox>

<script>
    function onCategoryChange(args) {
        console.log('Selected: ' + args.text);
    }
</script>

适用场景： 用户选择一个选项（类别、部门、状态）

模式 2：多选（类似复选框）

<ejs-listbox id="tagsBox" 
             dataSource="@Model.Tags"
             selectionSettings="@(new Syncfusion.EJ2.DropDowns.ListBoxSelectionSettings 
             { 
                 Mode = Syncfusion.EJ2.DropDowns.SelectionMode.Multiple,
                 CheckboxPosition = Syncfusion.EJ2.DropDowns.CheckBoxPosition.Before
             })">
</ejs-listbox>

适用场景： 用户选择多个选项（权限、功能、筛选条件）

模式 3：带搜索筛选

<input type="text" id="searchBox" placeholder="Search..." />
<ejs-listbox id="searchableList" dataSource="@Model.Items"></ejs-listbox>

<script>
    const allItems = @Html.Raw(System.Text.Json.JsonSerializer.Serialize(Model.Items));
    
    document.getElementById('searchBox').addEventListener('keyup', function(e) {
        var listbox = document.getElementById('searchableList').ej2_instances[0];
        var term = e.target.value.toLowerCase();
        listbox.dataSource = allItems.filter(item => 
            item.toLowerCase().includes(term)
        );
    });
</script>

适用场景： 长列表需要筛选（员工、产品、权限）

模式 4：双列表（在列表之间传输）

<div style="display: flex; gap: 20px;">
    <div>
        <label>Available</label>
        <ejs-listbox id="availableBox" dataSource="@Model.Available"></ejs-listbox>
    </div>
    <div>
        <button onclick="moveRight()">→</button>
        <button onclick="moveLeft()">←</button>
    </div>
    <div>
        <label>Selected</label>
        <ejs-listbox id="selectedBox" dataSource="@Model.Selected"></ejs-listbox>
    </div>
</div>

适用场景： 在列表之间传输项目（权限、功能、用户）

关键属性和方法

核心属性

属性	类型	用途
dataSource	IEnumerable	列表中要显示的数据
value	string/array	当前选中的值
selectionSettings	ListBoxSelectionSettings	配置选择行为
fields	ListBoxFieldSettings	将对象属性映射到 text/value/groupBy
sortOrder	SortOrder	对项目排序：None、Ascending、Descending
cssClass	string	用于设置样式的自定义 CSS 类
allowDragAndDrop	bool	启用拖放排序
height	string	固定高度并支持滚动

常见方法

var listbox = document.getElementById('listBox').ej2_instances[0];

// Get/set value
listbox.value;                    // Get selected value(s)
listbox.value = 'newValue';       // Set selected

// Selection operations
listbox.selectAll();              // Select all items
listbox.clearSelection();         // Deselect all
listbox.selectItemsByRange(0, 3); // Select range

// Data operations
listbox.refresh();                // Refresh UI after data change
listbox.destroy();                // Clean up component

常见用例

用例	选择方式	功能	示例
类别选择器	单选	无	存储类别偏好
批量权限	多选	复选框	为用户分配权限
产品筛选器	多选	搜索	电商筛选
功能切换	多选	拖动排序	设置功能优先级
员工选择器	多选	搜索、模板	团队分配
报表字段	多选	双列表	包含/排除字段

主要功能一览

• ✓ 单选/多选 - 选择一个或多个项目
• ✓ 数据绑定 - 连接到数组、对象、数据库
• ✓ 排序 - 按字母顺序排列（升序/降序）
• ✓ 分组 - 按类别或类型组织项目
• ✓ 拖放 - 对项目重新排序，或在列表之间传输项目
• ✓ 模板 - 使用 HTML 自定义项目显示内容
• ✓ 主题 - 7 种以上内置主题和自定义主题
• ✓ 筛选 - 搜索和筛选数据
• ✓ 键盘导航 - 提供完整的键盘辅助功能支持
• ✓ 虚拟滚动 - 高效处理数千个项目
• ✓ 事件 - 更改、选择、滚动事件
• ✓ 响应式 - 支持桌面、平板和移动设备

故障排除快速链接

问题 → 解决方案

• “ListBox 未显示” → 检查入门指南
• “数据未绑定” → 参阅数据绑定
• “事件未触发” → 阅读选择模式
• “样式显示异常” → 查看样式指南
• “排序不起作用” → 检查排序和分组
• “分组不起作用” → 阅读排序和分组指南
• “性能缓慢” → 检查功能 - 滚动器
• “拖放不起作用” → 查看功能 - 拖放

Next Steps

1. New to ListBox? Start with Getting Started
2. Need selection control? Go to Selection Modes
3. Working with data? Read Data Binding
4. Organizing large lists? Visit Sorting & Grouping
5. Styling your list? Visit Styling & Appearance
6. Advanced features? Explore Advanced Features
7. Solving problems? Check Common Tasks

---

See Also

• Parent Library → Implementing Syncfusion ASP.NET Core Components
• Component Category → Dropdowns
• Syncfusion Docs → Official ListBox Documentation