syncfusion-blazor-dropdowns

实现 Syncfusion Blazor 下拉列表

AutoComplete

AutoComplete 组件会在用户输入时提供智能搜索建议，支持本地和远程数据源，并具备高级筛选、自定义和无障碍功能。

组件概览

SfAutoComplete 组件支持：

• 数据绑定： 本地基元、对象或远程数据源
• 筛选： 实时搜索并支持防抖、筛选类型（StartsWith、Contains、EndsWith）
• 组织： 分组、排序、多列显示
• 自定义： 项目／分组／标题／页脚模板、样式、占位符
• 性能： 为大型数据集提供虚拟化
• 无障碍： 符合 WCAG 标准、键盘导航、支持 ARIA
• 交互： 事件、禁用项目、自定义值、支持 RTL

文档导航指南

选择与当前任务相符的参考文档：

开始使用

📄 阅读： references/getting-started.md

• 安装 NuGet 包
• 项目设置（Visual Studio、VS Code、.NET CLI）
• 基本的自动完成实现
• CSS 导入和主题设置
• 初始配置

数据绑定与数据源

📄 阅读： references/data-binding.md

• 绑定本地数据（基元、对象、ObservableCollection）
• 复杂数据类型（ExpandoObject、DynamicObject）
• 使用 DataManager 处理远程数据
• ODataAdaptor、Web API 和自定义适配器
• DataBound 事件处理

筛选与搜索

📄 阅读： references/filtering-and-search.md

• 启用和配置筛选
• 筛选类型（StartsWith、Contains、EndsWith）
• 本地与远程数据筛选
• 用于提升性能的 DebounceDelay
• 最小字符长度
• 高亮显示搜索结果

数据组织

📄 阅读： references/data-organization.md

• 按类别对数据分组
• 对列表项排序
• 多列显示
• 选择和选择模式
• 值绑定和自定义值

模板与样式

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

• 项目模板（自定义列表项布局）
• 分组模板（自定义分组标题）
• 标题、页脚和无记录模板
• CSS 类样式
• 占位符和 FloatLabel 自定义

高级功能

📄 阅读： references/advanced-features.md

• 大型数据集的虚拟化
• 弹出窗口设置和定位
• 禁用项目处理
• 支持自定义值
• 本地化和 RTL 支持
• 事件处理（ActionBegin、ActionComplete、ValueChange 等）

无障碍与最佳实践

📄 阅读： references/accessibility-and-best-practices.md

• 符合 WCAG 标准和无障碍标准
• ARIA 属性
• 键盘导航支持
• 屏幕阅读器兼容性
• 性能优化技巧
• 常见问题和故障排查

快速入门示例

使用本地数据实现 AutoComplete 的最简示例：

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Country" DataSource="@Countries">
    <AutoCompleteFieldSettings Value="CountryName"></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Country
    {
        public string CountryName { get; set; }
    }

    private List<Country> Countries = new()
    {
        new Country { CountryName = "Austria" },
        new Country { CountryName = "Brazil" },
        new Country { CountryName = "Canada" }
    };
}

常见模式

模式 1：筛选用户输入

启用实时筛选，在用户输入时进行筛选：

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Options"
                AllowFiltering="true"
                FilterType="FilterType.Contains">
</SfAutoComplete>

模式 2：使用防抖处理远程数据

通过防抖延迟减少服务器请求：

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true"
                DebounceDelay="300">
    <SfDataManager Url="api/products" Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor"></SfDataManager>
</SfAutoComplete>

模式 3：使用模板自定义项目显示

自定义列表项外观：

<SfAutoComplete TValue="string" TItem="Product" DataSource="@Products">
    <AutoCompleteTemplates TItem="Product">
        <ItemTemplate>
            <div>
                <span>@((context as Product)?.ProductName)</span>
                <span style="float:right">@((context as Product)?.Price)</span>
            </div>
        </ItemTemplate>
    </AutoCompleteTemplates>
</SfAutoComplete>

模式 4：分组和排序显示

通过分组和排序来组织数据：

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees"
                SortOrder="SortOrder.Ascending">
    <AutoCompleteFieldSettings GroupBy="Department" Value="EmployeeName"></AutoCompleteFieldSettings>
</SfAutoComplete>

关键属性

属性	类型	用途
DataSource	IEnumerable<TItem>	提示的源数据
AllowFiltering	bool	启用或禁用筛选
FilterType	FilterType	筛选模式（StartsWith、Contains、EndsWith）
DebounceDelay	int	触发筛选前的延迟时间（毫秒）
MinLength	int	触发筛选所需的最少字符数
SortOrder	SortOrder	对列表项排序（Ascending、Descending）
EnableVirtualization	bool	对大型数据集启用虚拟化
AllowCustom	bool	允许用户输入自定义值
Placeholder	string	输入框占位文本
FloatLabelType	FloatLabelType	浮动标签行为

常见用例

1. 边输入边搜索： 自动补全员工姓名、产品和地点
2. 筛选下拉列表： 用户筛选时显示匹配项
3. 远程 API： 从后端服务获取提示
4. 多列显示： 在名称旁显示产品详情
5. 分组提示： 按类别或部门整理
6. 自定义值： 允许用户创建新条目
7. 大型数据集： 对 1000+ 个项目启用虚拟化以提升性能

---

后续步骤： 从getting-started.md开始设置，或跳转到与任务相符的参考文档。

---

ComboBox

用于实现 ComboBox 组件的综合技能。ComboBox 允许用户从下拉列表中选择值，同时提供筛选、自定义模板、级联场景、数据绑定和丰富的自定义选项。

何时使用此技能

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

• 安装和设置 ComboBox 组件
• 使用本地或远程数据源实现 ComboBox
• 配置数据绑定（基本类型、复杂对象、集合）
• 启用并配置筛选和搜索功能
• 处理值选择和更改事件
• 创建级联 ComboBox 场景（依赖下拉列表）
• 使用模板自定义外观（项目、页眉、页脚）
• 将 ComboBox 与表单验证集成（EditForm、数据注释）
• 配置弹出窗口设置（高度、宽度、调整大小、位置）
• 对 ComboBox 数据进行分组和排序
• 处理事件（ValueChange、OnValueSelect、Blur 等）
• 实现无障碍功能和键盘导航
• 自定义样式和主题
• 排查常见的 ComboBox 问题

快速入门示例

@using Syncfusion.Blazor.DropDowns

