Back to Details

syncfusion-aspnetcore-list-box

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion ASP.NET Core ListBox

实现Syncfusion ASP.NET Core ListBox

When to Use This Skill

何时使用此技能

Use this skill when you need to:
  • Implement ListBox control in ASP.NET Core applications using TagHelper syntax
  • Configure selection modes (single or multiple item selection)
  • Bind data sources to the ListBox component
  • Apply themes and styling to match your design
  • Handle advanced features like drag-and-drop, dual lists, and filtering
  • Solve common tasks like adding items, enabling scrollers, or form integration
  • Debug issues with selection, data binding, or rendering
在以下场景中使用此技能：
  • 使用TagHelper语法在ASP.NET Core应用中实现ListBox控件
  • 配置选择模式（单选或多选）
  • 为ListBox组件绑定数据源
  • 应用主题与样式以匹配设计需求
  • 处理高级功能，如拖放、双列表和筛选
  • 解决常见任务，如添加项、启用滚动条或表单集成
  • 调试选择、数据绑定或渲染相关问题

Component Overview

组件概述

The Syncfusion ASP.NET Core ListBox component is a versatile selection control that supports:
  • Single and multiple item selection with keyboard and mouse navigation
  • Data binding from arrays, objects, and dynamic sources
  • Advanced features: drag-drop, templates, dual lists, sorting, grouping
  • Comprehensive theming with built-in and custom themes
  • Full accessibility support (WCAG compliance, keyboard navigation)
  • Rich customization via CSS classes, properties, and events
Perfect for: dropdowns, filters, selection interfaces, permission lists, bulk operations
Syncfusion ASP.NET Core ListBox组件是一款多功能选择控件，支持：
  • 支持键盘和鼠标导航的单选与多选
  • 从数组、对象和动态源进行数据绑定
  • 高级功能：拖放、模板、双列表、排序、分组
  • 包含内置和自定义主题的全面主题支持
  • 完整的可访问性支持（符合WCAG标准、键盘导航）
  • 通过CSS类、属性和事件实现丰富的自定义
适用于：下拉菜单、筛选器、选择界面、权限列表、批量操作

Documentation and Navigation Guide

文档与导航指南

Getting Started with ListBox

ListBox快速入门

📄 Read: references/getting-started.md
  • NuGet package installation steps
  • ASP.NET Core project setup (Razor pages, MVC)
  • TagHelper registration in 
    _ViewImports.cshtml
  • CDN stylesheet and script configuration
  • Register Syncfusion Script Manager
  • Create your first ListBox control
  • Initial data binding examples
📄 阅读： references/getting-started.md
  • NuGet包安装步骤
  • ASP.NET Core项目设置（Razor页面、MVC）
  • 在
    _ViewImports.cshtml
    中注册TagHelper
  • CDN样式表和脚本配置
  • 注册Syncfusion脚本管理器
  • 创建第一个ListBox控件
  • 初始数据绑定示例

Selection Modes and User Interaction

选择模式与用户交互

📄 Read: references/selection-modes.md
  • Single selection mode (radio button style)
  • Multiple selection mode (checkbox style)
  • Selection events (
    change
    , 
    select
    , 
    doubleClick
    )
  • Keyboard navigation (arrows, space, Ctrl+A)
  • Programmatic selection management
  • Select-all functionality with checkboxes
  • Advanced selection patterns
📄 阅读： references/selection-modes.md
  • 单选模式（单选按钮样式）
  • 多选模式（复选框样式）
  • 选择事件（
    change
    、
    select
    、
    doubleClick
    ）
  • 键盘导航（方向键、空格键、Ctrl+A）
  • 程序化选择管理
  • 带复选框的全选功能
  • 高级选择模式

Data Binding and Data Sources

数据绑定与数据源

📄 Read: references/data-binding.md
  • Binding string arrays to ListBox
  • Binding complex object arrays
  • Field mapping (Text and Value properties)
  • Dynamic data loading via AJAX
  • Real-time data updates
  • Master-detail and dependent lists
  • Filtering and refreshing data
📄 阅读： references/data-binding.md
  • 为ListBox绑定字符串数组
  • 绑定复杂对象数组
  • 字段映射（Text和Value属性）
  • 通过AJAX加载动态数据
  • 实时数据更新
  • 主从表和依赖列表
  • 筛选与刷新数据

Styling, Theming, and Appearance

样式、主题与外观

📄 Read: references/styling-and-appearance.md
  • Built-in themes (Material, Bootstrap, Fluent, Tailwind)
  • Theme Studio integration for custom themes
  • CSS class customization for ListBox elements
  • Horizontal ListBox layout implementation
  • Custom styling with colors, fonts, and spacing
  • Responsive design patterns for mobile/tablet
  • Status-based item coloring and templates
📄 阅读： references/styling-and-appearance.md
  • 内置主题（Material、Bootstrap、Fluent、Tailwind）
  • 集成Theme Studio创建自定义主题
  • 为ListBox元素自定义CSS类
  • 实现水平ListBox布局
  • 使用颜色、字体和间距进行自定义样式
  • 适用于手机/平板的响应式设计模式
  • 基于状态的项着色与模板