<SfComboBox TItem="Country" TValue="string" 
    Placeholder="Select a country" 
    DataSource="@CountryData"
    @bind-Value="@SelectedValue">
    <ComboBoxFieldSettings Text="Name" Value="Code"></ComboBoxFieldSettings>
</SfComboBox>

@code {
    private string SelectedValue = "USA";
    private List<Country> CountryData = new()
    {
        new Country { Name = "United States", Code = "USA" },
        new Country { Name = "United Kingdom", Code = "UK" },
        new Country { Name = "Canada", Code = "CA" }
    };

    public class Country
    {
        public string Name { get; set; }
        public string Code { get; set; }
    }
}

关键属性参考

属性	类型	用途
TValue	Generic	所选值的类型
TItem	Generic	列表中数据项的类型
DataSource	IEnumerable	要显示的项目列表
@bind-Value	TValue	对所选值进行双向绑定
@bind-Index	int?	对所选索引进行双向绑定
Placeholder	string	未选择值时显示的提示文本
AllowFiltering	bool	启用或禁用筛选
AllowCustom	bool	允许输入任意文本
Readonly	bool	将组件设为只读
Disabled	bool	禁用组件

常见模式

模式 1：基本数据绑定

将 ComboBox 绑定到包含基本类型或复杂类型的本地列表。使用 ComboBoxFieldSettings 映射文本和值字段。

模式 2：筛选与搜索

启用 AllowFiltering，让用户在输入时筛选数据。使用 FilterType 和 DebounceDelay 控制筛选行为。

模式 3：级联 ComboBox

使用父级 ComboBox 的 ValueChange 事件，根据父级选择动态填充子级 ComboBox 数据。

模式 4：表单集成

将 ComboBox 包装在 EditForm 中，并使用数据注释进行自动验证。使用 ValidationMessage 显示错误。

模式 5：自定义模板

使用 ItemTemplate、HeaderTemplate 和 FooterTemplate 为列表项和弹出窗口区域创建自定义 UI。

---

文档导航指南

根据任务阅读相应的参考文件：

📄 入门

阅读： references/getting-started.md

• 安装和 NuGet 包
• ComboBox 基本实现
• Web App 与 Server App 的设置
• CSS 导入和主题
• 第一个可运行的示例

📄 数据绑定

阅读： references/data-binding.md

• 本地数据绑定（数组、列表、集合）
• 基本类型与复杂对象绑定
• 基于索引的值绑定
• 使用 DataManager 处理远程数据
• OData 和 Web API 适配器
• 自定义数据适配器
• 动态对象绑定场景

📄 筛选与搜索

阅读： references/filtering.md

• 使用 AllowFiltering 启用筛选
• 本地与远程数据筛选
• 筛选类型（contains、startsWith、endsWith）
• 自定义筛选逻辑
• 用于提升性能的防抖延迟
• 区分大小写的筛选选项

📄 选择与值绑定

阅读： references/selection-and-value.md

• 获取和设置选中值
• 值绑定与索引绑定
• 初始化时预选值
• 以编程方式更改值
• 选择事件（ValueChange、OnValueSelect）
• 自动填充功能

📄 级联 ComboBox

阅读： references/cascading-combobox.md

• 创建依赖式/级联 ComboBox 链
• 根据父级选择填充子级 ComboBox
• 多级级联（3 级及以上）
• 根据选择填充其他表单字段
• 实际示例

📄 模板与自定义

阅读： references/templates-and-customization.md

• 用于自定义列表呈现的项目模板
• 用于分组数据的分组模板
• 页眉和页脚模板
• 自定义值模板
• 模板中的 HTML 内容
• 模板调试技巧

📄 事件与验证

阅读： references/events-and-validation.md

• ComboBox 事件（Creating、Created、Blur 等）
• ValueChange 和 OnValueSelect 事件
• 使用 EditForm 进行表单验证
• 数据注解和验证规则
• 自定义验证逻辑
• 通过取消事件阻止操作

📄 弹出窗口与外观

阅读： references/popup-and-appearance.md

• 配置弹出窗口的高度和宽度
• 弹出窗口的位置和 z-index
• 弹出窗口打开/关闭事件
• 允许调整弹出窗口大小
• 初始加载时显示弹出窗口
• 占位符和 FloatLabel
• CSS 类和样式

📄 高级功能

阅读： references/advanced-features.md

• 按类别对数据分组
• 排序选项和自定义排序顺序
• 对大型数据集进行虚拟化
• 列表中的禁用项
• RTL（从右到左）支持
• 无障碍功能（符合 WCAG 标准）
• 键盘导航

📄 故障排除

阅读： references/troubleshooting.md

• 数据未加载或列表为空
• 筛选未按预期工作
• 选择/绑定问题
• 事件处理程序未触发
• 性能优化技巧
• 常见错误及解决方案

---

常见用例

用例 1：国家/州/城市选择

• 创建 3 级级联 ComboBox
• 用户选择国家 → 填充州/省 → 填充城市
• 参见：级联 ComboBox + 事件与验证

用例 2：使用自定义显示搜索/筛选列表

• 使用自定义模板启用筛选
• 显示复杂数据（图标、描述、颜色）
• 参见：筛选与搜索 + 模板与自定义

用例 3：包含多个下拉列表的表单

• 将 ComboBox 集成到 EditForm 中
• 使用数据注解验证选择
• 在下拉列表之间设置级联
• 参见：事件与验证 + 级联 ComboBox

用例 4：大型数据集的性能

• 使用虚拟化绑定 1000+ 个项目
• 通过 API 启用远程筛选
• 配置防抖延迟
• 参见：高级功能 + 数据绑定

主要功能概述

✅ 本地与远程数据绑定 - 支持数组、列表、可观察对象、DataManager
✅ 灵活筛选 - 内置筛选功能，并提供自定义选项
✅ 模板 - 提供项目、分组、页眉和页脚模板，可自定义 UI
✅ 级联 - 创建相互依赖的下拉列表链
✅ 表单集成 - 原生支持 EditForm 和验证
✅ 事件 - 提供丰富的用户交互事件系统
✅ 无障碍功能 - 符合 WCAG 标准，支持键盘导航
✅ 自定义 - 支持主题、样式和 CSS 类
✅ 性能 - 支持大型列表虚拟化
✅ RTL 支持 - 支持从右向左书写的语言

---

相关组件

• DropdownList - 与 ComboBox 类似，但不支持自由文本输入
• AutoComplete - 带下拉列表的建议式文本输入
• MultiSelect - 支持从下拉列表中多选
• ListBox - 支持选择的可滚动列表

---

DropDown List

这是一项全面的技能，用于在 Blazor 应用程序中实现 Syncfusion DropDown List 组件。该组件支持灵活的项目选择，并支持数据绑定、筛选、模板、级联以及丰富的自定义选项。

何时使用此技能

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

• 在 Blazor 中创建用于选择项目的下拉列表组件
• 将下拉列表数据绑定到本地集合或远程 API
• 实现筛选和搜索功能
• 使用模板自定义下拉列表的呈现方式
• 处理选择事件和值绑定
• 创建级联下拉列表关系
• 对下拉列表项目进行分组和排序
• 使用下拉列表选择实现表单验证
• 为下拉列表应用样式和主题
• 支持无障碍功能和键盘导航
• 为本地化启用 RTL（从右向左）支持
• 使用虚拟化管理大型数据集
• 配置弹出窗口的行为和位置
• 处理禁用项目和占位符

组件概述

主要功能：

• 多选：使用多种模式选择一个或多个项目
• 数据源：绑定到集合、API 或自定义数据提供程序
• 筛选：内置搜索功能，并提供可自定义的筛选选项
• 分组与排序：通过排序按层次组织项目
• 自定义模板：设计自定义项目、分组、页眉和页脚模板
• 键盘导航：全面支持键盘操作和无障碍功能（WCAG 2.1）
• 主题：支持 Bootstrap、Material、Fluent、Tailwind 主题，以及浅色和深色模式
• 验证：支持表单验证和自定义验证器
• RTL 与本地化：支持从右向左书写的语言和多语言
• 虚拟化：高效处理大型数据集

文档和导航指南

入门

📄 阅读： references/getting-started-dropdown-list.md

• 安装和 NuGet 包设置
• 基本组件实现
• CSS 主题导入
• 最小可运行示例
• 呈现下拉列表

数据绑定

📄 阅读： references/data-binding.md

• 绑定本地集合（基元、复杂类型、可观察对象）
• 使用 Web API 和 OData 进行远程数据绑定
• 数据源事件（OnActionBegin、OnActionComplete）
• 动态数据和枚举数据绑定
• 值元组和 expando 对象绑定

筛选和搜索

📄 阅读： references/filtering-and-searching.md

• 筛选类型和策略
• 区分大小写的筛选
• 最小筛选长度配置
• 用于优化性能的防抖延迟
• 多列筛选
• 自定义筛选逻辑

模板和呈现

📄 阅读： references/templates-and-rendering.md

• 自定义项目模板
• 页眉和页脚模板
• 用于显示所选项目的值模板
• 模板中的条件呈现
• 复杂模板模式

选择和值绑定

📄 阅读： references/selection-and-value-binding.md

• 获取和设置选定值
• 使用 @bind-Value 指令进行值绑定
• 值变更事件
• 清除和重置选择
• 处理复杂对象选择

自定义和样式设置

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

• 聚焦时打开下拉列表
• 应用 CSS 类
• 应用和切换主题
• 组件尺寸和外观
• 设置打开和关闭状态的样式

高级功能

📄 阅读： references/advanced-features.md

• 用于依赖选择的级联下拉列表
• 项目分组和整理
• 排序选项
• 禁用项目和状态
• 占位文本和浮动标签
• 弹出窗口设置和定位
• 对大型数据集进行虚拟化

表单验证

📄 阅读： references/form-validation.md

• 与 EditForm 集成
• 数据注解验证
• 验证错误显示
• 自定义验证规则
• 表单提交模式

本地化和 RTL

📄 阅读： references/localization-and-rtl.md

• RTL（从右到左）支持
• 本地化模式
• 特定区域性的格式设置
• 多语言支持

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1
• WAI-ARIA 属性和角色
• 键盘导航（方向键、Enter、Escape）
• 屏幕阅读器兼容性
• 焦点管理
• 高对比度支持

快速入门

基本下拉列表实现

@page "/dropdown-demo"

<h3>Simple Dropdown List</h3>

<SfDropDownList TValue="int" TItem="Country" DataSource="@Countries" Placeholder="Select a country">
    <DropDownListFieldSettings Text="@nameof(Country.CountryName)" Value="@nameof(Country.CountryId)" />
</SfDropDownList>

@code {
    public List<Country> Countries { get; set; }

    protected override void OnInitialized()
    {
        Countries = new List<Country>
        {
            new Country { CountryId = 1, CountryName = "United States" },
            new Country { CountryId = 2, CountryName = "Canada" },
            new Country { CountryId = 3, CountryName = "Mexico" }
        };
    }

    public class Country
    {
        public int CountryId { get; set; }
        public string CountryName { get; set; }
    }
}

值绑定和选择事件

<SfDropDownList TValue="int" TItem="Country" @bind-Value="SelectedCountryId"
                DataSource="@Countries"
                Placeholder="Choose a country">
    <DropDownListFieldSettings Text="@nameof(Country.CountryName)" Value="@nameof(Country.CountryId)" />
    <DropDownListEvents TValue="int" TItem="Country" ValueChange="@OnValueChange"></DropDownListEvents>
</SfDropDownList>

<p>Selected: @SelectedCountryId</p>

@code {
    private int SelectedCountryId;
    
    protected override void OnInitialized()
    {
        Countries = new List<Country>
        {
            new Country { CountryId = 1, CountryName = "United States" },
            new Country { CountryId = 2, CountryName = "Canada" },
            new Country { CountryId = 3, CountryName = "Mexico" }
        };
    }

    public class Country
    {
        public int CountryId { get; set; }
        public string CountryName { get; set; }
    }

    private void OnValueChange(ChangeEventArgs<int, Country> args)
    {
        SelectedCountryId = args.Value;
        // Handle value change
    }
}

常见模式

模式 1：带筛选功能的下拉列表

启用输入即筛选功能，帮助用户在大型列表中快速查找项目：

<SfDropDownList TValue="string" TItem="string"
                DataSource="@Items"
                AllowFiltering="true"
                FilterType="Syncfusion.Blazor.DropDowns.FilterType.Contains"
                Placeholder="Type to filter">
</SfDropDownList>

模式 2：级联下拉列表

创建依赖下拉列表，其中一个下拉列表中的选择会影响另一个下拉列表中的选项：

<SfDropDownList TValue="int" TItem="Country" @bind-Value="SelectedCountry"
                DataSource="@Countries"
                Placeholder="Select Country">
    <DropDownListFieldSettings Text="@nameof(Country.Name)" Value="@nameof(Country.Id)" />
    <DropDownListEvents TValue="int" TItem="Country" ValueChange="@OnCountryChange"></DropDownListEvents>