Sorting and Grouping ListBox Data

ListBox数据排序与分组

📄 Read: references/sorting-and-grouping.md
  • Sort items in ascending/descending order
  • Group items by category or type
  • Combine sorting and grouping for organized lists
  • Handle complex data with group headers
  • Practical examples with multiple categories
  • Performance optimization for large grouped lists
📄 阅读： references/sorting-and-grouping.md
  • 按升序/降序排序项
  • 按类别或类型分组项
  • 结合排序与分组实现有序列表
  • 处理带组头的复杂数据
  • 多类别实用示例
  • 大型分组列表的性能优化

Advanced Features and Configurations

高级功能与配置

📄 Read: references/features.md
  • Drag and drop within list and between lists
  • Icons and custom item templates
  • Dual list box (transfer between lists)
  • Virtual scrolling for large datasets
  • Scroller configuration for fixed heights
  • Complex selection scenarios and patterns
  • Event handling best practices
📄 阅读： references/features.md
  • 列表内部及列表间的拖放
  • 图标与自定义项模板
  • 双列表框（列表间项传输）
  • 大型数据集的虚拟滚动
  • 固定高度的滚动条配置
  • 复杂选择场景与模式
  • 事件处理最佳实践

Common Tasks and Troubleshooting

常见任务与故障排除

📄 Read: references/howto-common-tasks.md
  • Adding and removing items dynamically
  • Enabling/disabling specific items
  • Filtering ListBox data with search
  • Form submission with selected values
  • Scroll positioning and monitoring
  • Validating user input before operations
  • Performance optimization techniques
  • Debugging common issues
📄 阅读： references/howto-common-tasks.md
  • 动态添加和删除项
  • 启用/禁用特定项
  • 通过搜索筛选ListBox数据
  • 提交表单时获取选中值
  • 滚动位置定位与监控
  • 操作前验证用户输入
  • 性能优化技巧
  • 调试常见问题

Quick Start Example

快速入门示例

1. Install Syncfusion Package

1. 安装Syncfusion包

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

2. Register TagHelper

2. 注册TagHelper

cshtml
<!-- ~/Pages/_ViewImports.cshtml -->
@addTagHelper *, Syncfusion.EJ2
cshtml
<!-- ~/Pages/_ViewImports.cshtml -->
@addTagHelper *, Syncfusion.EJ2

3. Add Theme and Scripts

3. 添加主题与脚本

cshtml
<!-- ~/Pages/Shared/_Layout.cshtml -->
<head>
    <link rel="stylesheet" href="https://cdn.syncfusion.com/ej2/25.1.35/fluent.css" />
</head>
<body>
    <!-- Content -->
    <script src="https://cdn.syncfusion.com/ej2/25.1.35/dist/ej2.min.js"></script>
    <ejs-scripts></ejs-scripts>
</body>
cshtml
<!-- ~/Pages/Shared/_Layout.cshtml -->
<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. Create Basic ListBox

4. 创建基础ListBox

csharp
// ~/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" };
    }
}
cshtml
<!-- ~/Pages/Index.cshtml -->
@page
@model IndexModel

<ejs-listbox id="fruitBox" dataSource="@Model.Fruits"></ejs-listbox>
csharp
// ~/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" };
    }
}
cshtml
<!-- ~/Pages/Index.cshtml -->
@page
@model IndexModel

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

Common Patterns

常见模式

Pattern 1: Single Selection (Like Radio Buttons)

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

cshtml
<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>
Use when: User picks one option (category, department, status)
cshtml
<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>
适用场景： 用户选择单个选项（类别、部门、状态）

Pattern 2: Multiple Selection (Like Checkboxes)

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

cshtml
<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>
Use when: User selects multiple options (permissions, features, filters)
cshtml
<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>
适用场景： 用户选择多个选项（权限、功能、筛选器）

Pattern 3: With Search Filter

模式3：带搜索筛选

cshtml
<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>
Use when: Long lists need filtering (employees, products, permissions)
cshtml
<input type="text" id="searchBox" placeholder="搜索..." />
<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>
适用场景： 长列表需要筛选（员工、产品、权限）

Pattern 4: Dual List (Transfer Between Lists)

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

cshtml
<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>
Use when: Transferring items between lists (permissions, features, users)
cshtml
<div style="display: flex; gap: 20px;">
    <div>
        <label>可用项</label>
        <ejs-listbox id="availableBox" dataSource="@Model.Available"></ejs-listbox>
    </div>
    <div>
        <button onclick="moveRight()">→</button>
        <button onclick="moveLeft()">←</button>
    </div>
    <div>
        <label>已选项目</label>
        <ejs-listbox id="selectedBox" dataSource="@Model.Selected"></ejs-listbox>
    </div>
</div>
适用场景： 在列表间传输项（权限、功能、用户）

Key Properties and Methods

关键属性与方法

Essential Properties

核心属性