</SfDropDownList>

<SfDropDownList TValue="int" TItem="City"
                DataSource="@FilteredCities"
                Placeholder="Select City">
    <DropDownListFieldSettings Text="@nameof(City.Name)" Value="@nameof(City.Id)" />
</SfDropDownList>

@code {
    private int SelectedCountry;
    private List<City> FilteredCities;

    private void OnCountryChange(ChangeEventArgs<int, Country> args)
    {
        SelectedCountry = args.Value;
        FilteredCities = Cities.Where(c => c.CountryId == SelectedCountry).ToList();
    }
}

模式 3：远程数据绑定

连接 API 以动态加载数据：

<SfDropDownList TValue="int" TItem="DataItem"
                DataSource="@RemoteData"
                Placeholder="Select item">
    <DropDownListFieldSettings Text="@nameof(DataItem.CountryName)" Value="@nameof(DataItem.CountryId)" />
    <DropDownListEvents TValue="int" TItem="DataItem" OnActionComplete="@OnActionComplete"></DropDownListEvents>
</SfDropDownList>

@code {
    private List<DataItem> RemoteData;
    
    private async Task OnActionComplete(ActionCompleteEventArgs<DataItem> args)
    {
        var response = await HttpClient.GetAsync("api/items");
        RemoteData = await response.Content.ReadAsAsync<List<DataItem>>();
    }

    public class DataItem
    {
        public int CountryId { get; set; }
        public string CountryName { get; set; }
    }
}

模式 4：自定义项目模板

使用模板在下拉列表项目中显示丰富内容：

<SfDropDownList TValue="int" TItem="Employee" DataSource="@Employees">
    <DropDownListFieldSettings Text="@nameof(Employee.EmployeeName)" Value="@nameof(Employee.Id)" />
    <DropDownListTemplates TValue="Employee">
        <ItemTemplate>
            <span>@context.EmployeeName - @context.Designation</span>
        </ItemTemplate>
    </DropDownListTemplates>
</SfDropDownList>

模式 5：表单验证

与 EditForm 集成以进行验证：

<EditForm Model="@FormModel">
    <DataAnnotationsValidator />
    <ValidationSummary />
    
    <div class="form-group">
        <label>Select Department</label>
        <SfDropDownList TValue="int" TItem="Department" @bind-Value="FormModel.DepartmentId"
                        DataSource="@Departments"
                        Placeholder="Choose department">
            <DropDownListFieldSettings Text="@nameof(Department.Name)" Value="@nameof(Department.Id)" />
        </SfDropDownList>
    </div>
    
    <button type="submit">Submit</button>
</EditForm>

@code {
    private FormData FormModel = new();
    
    public class FormData
    {
        [Required(ErrorMessage = "Department is required")]
        public int DepartmentId { get; set; }
    }
}

关键属性和事件

必要属性

属性	说明
DataSource	IEnumerable<T> 要显示的项目集合
Value / @bind-Value	TValue 当前选定值
Placeholder	string 未选择时显示的提示文本
AllowFiltering	bool 启用搜索/筛选功能
FilterType	FilterType 筛选策略（StartsWith、Contains、EndsWith）
Enabled	bool 启用或禁用下拉列表
EnableRtl	bool 从右到左的文本方向
Width	string 组件宽度（px、% 等）

字段映射： 使用 <DropDownListFieldSettings Text="..." Value="..." /> 子组件标签映射数据字段。

必要事件（位于 <DropDownListEvents> 内）

事件	说明
ValueChange	选定值变更时触发
OnActionBegin	开始获取远程数据之前触发
OnActionComplete	完成获取远程数据之后触发
OnActionFailure	获取远程数据失败时触发
OnOpen	下拉列表打开时触发
OnClose	下拉列表关闭时触发
Focus	组件获得焦点时触发
Blur	组件失去焦点时触发

常见用例

1. 表单中的用户选择 - 从列表中选择用户进行分配或通知
2. 类别／类型选择 - 从预定义的类别或类型中进行选择
3. 级联选择 - 使用相互依赖的下拉列表（国家 → 州 → 城市）
4. 从 API 获取动态数据 - 从后端服务加载选项
5. 可搜索列表 - 高效筛选大型数据集
6. 多阶段工作流 - 基于选择的表单导航
7. 数据筛选 - 根据下拉列表中的选择应用筛选条件
8. 模板化下拉列表 - 显示丰富内容（图片、描述）
9. 本地化选择 - 提供特定地区／语言的选项
10. 符合无障碍规范的表单 - 符合 WCAG 规范的选择界面

相关组件

• ComboBox - 可编辑的下拉列表，支持文本输入
• AutoComplete - 带自动建议下拉列表的文本输入框
• ListBox - 提供选择选项的多项列表
• MultiSelect Dropdown - 从列表中选择多个项目
• Mention - @提及自动补全（类似社交媒体）

后续步骤

1. 从上方的“常见用例”中选择用例
2. 在“文档与导航指南”部分中找到相关的参考指南
3. 复制模式示例，并根据你的具体数据和需求进行调整
4. 查阅相应参考资料，了解高级配置和边缘情况

如需了解详细的实现模式、完整代码示例和故障排除指南，请根据你的具体需求阅读相应的参考文件。

---

MultiSelect Dropdown

MultiSelect Dropdown 组件支持用户从列表中选择多个项目，并提供筛选、分组、排序、键盘导航、无障碍支持和丰富的自定义选项。本技能将指导你完成安装、实现、数据绑定、功能使用、自定义和高级场景配置。

何时使用本技能

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

• 在 Blazor 项目中安装和配置 MultiSelect Dropdown 组件
• 在表单和应用中实现多项目选择
• 设置集合、API 或远程数据源的数据绑定
• 配置选择模式（Checkbox、Delimiter、Box）
• 为下拉列表添加筛选和分组功能
• 自定义外观、样式和模板
• 实现键盘导航和无障碍功能
• 处理选择事件和以编程方式进行选择
• 支持本地化、RTL 和全球化
• 使用虚拟化优化性能
• 与表单和验证集成

组件概览

主要功能：

• 多项选择：使用多种模式选择一个或多个项目
• 数据源：绑定到集合、API 或自定义数据提供程序
• 筛选：内置搜索，并支持自定义筛选选项
• 分组与排序：按层级组织项目并进行排序
• 自定义模板：设计自定义项目、分组、页眉和页脚模板
• 键盘导航：全面支持键盘操作和无障碍功能（WCAG 2.1）
• 主题：提供 Bootstrap、Material、Fluent、Tailwind 主题，并支持浅色／深色模式
• 验证：支持表单验证和自定义验证器
• RTL 与本地化：支持从右到左的语言和多语言
• 虚拟化：高效处理大型数据集

文档与导航指南

快速入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• 基本的 MultiSelect Dropdown 实现
• 命名空间导入和服务注册
• 应用主题
• 最精简的可运行示例
• 常见设置问题排查

数据绑定

📄 阅读： references/data-binding.md

• 绑定到集合（List、ObservableCollection）
• 远程数据绑定和 API 集成
• 自定义数据适配器和数据源
• 值绑定模式
• 处理 null 和空数据
• 性能注意事项

功能和选择

📄 阅读： references/features-and-selection.md

• 选择模式（Checkbox、Delimiter、Box）
• 单项选择与多项选择
• 全选／取消全选功能
• 以编程方式进行选择和更新值
• 自定义值和自由文本输入
• 默认选中值
• 禁用项和项分组
• 大型数据集的虚拟化

筛选和分组

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

• 启用和配置筛选
• 筛选占位符和防抖延迟
• 自定义筛选实现
• 区分大小写和多字段筛选
• 通过 API 进行远程筛选
• 使用分组标题对数据进行分组
• 在组内排序
• 筛选性能优化

自定义和样式

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

• CSS 类和主题自定义
• 占位符和浮动标签
• 图标支持（前缀／后缀图标）
• 自定义弹出窗口的宽度和高度
• 标签芯片的显示模式和样式
• 弹出窗口定位
• RTL（从右到左）支持
• 深色模式实现
• 自定义 CSS 变量和覆盖样式

无障碍功能和模板

📄 阅读： references/accessibility-and-templates.md

• ARIA 属性和屏幕阅读器支持
• 键盘导航快捷键
• 焦点管理和视觉焦点指示器
• 符合 WCAG 2.1 标准
• 用于自定义项渲染的 ItemTemplate
• 用于自定义组标题的 GroupTemplate
• HeaderTemplate 和 FooterTemplate
• 模板绑定和上下文
• 自定义模板中的无障碍功能

事件和 API 参考

📄 阅读： references/events-and-api.md

• 完整的事件参考（Change、Focus、Blur、Open、Close）
• Blazor 中的事件处理模式
• 事件参数和返回值
• 组件 API 方法（Open、Close、Focus、Refresh）
• 属性访问和状态更新
• 状态管理的响应式模式
• 实际事件处理示例

高级场景

📄 阅读： references/advanced-scenarios.md

• 表单集成和验证
• 本地化和全球化设置
• 自定义值的创建和建议
• 性能优化技巧
• 管理多个下拉列表实例
• 服务端与客户端筛选
• 实际用例和模式
• 边缘情况和故障排除
• 最佳实践和注意事项

快速开始

最简示例

1. 安装 NuGet 包：

dotnet add package Syncfusion.Blazor.DropDowns

2. 添加到 _Imports.razor：

@using Syncfusion.Blazor
@using Syncfusion.Blazor.DropDowns

3. 在 Program.cs 中注册服务：

builder.Services.AddSyncfusionBlazor();

4. 在 App.razor 中添加主题：

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

5. 使用 MultiSelect 下拉列表：

@page "/multiselect-demo"
@using Syncfusion.Blazor.DropDowns

<SfMultiSelect TValue="string[]" 
               TItem="EmployeeData"
               DataSource="@Employees"
               Placeholder="Select employees">
    <MultiSelectFieldSettings Text="Name" Value="ID"></MultiSelectFieldSettings>
</SfMultiSelect>

@code {
    private List<EmployeeData> Employees { get; set; } = new();

    protected override void OnInitialized()
    {
        Employees = new List<EmployeeData>
        {
            new() { ID = "1", Name = "Alice Johnson" },
            new() { ID = "2", Name = "Bob Smith" },
            new() { ID = "3", Name = "Carol White" }
        };
    }

    public class EmployeeData
    {
        public string ID { get; set; }
        public string Name { get; set; }
    }
}

常见模式

模式 1：选择更改时进行双向绑定

@page "/multiselect-binding"
@using Syncfusion.Blazor.DropDowns

<div>
    <p>Selected IDs: @string.Join(", ", SelectedValues)</p>
    <SfMultiSelect TValue="string[]" 
                   TItem="ItemData"
                   DataSource="@Items"
                   @bind-Value="SelectedValues"
                   Placeholder="Select items">
        <MultiSelectFieldSettings Text="Name" Value="ID"></MultiSelectFieldSettings>
    </SfMultiSelect>
</div>

@code {
    private string[] SelectedValues { get; set; } = Array.Empty<string>();
    private List<ItemData> Items { get; set; } = new();

    protected override void OnInitialized()
    {
        Items = new List<ItemData>
        {
            new() { ID = "1", Name = "Item 1" },
            new() { ID = "2", Name = "Item 2" },
            new() { ID = "3", Name = "Item 3" }
        };
    }

    public class ItemData
    {
        public string ID { get; set; }
        public string Name { get; set; }
    }
}

模式 2：使用远程数据进行筛选

<SfMultiSelect TValue="string[]" 
               TItem="RemoteItem"
               DataSource="@RemoteData"
               AllowFiltering="true"
               Mode="VisualMode.CheckBox"
               Placeholder="Search and select">
    <MultiSelectFieldSettings Text="Text" Value="ID"></MultiSelectFieldSettings>
    <MultiSelectEvents TValue="string[]" TItem="RemoteItem" 
                       Filtering="OnFiltering">
    </MultiSelectEvents>
</SfMultiSelect>

@code {
    private List<RemoteItem> RemoteData { get; set; } = new();

    private async Task OnFiltering(FilteringEventArgs args)
    {
        // Filter items based on search text
        args.PreventDefaultAction = true;
        var filtered = RemoteData
            .Where(x => x.Text.Contains(args.Text, StringComparison.OrdinalIgnoreCase))
            .ToList();
        
        // Update DataSource with filtered results
        // (Implementation depends on your component reference handling)
    }

    public class RemoteItem
    {
        public string ID { get; set; }
        public string Text { get; set; }
    }
}

模式 3：在表单中进行自定义验证