PropertyTypePurpose
dataSource
IEnumerableData to display in the list
value
string/arrayCurrently selected value(s)
selectionSettings
ListBoxSelectionSettingsConfigure selection behavior
fields
ListBoxFieldSettingsMap object properties to text/value/groupBy
sortOrder
SortOrderSort items: None, Ascending, Descending
cssClass
stringCustom CSS class for styling
allowDragAndDrop
boolEnable drag-drop reordering
height
stringFixed height with scroll
属性类型用途
dataSource
IEnumerable列表中显示的数据
value
string/array当前选中的值（单个或多个）
selectionSettings
ListBoxSelectionSettings配置选择行为
fields
ListBoxFieldSettings将对象属性映射到文本/值/分组字段
sortOrder
SortOrder项排序：无、升序、降序
cssClass
string用于样式自定义的CSS类
allowDragAndDrop
bool启用拖放重排序
height
string设置固定高度并启用滚动

Common Methods

常用方法

javascript
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
javascript
var listbox = document.getElementById('listBox').ej2_instances[0];

// 获取/设置值
listbox.value;                    // 获取选中值
listbox.value = 'newValue';       // 设置选中值

// 选择操作
listbox.selectAll();              // 全选所有项
listbox.clearSelection();         // 取消所有选择
listbox.selectItemsByRange(0, 3); // 选择指定范围的项

// 数据操作
listbox.refresh();                // 数据变更后刷新UI
listbox.destroy();                // 销毁组件

Common Use Cases

常见用例

Use CaseSelectionFeaturesExample
Category PickerSingleNoneStore category preference
Bulk PermissionsMultipleCheckboxesAssign permissions to users
Product FilterMultipleSearchE-commerce filtering
Feature ToggleMultipleDrag-sortSet feature priority
Employee SelectorMultipleSearch, TemplatesTeam assignment
Report FieldsMultipleDual listsInclude/exclude fields
用例选择模式功能示例
类别选择器单选无存储类别偏好
批量权限分配多选复选框为用户分配权限
产品筛选器多选搜索电商商品筛选
功能排序多选拖拽排序设置功能优先级
员工选择器多选搜索、模板团队成员分配
报表字段选择多选双列表包含/排除字段

Key Features at a Glance

核心功能概览

  • ✓ Single/Multiple Selection - Choose one or many items
  • ✓ Data Binding - Connect to arrays, objects, databases
  • ✓ Sorting - Alphabetical ordering (ascending/descending)
  • ✓ Grouping - Organize items by category or type
  • ✓ Drag & Drop - Reorder items or transfer between lists
  • ✓ Templates - Customize item display with HTML
  • ✓ Theming - 7+ built-in themes + custom themes
  • ✓ Filtering - Search and filter data
  • ✓ Keyboard Nav - Full keyboard support for accessibility
  • ✓ Virtual Scroll - Handle thousands of items efficiently
  • ✓ Events - Change, select, scroll events
  • ✓ Responsive - Works on desktop, tablet, mobile
  • ✓ 单选/多选 - 选择单个或多个项
  • ✓ 数据绑定 - 连接数组、对象、数据库
  • ✓ 排序 - 按字母顺序升序/降序排列
  • ✓ 分组 - 按类别或类型组织项
  • ✓ 拖放 - 重排序项或在列表间传输
  • ✓ 模板 - 使用HTML自定义项显示
  • ✓ 主题 - 7+内置主题 + 自定义主题
  • ✓ 筛选 - 搜索和过滤数据
  • ✓ 键盘导航 - 完整的键盘支持以确保可访问性
  • ✓ 虚拟滚动 - 高效处理数千条数据
  • ✓ 事件 - 变更、选择、滚动等事件
  • ✓ 响应式 - 适配桌面、平板、移动设备

Troubleshooting Quick Links

故障排除快速链接

Problem → Solution
  • "ListBox not showing" → Check Getting Started
  • "Data not binding" → See Data Binding
  • "Events not firing" → Read Selection Modes
  • "Styling looks wrong" → Visit Styling Guide
  • "Sorting not working" → Check Sorting & Grouping
  • "Grouping not working" → Read Sorting & Grouping Guide
  • "Performance slow" → Check Features - Scroller
  • "Drag-drop not working" → Review Features - Drag & Drop
问题 → 解决方案
  • "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
  1. 首次使用ListBox？ 从快速入门开始
  2. 需要选择控件？ 查看选择模式
  3. 处理数据？ 阅读数据绑定
  4. 组织大型列表？ 访问排序与分组
  5. 自定义列表样式？ 访问样式与外观
  6. 使用高级功能？ 探索高级功能
  7. 解决问题？ 查看常见任务

See Also

相关链接

  • Parent Library → Implementing Syncfusion ASP.NET Core Components
  • Component Category → Dropdowns
  • Syncfusion Docs → Official ListBox Documentation
  • 父级库 → 实现Syncfusion ASP.NET Core组件
  • 组件分类 → 下拉菜单
  • Syncfusion官方文档 → ListBox官方文档