<EditForm Model="FormData" OnValidSubmit="HandleSubmit">
    <DataAnnotationsValidator />
    
    <div class="form-group">
        <label>Select at least 2 items:</label>
        <SfMultiSelect TValue="string[]"
                       TItem="ItemData"
                       DataSource="@Items"
                       @bind-Value="FormData.SelectedItems"
                       Placeholder="Select items">
            <MultiSelectFieldSettings Text="Name" Value="ID"></MultiSelectFieldSettings>
        </SfMultiSelect>
        <ValidationMessage For="@(() => FormData.SelectedItems)" />
    </div>
    
    <button type="submit">Submit</button>
</EditForm>

@code {
    private FormModel FormData { get; set; } = new();
    private List<ItemData> Items { get; set; } = new();

    private async Task HandleSubmit()
    {
        // Handle form submission
    }

    public class FormModel
    {
        [Required(ErrorMessage = "Please select items")]
        [MinLength(2, ErrorMessage = "Select at least 2 items")]
        public string[] SelectedItems { get; set; } = Array.Empty<string>();
    }

    public class ItemData
    {
        public string ID { get; set; }
        public string Name { get; set; }
    }
}

关键属性参考

属性	类型	描述	使用场景
DataSource	IEnumerable<TItem>	要显示的项目集合	始终必需
Value	TValue	当前选中的值（数组或集合）	绑定选择项
Placeholder	string	内容为空时显示的占位文本	改善用户体验
AllowFiltering	bool	启用或禁用搜索筛选	用于可搜索列表
Mode	VisualMode	选择项显示模式（Default、Box、Delimiter、CheckBox）	自定义显示样式
Enabled	bool	启用或禁用组件（默认值：true）	条件状态
AllowCustomValue	bool	允许用户输入自定义值	自由输入
EnableVirtualization	bool	为大量数据启用虚拟化	性能优化
PopupHeight	string	下拉弹出窗口的高度（默认值：300px）	自定义外观
PopupWidth	string	下拉弹出窗口的宽度（默认值：100%）	自定义外观
CssClass	string	自定义 CSS 类	自定义样式
ShowSelectAll	bool	在 CheckBox 模式下显示全选选项	批量选择
ShowClearButton	bool	显示清除按钮（默认值：true）	允许清除选择项
ShowDropDownIcon	bool	显示下拉图标（默认值：true）	提供视觉提示
MaximumSelectionLength	int	最多可选择的项目数（默认值：1000）	限制选择项数量
HideSelectedItem	bool	在弹出窗口中隐藏已选项目	保持弹出窗口简洁
EnableSelectionOrder	bool	启用选择顺序显示（默认值：true）	显示选择顺序
EnableCloseOnSelect	bool	选择后自动关闭弹出窗口	提升快速选择体验
DelimiterChar	string	Delimiter 模式下的分隔符（默认值："，"）	自定义分隔符
FilterBarPlaceholder	string	筛选输入框的占位文本	改善筛选体验
FloatLabelType	FloatLabelType	浮动标签行为（Never、Always、Auto）	实现现代表单样式
EnableRtl	bool	支持从右到左书写的语言	用于国际化应用
ReadOnly	bool	只读模式（默认值：false）	仅显示状态
TabIndex	int	Tab 顺序索引（默认值：0）	键盘导航

常见使用场景

场景 1：分配团队时选择员工

• 用户需要为团队选择多名员工
• 使用复选框模式，清晰展示选择项
• 添加筛选功能，便于搜索
• 验证是否满足最低选择数量要求

场景 2：为内容选择类别或标签

• 用户为内容添加多个类别标签
• 使用自定义值添加新标签
• 将已选项目显示为标签块
• 允许使用删除键取消选择

场景 3：按部门或位置进行多条件筛选

• 按多个部门和位置筛选数据
• 使用来自 API 的远程数据源
• 按部门或位置分组
• 以编程方式更新选择项

场景 4：订阅偏好设置

• 用户选择多种通知类型
• 按类别分组（Email、SMS、Push）
• 支持全选和取消全选
• 为国际化应用提供 RTL 支持

---

准备好实现 MultiSelect Dropdown 了吗？ 请从 入门指南 开始进行设置，然后根据具体需求查看其他参考资料。

---

Mention

Mention 组件提供 @mention 功能，可在文本内容中标记用户、项目或实体。用户输入触发字符（默认值：@）时，组件会显示建议列表，方便用户选择并插入标记项。

何时使用此组件

在以下情况下使用 Mention 组件：

• 在评论、聊天或社交功能中添加 @mention 标记
• 在文本区域中标记用户、产品或实体
• 使用触发字符实现自动完成建议
• 创建协作评论系统
• 构建类似社交媒体的提及功能
• 在文本输入中支持基于上下文的项目选择

组件概览

Mention 组件是一个下拉列表，用户输入触发字符（默认值：@）即可从已配置的数据源中提及条目。它会显示经过筛选的建议列表，供用户选择，并自动将提及内容插入目标元素。

主要功能

• 基于触发字符的建议： 用户输入提及字符时显示建议
• 支持多种数据源类型： 支持本地基元、复杂对象、枚举和远程数据
• 高级筛选： 支持 StartsWith、Contains、EndsWith 筛选类型，并可设置最少字符数
• 模板： 自定义条目显示、提及格式、空状态和加载指示器
• 无障碍功能： 完全符合 WCAG 2.2 标准，支持键盘导航和屏幕阅读器
• 远程数据： 支持 OData v4、Web API 适配器和离线模式

---

文档与导航指南

选择以下主题以开始：

📄 入门

阅读： references/getting-started.md

• 安装和包设置（NuGet、主题）
• 创建 Blazor WASM 和 Server 应用程序
• Mention 组件的基本实现
• 配置目标元素（div、textarea、input）
• 初始数据绑定

📄 使用数据

阅读： references/working-with-data.md

• 绑定本地数据（基元、复杂对象、ExpandoObject）
• 枚举数据绑定
• 使用 DataManager 绑定远程数据
• OData v4 和 Web API 适配器
• 用于缓存的离线模式
• 数据获取事件（ActionBegin、ActionComplete、ActionFailure）

📄 筛选与搜索

阅读： references/filtering-and-search.md

• 用于设置最少搜索字符数的 MinLength 属性
• FilterType 选项（StartsWith、Contains、EndsWith）
• 使用 AllowSpaces 进行多词搜索
• 使用 SuggestionCount 限制结果数量

📄 自定义

阅读： references/customization.md

• 使用 ShowMentionChar 在选中的文本中显示提及字符
• 使用 SuffixText 在提及内容后添加空格或换行符
• 弹出窗口尺寸（PopupHeight、PopupWidth）
• 自定义提及触发字符
• 使用 RequireLeadingSpace 要求触发字符前有空格

📄 模板与显示

阅读： references/templates.md

• 使用 ItemTemplate 自定义建议列表样式
• 使用 DisplayTemplate 格式化提及内容的显示
• 使用 NoRecordsTemplate 设置空状态
• 使用 SpinnerTemplate 设置加载状态
• 模板上下文访问和数据使用

📄 无障碍功能

阅读： references/accessibility.md

• WCAG 2.2 合规详情
• WAI-ARIA 属性（aria-selected、aria-activedescendent）
• 键盘导航快捷键
• 屏幕阅读器支持
• 移动设备和 RTL 语言支持

快速入门示例

<SfMention TItem="PersonData" DataSource="@TeamMembers">
    <TargetComponent>
        <textarea id="mentionTarget" placeholder="Type @ to mention someone"></textarea>
    </TargetComponent>
    <ChildContent>
        <MentionFieldSettings Text="Name"></MentionFieldSettings>
    </ChildContent>
</SfMention>

<style>
    #mentionTarget {
        min-height: 100px;
        border: 1px solid #D7D7D7;
        border-radius: 4px;
        padding: 8px;
        font-size: 14px;
        width: 100%;
    }
</style>

@code {
    public class PersonData
    {
        public string Name { get; set; }
        public string Email { get; set; }
    }

    List<PersonData> TeamMembers = new List<PersonData>
    {
        new PersonData { Name = "Alice Johnson", Email = "[email protected]" },
        new PersonData { Name = "Bob Smith", Email = "[email protected]" },
        new PersonData { Name = "Carol White", Email = "[email protected]" }
    };
}

---

常见模式

模式 1：带用户提及功能的评论区

<SfMention TItem="UserData" DataSource="@AllUsers" MentionChar="@MentionCharAt">
    <TargetComponent>
        <div id="comments" contenteditable="true" placeholder="Type @ to mention..."></div>
    </TargetComponent>
    <ChildContent>
        <MentionFieldSettings Text="UserName"></MentionFieldSettings>
    </ChildContent>
</SfMention>

@code {
    private char MentionCharAt = '@';
}

模式 2：使用远程数据筛选建议

<SfMention TItem="EmployeeData" MentionChar="@MentionCharAt" MinLength="2" FilterType="FilterType.StartsWith">
    <TargetComponent>
        <input id="employeeInput" type="text" placeholder="Search employees..." />
    </TargetComponent>
    <ChildContent>
        <SfDataManager Url="YOUR_API_ENDPOINT" Adaptor="Adaptors.WebApiAdaptor"></SfDataManager>
        <MentionFieldSettings Text="Name"></MentionFieldSettings>
    </ChildContent>
</SfMention>

@code {
    private char MentionCharAt = '@';
}

模式 3：使用模板自定义显示

<SfMention TItem="PersonData" DataSource="@TeamMembers" MentionChar="@MentionCharAt">
    <TargetComponent>
        <div id="mentionDiv" contenteditable="true"></div>
    </TargetComponent>
    <ItemTemplate>
        <div class="mention-item">
            <span>@((context as PersonData).Name)</span>
            <small>@((context as PersonData).Email)</small>
        </div>
    </ItemTemplate>
    <DisplayTemplate>
        <span class="mentioned-user">@((context as PersonData).Name)</span>
    </DisplayTemplate>
    <ChildContent>
        <MentionFieldSettings Text="Name"></MentionFieldSettings>
    </ChildContent>
</SfMention>

@code {
    private char MentionCharAt = '@';
}

---

关键属性

属性	类型	默认值	用途
TItem	泛型	-	数据源项类型
DataSource	IEnumerable	-	本地数据集合
MentionChar	char	'@'	触发建议的字符
Target	string	-	目标元素的 CSS 选择器
MinLength	int	0	显示建议所需的最少字符数
FilterType	FilterType	Contains	搜索筛选模式（StartsWith、Contains、EndsWith）
AllowSpaces	bool	false	允许在提及搜索中使用空格
ShowMentionChar	bool	false	在提及内容中显示触发字符
SuffixText	string	-	在提及内容后追加的文本（空格、换行符）
RequireLeadingSpace	bool	false	要求提及字符前有空格
PopupHeight	string	300px	建议列表高度
PopupWidth	string	auto	建议列表宽度
SuggestionCount	int	25	建议列表中的最大项数

---

常见用例

评论中的用户标记

• 创建协作工具，让用户在评论中提及 @username
• 与 DisplayTemplate 配合使用，以显示用户头像
• 使用远程数据绑定动态获取团队成员

任务分配通知

• 分配任务时提及团队成员
• 自定义 MentionChar，用 # 表示任务，用 @ 表示用户
• 使用 ActionComplete 事件记录提及内容以发送通知

代码或实体引用

• 使用 Mention 引用代码片段（#snippet）
• 在文档中提及实体或资源
• 支持为预定义实体进行枚举数据绑定

多目标提及

• 在同一页面的多个文本区域中实现提及支持
• 每个 Mention 组件都可以指定不同的目标元素
• 使用 Target 属性和唯一的 CSS 选择器

---

后续步骤

1. 从这里开始： 阅读入门指南，了解安装和设置
2. 绑定数据： 阅读使用数据，了解本地和远程数据源
3. 增强用户体验： 查看筛选与搜索和模板
4. 确保无障碍访问： 查看无障碍访问，了解包容性设计
5. 微调： 使用自定义调整外观和行为

---

如需更多帮助：

• 官方文档：https://blazor.syncfusion.com/documentation/mention/getting-started
• API 参考：https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfMention-1.html
• 社区支持：https://www.syncfusion.com/forums/blazor

---

列表框

一项全面的技能，介绍如何在 Blazor 应用中实现和使用 SfListBox 组件。列表框会显示可滚动的项目列表，并支持单选和多选、复选框、筛选、拖放、图标和自定义模板。

何时使用此技能

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

• 安装与设置

  • 安装 Syncfusion.Blazor.DropDowns NuGet 包
  • 注册服务并配置主题
  • 设置 Blazor WebAssembly、Server 或 Web App 项目

• 数据绑定

  • 将字符串或对象数组绑定到 ListBox
  • 将复杂的嵌套对象映射为列表项
  • 从远程数据源（DataManager、API）加载数据
  • 动态更新数据

• 选择与交互

  • 实现单选或多选模式
  • 添加复选框以选择项目
  • 启用“全选”功能
  • 设置最大选择数量
  • 获取选中的项目和值
  • 处理选择变更事件

• 功能与自定义

  • 启用筛选和搜索功能
  • 实现拖放排序
  • 创建双列表框模式（源/目标）
  • 启用或禁用特定项目
  • 添加图标和自定义模板
  • 应用排序和分组

• 样式与外观

  • 应用主题（Bootstrap、Material、Fluent、Tailwind）
  • 自定义 CSS 和样式
  • 创建响应式布局
  • 实现深色模式

• 无障碍

  • 确保符合 WCAG 2.1 标准
  • 配置键盘导航
  • 添加 ARIA 标签和角色
  • 支持屏幕阅读器

组件概览

SfListBox 组件是一种灵活的下拉列表替代方案，可滚动显示列表项。

主要特性：

• TValue：所选值的类型参数（例如，string[]、int[]）
• TItem：数据源项目的类型参数
• 多选：默认行为；支持单选模式
• 复选框支持：可选复选框，用于选择项目
• 字段映射：将数据对象属性映射为显示内容和值
• 模板：支持自定义项目模板，实现丰富的格式
• 数据绑定：支持本地数组、对象和远程数据
• 事件：用于处理交互的变更、选择和焦点事件

快速入门示例

@using Syncfusion.Blazor.DropDowns

<SfListBox TValue="string[]" DataSource="@Items" TItem="string"></SfListBox>

@code {
    public string[] Items = new string[] { "Apple", "Banana", "Orange", "Mango", "Grape" };
}

使用数据绑定：

<SfListBox TValue="string[]" DataSource="@Vehicles" TItem="VehicleData">
    <ListBoxFieldSettings Text="Text" Value="Id" />
</SfListBox>

@code {
    public List<VehicleData> Vehicles = new List<VehicleData>
    {
        new VehicleData { Text = "Hennessey Venom", Id = "Vehicle-01" },
        new VehicleData { Text = "Bugatti Chiron", Id = "Vehicle-02" },
        new VehicleData { Text = "McLaren F1", Id = "Vehicle-03" }
    };

    public class VehicleData
    {
        public string Text { get; set; }
        public string Id { get; set; }
    }
}

重要属性与事件

重要属性：

• DataSource - 要显示的项目数组或列表
• TValue - 所选值的类型（string[]、int[] 等）
• TItem - 数据源项目的类型
• Value - 当前选中的值（支持双向绑定）
• MaximumSelectionLength - 限制选择数量（默认值：500）
• Enabled - 启用或禁用组件
• AllowFiltering - 启用搜索/筛选功能
• Allowdragging - 启用拖放排序

选择设置：

• Mode - SelectionMode.Single 或 SelectionMode.Multiple
• ShowCheckbox - 显示用于选择的复选框
• ShowSelectAll - 显示“全选”复选框

常见事件：

• ValueChange - 所选值变更时触发
• Change - 项目选择发生变更时触发
• Select - 选中项目时触发

常见模式

1. 单选模式

<ListBoxSelectionSettings Mode="Syncfusion.Blazor.DropDowns.SelectionMode.Single" />

2. 使用复选框进行多选

<ListBoxSelectionSettings ShowCheckbox="true" ShowSelectAll="true" />

3. 获取选中的值

@bind-Value="@SelectedValues"

@code {
    public string[] SelectedValues { get; set; }
}

4. 处理选择变更

<SfListBox ValueChange="@OnSelectionChanged" ...>
</SfListBox>

@code {
    private void OnSelectionChanged(ChangeEventArgs args)
    {
        var selectedValues = args.Value as string[];
        // Process selected values
    }
}

5. 启用筛选

<SfListBox AllowFiltering="true" FilterType="FilterType.Contains" ... >
</SfListBox>

文档与导航指南

选择与当前任务相符的参考文档：

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• 项目配置（WebAssembly、Server、Web App）
• 基本组件标记和第一个示例
• 主题配置和样式表
• 运行并测试第一个 ListBox

数据绑定

📄 阅读： references/data-binding.md

• 绑定字符串数组
• 使用字段映射绑定对象数组
• 绑定复杂的嵌套对象
• 使用 DataManager 加载远程数据
• 动态更新数据
• 数据绑定最佳实践

选择与模式

📄 阅读： references/selection-and-modes.md

• 单选配置
• 多选（默认模式）
• 使用 ShowCheckbox 复选框选择
• 全选功能
• 获取已选项目和数值
• MaximumSelectionLength 限制
• 选择变更事件
• 常见选择模式

功能与交互

📄 阅读： references/features-and-interactions.md

• 筛选和搜索功能
• 拖放排序（Allowdragging）
• 启用/禁用项目功能
• 图标和图标 CSS 类
• 用于自定义呈现的项目模板
• 对数据进行排序和分组
• 双 ListBox 模式（从源列表到目标列表）
• 无障碍属性

样式与外观

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

• 应用主题（Bootstrap、Material、Fluent、Tailwind）
• 自定义 CSS 类
• 用于样式设置的自定义项目模板
• 集成和设置图标样式
• 深色模式实现
• 响应式设计模式
• 布局和尺寸

无障碍与事件

📄 阅读： references/accessibility-and-events.md

• WCAG 2.1 合规指南
• 键盘导航支持
• ARIA 标签和角色
• 事件绑定（ValueChange、Change、Select）
• 事件处理模式
• 焦点管理
• 屏幕阅读器支持
• 常见无障碍模式

用例示例

根据你的场景选择参考内容：

• “我需要在 Blazor 项目中添加 ListBox” → 入门指南
• “如何将数据绑定到 ListBox？” → 数据绑定
• “我希望用户通过复选框选择多个项目” → 选择与模式
• “我可以让用户搜索/筛选列表吗？” → 功能与交互
• “如何自定义颜色和样式？” → 样式与外观
• “ListBox 支持键盘导航吗？” → 无障碍与事件
• “我需要源列表/目标列表模式的 ListBox” → 功能与交互

后续步骤

1. 刚开始使用 ListBox？ 从入门指南开始
2. 有要绑定的数据？ 前往数据绑定
3. 需要多选？ 查看选择与模式
4. 想使用高级功能？ 探索功能与交互
5. 想让它看起来更美观？ 阅读样式与外观
6. 需要无障碍支持？ 查看无障碍与事件