syncfusion-blazor-dropdowns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Blazor Dropdowns

实现Syncfusion Blazor下拉组件

AutoComplete

The AutoComplete component provides intelligent search suggestions as users type, supporting local and remote data sources with advanced filtering, customization, and accessibility features.

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

Component Overview

组件概述

The SfAutoComplete component enables:

Data Binding: Local primitives, objects, or remote data sources
Filtering: Real-time search with debounce, filter types (StartsWith, Contains, EndsWith)
Organization: Grouping, sorting, multicolumn display
Customization: Item/group/header/footer templates, styling, placeholders
Performance: Virtualization for large datasets
Accessibility: WCAG compliance, keyboard navigation, ARIA support
Interactions: Events, disabled items, custom values, RTL support

SfAutoComplete组件支持：

数据绑定：本地基本类型、对象或远程数据源
过滤：带防抖功能的实时搜索，支持多种过滤类型（StartsWith、Contains、EndsWith）
数据组织：分组、排序、多列显示
自定义：项/组/页眉/页脚模板、样式、占位符
性能优化：大数据集虚拟化
无障碍支持：符合WCAG标准、键盘导航、ARIA支持
交互能力：事件处理、禁用项、自定义值、RTL支持

Documentation Navigation Guide

文档导航指南

Choose the reference that matches your current task:

根据当前任务选择对应的参考文档：

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation of NuGet packages
Project setup (Visual Studio, VS Code, .NET CLI)
Basic autocomplete implementation
CSS imports and theme setup
Initial configuration

📄 阅读：references/getting-started.md

NuGet包安装
项目配置（Visual Studio、VS Code、.NET CLI）
基础AutoComplete实现
CSS导入和主题配置
初始设置

Data Binding & Sources

数据绑定与数据源

📄 Read: references/data-binding.md

Binding local data (primitives, objects, ObservableCollection)
Complex data types (ExpandoObject, DynamicObject)
Remote data with DataManager
ODataAdaptor, Web API, and custom adaptors
DataBound event handling

📄 阅读：references/data-binding.md

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

Filtering & Search

过滤与搜索

📄 Read: references/filtering-and-search.md

Enabling and configuring filtering
Filter types (StartsWith, Contains, EndsWith)
Local vs. remote data filtering
DebounceDelay for performance
Minimum character length
Highlight search results

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

启用并配置过滤功能
过滤类型（StartsWith、Contains、EndsWith）
本地与远程数据过滤对比
防抖延迟优化性能
触发过滤的最小字符长度
搜索结果高亮

Data Organization

数据组织

📄 Read: references/data-organization.md

Grouping data by categories
Sorting list items
Multicolumn display
Selection and selection modes
Value binding and custom values

📄 阅读：references/data-organization.md

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

Templates & Styling

模板与样式

📄 Read: references/templates-and-styling.md

Item templates (custom list item layout)
Group templates (group header customization)
Header, footer, and no-records templates
CSS class styling
Placeholder and FloatLabel customization

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

项模板（自定义列表项布局）
组模板（自定义组页眉）
页眉、页脚和无数据模板
CSS类样式定制
占位符和FloatLabel自定义

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Virtualization for large datasets
Popup settings and positioning
Disabled items handling
Custom values support
Localization and RTL support
Event handling (ActionBegin, ActionComplete, ValueChange, etc.)

📄 阅读：references/advanced-features.md

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

Accessibility & Best Practices

无障碍与最佳实践

📄 Read: references/accessibility-and-best-practices.md

WCAG compliance and accessibility standards
ARIA attributes
Keyboard navigation support
Screen reader compatibility
Performance optimization tips
Common issues and troubleshooting

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

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

Quick Start Example

快速入门示例

A minimal AutoComplete implementation with local data:

blazor

@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" }
    };
}

基于本地数据的最简AutoComplete实现：

blazor

@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" }
    };
}

Common Patterns

常见模式

Pattern 1: Filtering User Input

模式1：过滤用户输入

Enable real-time filtering as users type:

blazor

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

启用实时输入过滤：

blazor

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

Pattern 2: Remote Data with Debounce

模式2：带防抖的远程数据

Reduce server requests with debounce delay:

blazor

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

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

blazor

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

Pattern 3: Custom Item Display with Templates

模式3：自定义项显示模板

Customize list item appearance:

blazor

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

自定义列表项外观：

blazor

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

Pattern 4: Grouped & Sorted Display

模式4：分组与排序显示

Organize data with grouping and sorting:

blazor

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

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

blazor

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

Key Props

关键属性

Prop	Type	Purpose
`DataSource`	`IEnumerable<TItem>`	Source data for suggestions
`AllowFiltering`	`bool`	Enable/disable filtering
`FilterType`	`FilterType`	Filter mode (StartsWith, Contains, EndsWith)
`DebounceDelay`	`int`	Delay in ms before filter triggers
`MinLength`	`int`	Min characters to trigger filtering
`SortOrder`	`SortOrder`	Sort list items (Ascending, Descending)
`EnableVirtualization`	`bool`	Virtualize large datasets
`AllowCustom`	`bool`	Allow users to enter custom values
`Placeholder`	`string`	Input placeholder text
`FloatLabelType`	`FloatLabelType`	Floating label behavior

属性	类型	用途
`DataSource`	`IEnumerable<TItem>`	建议项的数据源
`AllowFiltering`	`bool`	启用/禁用过滤功能
`FilterType`	`FilterType`	过滤模式（StartsWith、Contains、EndsWith）
`DebounceDelay`	`int`	过滤触发前的延迟（毫秒）
`MinLength`	`int`	触发过滤的最小字符数
`SortOrder`	`SortOrder`	列表项排序方式（升序、降序）
`EnableVirtualization`	`bool`	启用大数据集虚拟化
`AllowCustom`	`bool`	允许用户输入自定义值
`Placeholder`	`string`	输入框占位文本
`FloatLabelType`	`FloatLabelType`	浮动标签行为

Common Use Cases

常见使用场景

Search-as-you-type: Autocomplete on employee names, products, locations
Filtered dropdowns: Show matching items as users filter
Remote APIs: Fetch suggestions from backend services
Multi-column display: Show product details alongside names
Grouped suggestions: Organize by category or department
Custom values: Allow users to create new entries
Large datasets: Virtualize for performance with 1000+ items

Next Steps: Start with getting-started.md for setup, or jump to the reference that matches your task.

输入即搜索：员工姓名、产品、地点的自动完成
过滤下拉框：用户过滤时显示匹配项
远程API调用：从后端服务获取建议项
多列显示：在名称旁显示产品详情
分组建议：按类别或部门组织建议项
自定义值：允许用户创建新条目
大数据集：虚拟化处理1000+条目的性能优化

下一步：从getting-started.md开始配置，或直接跳转到与任务匹配的参考文档。

ComboBox

A comprehensive skill for implementing the ComboBox component. The ComboBox allows users to select a value from a dropdown list while also providing filtering, custom templates, cascading scenarios, data binding, and extensive customization options.

这是一份关于实现ComboBox组件的全面指南。ComboBox允许用户从下拉列表中选择值，同时支持过滤、自定义模板、级联场景、数据绑定和丰富的自定义选项。

When to Use This Skill

使用场景

Use this skill when you need to:

Install and set up the ComboBox component
Implement ComboBox with local or remote data sources
Configure data binding (primitive types, complex objects, collections)
Enable and configure filtering and search functionality
Handle value selection and change events
Create cascading ComboBox scenarios (dependent dropdowns)
Customize appearance with templates (items, header, footer)
Integrate ComboBox with form validation (EditForm, data annotations)
Configure popup settings (height, width, resize, positioning)
Apply grouping and sorting to ComboBox data
Handle events (ValueChange, OnValueSelect, Blur, etc.)
Implement accessibility and keyboard navigation
Customize styling and themes
Troubleshoot common ComboBox issues

当你需要以下功能时使用本指南：

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

Quick Start Example

快速入门示例

razor

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

razor

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

Key Props Reference

关键属性参考

Property	Type	Purpose
`TValue`	Generic	Type of the selected value
`TItem`	Generic	Type of data items in the list
`DataSource`	IEnumerable	List of items to display
`@bind-Value`	TValue	Two-way binding for selected value
`@bind-Index`	int?	Two-way binding for selected index
`Placeholder`	string	Hint text when no value selected
`AllowFiltering`	bool	Enable/disable filtering
`AllowCustom`	bool	Allow free-text entry
`Readonly`	bool	Make component read-only
`Disabled`	bool	Disable the component

属性	类型	用途
`TValue`	泛型	选中值的类型
`TItem`	泛型	列表中数据项的类型
`DataSource`	IEnumerable	要显示的项列表
`@bind-Value`	TValue	选中值的双向绑定
`@bind-Index`	int?	选中索引的双向绑定
`Placeholder`	string	未选中时的提示文本
`AllowFiltering`	bool	启用/禁用过滤
`AllowCustom`	bool	允许自由文本输入
`Readonly`	bool	设置组件为只读
`Disabled`	bool	禁用组件

Common Patterns

常见模式

Pattern 1: Basic Data Binding

模式1：基础数据绑定

Bind ComboBox to local list with primitive or complex types. Use

ComboBoxFieldSettings

to map text/value fields.

将ComboBox绑定到本地列表（基本类型或复杂类型），使用

ComboBoxFieldSettings

映射文本/值字段。

Pattern 2: Filtering & Search

模式2：过滤与搜索

Enable

AllowFiltering

to let users filter data as they type. Control filter behavior with

FilterType

and

DebounceDelay

启用

AllowFiltering

让用户输入时过滤数据，通过

FilterType

和

DebounceDelay

控制过滤行为。

Pattern 3: Cascading ComboBox

模式3：级联ComboBox

Use

ValueChange

event in parent ComboBox to populate child ComboBox data dynamically based on parent selection.

使用父ComboBox的

ValueChange

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

Pattern 4: Form Integration

模式4：表单集成

Wrap ComboBox in EditForm with data annotations for automatic validation. Use

ValidationMessage

to display errors.

将ComboBox包裹在EditForm中，结合数据注解实现自动验证，使用

ValidationMessage

显示错误信息。

Pattern 5: Custom Templates

模式5：自定义模板

Use

ItemTemplate

HeaderTemplate

FooterTemplate

to create custom UI for list items and popup sections.

使用

ItemTemplate

、

HeaderTemplate

、

FooterTemplate

为列表项和弹窗区域创建自定义UI。

Documentation Navigation Guide

文档导航指南

Read the appropriate reference file based on your task:

根据任务选择对应的参考文档：

📄 Getting Started

📄 快速入门

Read: references/getting-started.md

Installation and NuGet packages
Basic ComboBox implementation
Web App vs Server App setup
CSS imports and themes
First working example

阅读：references/getting-started.md

安装和NuGet包配置
基础ComboBox实现
Web应用与服务器应用的设置差异
CSS导入和主题配置
第一个可运行示例

📄 Data Binding

📄 数据绑定

Read: references/data-binding.md

Local data binding (arrays, lists, collections)
Primitive type vs complex object binding
Index-based value binding
Remote data with DataManager
OData and Web API adaptors
Custom data adaptors
Dynamic object binding scenarios

阅读：references/data-binding.md

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

📄 Filtering & Search

📄 过滤与搜索

Read: references/filtering.md

Enable filtering with
```
AllowFiltering
```
Local vs remote data filtering
Filter types (contains, startsWith, endsWith)
Custom filtering logic
Debounce delay for performance
Case-sensitive filtering options

阅读：references/filtering.md

使用
```
AllowFiltering
```
启用过滤
本地与远程数据过滤对比
过滤类型（contains、startsWith、endsWith）
自定义过滤逻辑
防抖延迟优化性能
区分大小写的过滤选项

📄 Selection & Value Binding

📄 选择与值绑定

Read: references/selection-and-value.md

Get and set selected value
Value vs Index binding
Preselected values on initialization
Programmatic value changes
Selection events (ValueChange, OnValueSelect)
Autofill functionality

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

获取和设置选中值
值绑定与索引绑定对比
初始化时设置预选中值
程序化修改值
选择事件（ValueChange、OnValueSelect）
自动填充功能

📄 Cascading ComboBox

📄 级联ComboBox

Read: references/cascading-combobox.md

Create dependent/cascading ComboBox chains
Populate child ComboBox based on parent selection
Multi-level cascading (3+ levels)
Populate other form fields from selection
Real-world examples

阅读：references/cascading-combobox.md

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

📄 Templates & Customization

📄 模板与自定义

Read: references/templates-and-customization.md

Item templates for custom list rendering
Group templates for grouped data
Header and footer templates
Value template customization
HTML content in templates
Template debugging tips

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

自定义列表渲染的项模板
分组数据的组模板
页眉和页脚模板
值模板自定义
模板中的HTML内容
模板调试技巧

📄 Events & Validation

📄 事件与验证

Read: references/events-and-validation.md

ComboBox events (Creating, Created, Blur, etc.)
ValueChange and OnValueSelect events
Form validation with EditForm
Data annotations and validation rules
Custom validation logic
Preventing operations with event cancellation

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

ComboBox事件（Creating、Created、Blur等）
ValueChange和OnValueSelect事件
结合EditForm的表单验证
数据注解和验证规则
自定义验证逻辑
通过事件取消操作

📄 Popup & Appearance

📄 弹窗与外观

Read: references/popup-and-appearance.md

Popup height and width configuration
Popup positioning and z-index
Popup open/close events
Allow popup resize
Show popup on initial load
Placeholder and FloatLabel
CSS classes and styling

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

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

📄 Advanced Features

📄 高级功能

Read: references/advanced-features.md

Grouping data by category
Sorting options and custom sort order
Virtualization for large datasets
Disabled items in the list
RTL (right-to-left) support
Accessibility (WCAG compliance)
Keyboard navigation

阅读：references/advanced-features.md

按类别分组数据
排序选项和自定义排序顺序
大数据集虚拟化
列表中的禁用项
RTL（从右到左）支持
无障碍（WCAG合规性）
键盘导航

📄 Troubleshooting

📄 故障排除

Read: references/troubleshooting.md

Data not loading or empty list
Filtering not working as expected
Selection/binding issues
Event handlers not firing
Performance optimization tips
Common errors and solutions

阅读：references/troubleshooting.md

数据未加载或列表为空
过滤功能不符合预期
选择/绑定问题
事件处理器未触发
性能优化技巧
常见错误与解决方案

Common Use Cases

常见使用场景

Use Case 1: Country/State/City Selection

Create 3-level cascading ComboBox
User selects country → states populate → cities populate
See: Cascading ComboBox + Events & Validation

Use Case 2: Search/Filter List with Custom Display

Enable filtering with custom templates
Show complex data (icons, descriptions, colors)
See: Filtering & Search + Templates & Customization

Use Case 3: Form with Multiple Dropdowns

Integrate ComboBox into EditForm
Validate selections with data annotations
Cascade between dropdowns
See: Events & Validation + Cascading ComboBox

Use Case 4: Large Dataset Performance

Bind to 1000+ items with virtualization
Enable remote filtering via API
Configure debounce delay
See: Advanced Features + Data Binding

场景1：国家/州/城市选择

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

场景2：带自定义显示的搜索/过滤列表

启用过滤并结合自定义模板
显示复杂数据（图标、描述、颜色）
参考：过滤与搜索 + 模板与自定义

场景3：包含多个下拉框的表单

将ComboBox集成到EditForm中
使用数据注解验证选择
下拉框之间的级联
参考：事件与验证 + 级联ComboBox

场景4：大数据集性能优化

绑定1000+条数据并启用虚拟化
通过API启用远程过滤
配置防抖延迟
参考：高级功能 + 数据绑定

Key Features Summary

关键功能汇总

✅ Local & Remote Data Binding - Support for arrays, lists, observables, DataManager
✅ Flexible Filtering - Built-in filtering with customization options
✅ Templates - Item, group, header, footer templates for custom UI
✅ Cascading - Create dependent dropdown chains
✅ Form Integration - Native EditForm and validation support
✅ Events - Rich event system for user interactions
✅ Accessibility - WCAG compliance, keyboard navigation
✅ Customization - Theming, styling, CSS classes
✅ Performance - Virtualization support for large lists
✅ RTL Support - Right-to-left language support

✅ 本地与远程数据绑定 - 支持数组、列表、可观察对象、DataManager
✅ 灵活过滤 - 内置过滤功能并支持自定义选项
✅ 模板支持 - 项、组、页眉、页脚模板实现自定义UI
✅ 级联功能 - 创建依赖下拉框链
✅ 表单集成 - 原生EditForm和验证支持
✅ 丰富事件 - 覆盖用户交互的事件系统
✅ 无障碍支持 - WCAG合规、键盘导航
✅ 高度自定义 - 主题、样式、CSS类定制
✅ 性能优化 - 大数据集虚拟化支持
✅ RTL支持 - 从右到左语言支持

Related Components

DropDown List

A comprehensive skill for implementing the Syncfusion DropDown List component in Blazor applications. This component provides flexible item selection with support for data binding, filtering, templating, cascading, and extensive customization options.

这是一份关于在Blazor应用中实现Syncfusion DropDown List组件的全面指南。该组件提供灵活的项选择功能，支持数据绑定、过滤、模板、级联和丰富的自定义选项。

When to Use This Skill

使用场景

Use this skill when you need to:

Create a dropdown list component for item selection in Blazor
Bind dropdown data from local collections or remote APIs
Implement filtering and search functionality
Customize dropdown rendering with templates
Handle selection events and value binding
Create cascading dropdown relationships
Group and sort dropdown items
Implement form validation with dropdown selection
Apply styling and theming to dropdowns
Support accessibility and keyboard navigation
Enable RTL (Right-to-Left) support for localization
Manage large datasets with virtualization
Configure popup behavior and positioning
Handle disabled items and placeholders

当你需要以下功能时使用本指南：

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

Component Overview

组件概述

Key Capabilities:

Multiple Selection: Select one or many items using various modes
Data Sources: Bind to collections, APIs, or custom data providers
Filtering: Built-in search with customizable filter options
Grouping & Sorting: Organize items hierarchically with sorting
Custom Templates: Design custom item, group, header, and footer templates
Keyboard Navigation: Full keyboard support and accessibility (WCAG 2.1)
Theming: Bootstrap, Material, Fluent, Tailwind themes with light/dark modes
Validation: Form validation support with custom validators
RTL & Localization: Right-to-left language support and multi-language
Virtualization: Handle large datasets efficiently

核心能力：

多选功能：使用多种模式选择一个或多个项
数据源：绑定到集合、API或自定义数据提供程序
过滤：内置搜索功能，支持自定义过滤选项
分组与排序：通过排序分层组织项
自定义模板：设计自定义项、组、页眉和页脚模板
键盘导航：完整的键盘支持和无障碍（WCAG 2.1）
主题支持：Bootstrap、Material、Fluent、Tailwind主题，支持明暗模式
验证：表单验证支持，包含自定义验证器
RTL与本地化：从右到左语言支持和多语言适配
虚拟化：高效处理大数据集

Documentation and Navigation Guide

文档导航指南

Getting Started

快速入门

📄 Read: references/getting-started-dropdown-list.md

Installation and NuGet package setup
Basic component implementation
CSS theme imports
Minimal working example
Rendering the dropdown

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

安装和NuGet包配置
基础组件实现
CSS主题导入
最简运行示例
渲染下拉框

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding local collections (primitives, complex types, observables)
Remote data binding with Web API and OData
Data source events (OnActionBegin, OnActionComplete)
Dynamic and enum data binding
Value tuple and expando object binding

📄 阅读：references/data-binding.md

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

Filtering and Searching

过滤与搜索

📄 Read: references/filtering-and-searching.md

Filter types and strategies
Case-sensitive filtering
Minimum filter length configuration
Debounce delay for performance optimization
Multi-column filtering
Custom filtering logic

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

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

Templates and Rendering

模板与渲染

📄 Read: references/templates-and-rendering.md

Item template customization
Header and footer templates
Value template for selection display
Conditional rendering in templates
Complex template patterns

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

项模板自定义
页眉和页脚模板
选择显示的值模板
模板中的条件渲染
复杂模板模式

Selection and Value Binding

选择与值绑定

📄 Read: references/selection-and-value-binding.md

Getting and setting selected values
Value binding with @bind-Value directive
Value changed events
Clearing and resetting selection
Working with complex object selections

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

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

Customization and Styling

自定义与样式

📄 Read: references/customization-and-styling.md

Opening dropdown on focus
CSS class application
Theme application and switching
Component sizing and appearance
Styling open and closed states

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

获取焦点时打开下拉框
CSS类应用
主题应用与切换
组件尺寸和外观
打开和关闭状态的样式定制

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Cascading dropdowns for dependent selections
Item grouping and organization
Sorting and ordering options
Disabled items and states
Placeholder text and float label
Popup settings and positioning
Virtualization for large datasets

📄 阅读：references/advanced-features.md

用于依赖选择的级联下拉框
项分组和组织
排序和排序选项
禁用项和状态
占位文本和浮动标签
弹窗设置和定位
大数据集虚拟化

Form Validation

表单验证

📄 Read: references/form-validation.md

EditForm integration
Data annotation validation
Validation error display
Custom validation rules
Form submission patterns

📄 阅读：references/form-validation.md

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

Localization and RTL

本地化与RTL

📄 Read: references/localization-and-rtl.md

RTL (Right-to-Left) support
Localization patterns
Culture-specific formatting
Multi-language support

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

RTL（从右到左）支持
本地化模式
特定文化格式
多语言支持

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.1 compliance
WAI-ARIA attributes and roles
Keyboard navigation (Arrow keys, Enter, Escape)
Screen reader compatibility
Focus management
High contrast support

📄 阅读：references/accessibility.md

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

Quick Start

快速入门

Basic Dropdown Implementation

基础下拉框实现

razor

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

razor

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

With Value Binding and Selection Event

带值绑定和选择事件的实现

razor

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

razor

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

Common Patterns

常见模式

Pattern 1: Dropdown with Filtering

模式1：带过滤的下拉框

Enable filter-as-you-type functionality to let users quickly find items in large lists:

razor

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

启用输入过滤功能，让用户快速在大列表中找到项：

razor

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

Pattern 2: Cascading Dropdowns

模式2：级联下拉框

Create dependent dropdowns where selection in one dropdown affects the options in another:

razor

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

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

razor

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

Pattern 3: Remote Data Binding

模式3：远程数据绑定

Connect to APIs for dynamic data loading:

razor

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

连接API加载动态数据：

razor

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

Pattern 4: Custom Item Template

模式4：自定义项模板

Use templates to display rich content in dropdown items:

razor

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

使用模板在下拉项中显示富内容：

razor

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

Pattern 5: Form Validation

模式5：表单验证

Integrate with EditForm for validation:

razor

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

集成到EditForm中实现验证：

razor

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

Key Props and Events

关键属性与事件

Essential Properties

核心属性

Property	Description
`DataSource`	`IEnumerable<T>` Collection of items to display
`Value` / `@bind-Value`	`TValue` Currently selected value
`Placeholder`	`string` Hint text when no selection
`AllowFiltering`	`bool` Enable search/filter functionality
`FilterType`	`FilterType` Filter strategy (StartsWith, Contains, EndsWith)
`Enabled`	`bool` Enable or disable the dropdown
`EnableRtl`	`bool` Right-to-Left text direction
`Width`	`string` Component width (px, %, etc.)

Field mapping: Use the
<DropDownListFieldSettings Text="..." Value="..." />
child component tag to map data fields.

属性	描述
`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="..." />
子组件标签映射数据字段。

Essential Events (inside

<DropDownListEvents>

)

核心事件（在

<DropDownListEvents>

内）

Event	Description
`ValueChange`	Triggered when selected value changes
`OnActionBegin`	Before remote data fetch begins
`OnActionComplete`	After remote data fetch completes
`OnActionFailure`	When remote data fetch fails
`OnOpen`	When dropdown opens
`OnClose`	When dropdown closes
`Focus`	When component receives focus
`Blur`	When component loses focus

事件	描述
`ValueChange`	选中值变更时触发
`OnActionBegin`	远程数据获取开始前触发
`OnActionComplete`	远程数据获取完成后触发
`OnActionFailure`	远程数据获取失败时触发
`OnOpen`	下拉框打开时触发
`OnClose`	下拉框关闭时触发
`Focus`	组件获取焦点时触发
`Blur`	组件失去焦点时触发

Common Use Cases

常见使用场景

User Selection in Forms - Select users from a list for assignment or notification
Category/Type Selection - Choose from predefined categories or types
Cascading Selections - Dependent dropdowns (Country → State → City)
Dynamic Data from APIs - Load options from backend services
Searchable Lists - Filter through large datasets efficiently
Multi-stage Workflows - Selection-based form navigation
Data Filtering - Apply filters based on dropdown selection
Templated Dropdowns - Display rich content (images, descriptions)
Localized Selections - Region/language-specific options
Accessibility-Compliant Forms - WCAG-compliant selection interface

表单中的用户选择 - 从列表中选择用户进行分配或通知
类别/类型选择 - 从预定义类别或类型中选择
级联选择 - 依赖下拉框（国家→州→城市）
来自API的动态数据 - 从后端服务加载选项
可搜索列表 - 高效过滤大数据集
多阶段工作流 - 基于选择的表单导航
数据过滤 - 根据下拉选择应用过滤器
模板化下拉框 - 显示富内容（图片、描述）
本地化选择 - 特定区域/语言的选项
无障碍合规表单 - 符合WCAG标准的选择界面

Related Components

Next Steps

下一步

Choose your use case from "Common Use Cases" above
Navigate to the relevant reference guide in the "Documentation and Navigation Guide" section
Copy the pattern example and adapt it to your specific data and requirements
Consult the specific reference for advanced configurations and edge cases

For detailed implementation patterns, complete code examples, and troubleshooting guidance, read the appropriate reference file based on your specific needs.

从上方的「常见使用场景」中选择你的场景
在「文档导航指南」部分导航到相关参考指南
复制模式示例并适配你的具体数据和需求
查阅特定参考文档了解高级配置和边缘情况

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

MultiSelect Dropdown

The MultiSelect Dropdown component enables users to select multiple items from a list with support for filtering, grouping, sorting, keyboard navigation, accessibility, and extensive customization options. This skill guides you through installation, implementation, data binding, features, customization, and advanced scenarios.

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

When to Use This Skill

使用场景

Use this skill when you need to:

Install and configure the MultiSelect Dropdown component in Blazor projects
Implement multiple item selection in forms and applications
Set up data binding with collections, APIs, or remote sources
Configure selection modes (Checkbox, Delimiter, Box)
Add filtering and grouping capabilities to dropdowns
Customize appearance, styling, and templates
Implement keyboard navigation and accessibility features
Handle selection events and programmatic selection
Support localization, RTL, and globalization
Optimize performance with virtualization
Integrate with forms and validation

当你需要以下功能时使用本指南：

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

Component Overview

组件概述

Key Capabilities:

Multiple Selection: Select one or many items using various modes
Data Sources: Bind to collections, APIs, or custom data providers
Filtering: Built-in search with customizable filter options
Grouping & Sorting: Organize items hierarchically with sorting
Custom Templates: Design custom item, group, header, and footer templates
Keyboard Navigation: Full keyboard support and accessibility (WCAG 2.1)
Theming: Bootstrap, Material, Fluent, Tailwind themes with light/dark modes
Validation: Form validation support with custom validators
RTL & Localization: Right-to-left language support and multi-language
Virtualization: Handle large datasets efficiently

核心能力：

多选功能：使用多种模式选择一个或多个项
数据源：绑定到集合、API或自定义数据提供程序
过滤：内置搜索功能，支持自定义过滤选项
分组与排序：通过排序分层组织项
自定义模板：设计自定义项、组、页眉和页脚模板
键盘导航：完整的键盘支持和无障碍（WCAG 2.1）
主题支持：Bootstrap、Material、Fluent、Tailwind主题，支持明暗模式
验证：表单验证支持，包含自定义验证器
RTL与本地化：从右到左语言支持和多语言适配
虚拟化：高效处理大数据集

Documentation and Navigation Guide

文档导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and NuGet package setup
Basic MultiSelect Dropdown implementation
Namespace imports and service registration
Theme application
Minimal working example
Common setup troubleshooting

📄 阅读：references/getting-started.md

安装和NuGet包配置
基础MultiSelect Dropdown实现
命名空间导入和服务注册
主题应用
最简运行示例
常见设置故障排除

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding to collections (List, ObservableCollection)
Remote data binding and API integration
Custom data adapters and sources
Value binding patterns
Handling null and empty data
Performance considerations

📄 阅读：references/data-binding.md

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

Features and Selection

功能与选择

📄 Read: references/features-and-selection.md

Selection modes (Checkbox, Delimiter, Box)
Single vs. multiple item selection
Select/deselect all functionality
Programmatic selection and value updates
Custom values and free-form text input
Default selected values
Disabled items and item groups
Virtualization for large datasets

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

选择模式（Checkbox、Delimiter、Box）
单项与多项选择对比
全选/取消全选功能
程序化选择和值更新
自定义值和自由文本输入
默认选中值
禁用项和项组
大数据集虚拟化

Filtering and Grouping

过滤与分组

📄 Read: references/filtering-and-grouping.md

Enable and configure filtering
Filter placeholder and debounce delay
Custom filter implementation
Case-sensitive and multi-field filtering
Remote filtering from APIs
Data grouping with group headers
Sorting within groups
Filter performance optimization

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

启用并配置过滤
过滤占位符和防抖延迟
自定义过滤实现
区分大小写和多字段过滤
来自API的远程过滤
带组页眉的数据分组
组内排序
过滤性能优化

Customization and Styling

自定义与样式

📄 Read: references/customization-and-styling.md

CSS classes and theme customization
Placeholder and floating labels
Icon support (prefix/suffix icons)
Popup width and height customization
Chip display modes and styling
Popup positioning
RTL (Right-to-Left) support
Dark mode implementation
Custom CSS variables and overrides

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

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

Accessibility and Templates

无障碍与模板

📄 Read: references/accessibility-and-templates.md

ARIA attributes and screen reader support
Keyboard navigation shortcuts
Focus management and visual focus indicators
WCAG 2.1 compliance
ItemTemplate for custom item rendering
GroupTemplate for custom group headers
HeaderTemplate and FooterTemplate
Template binding and context
Accessibility in custom templates

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

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

Events and API Reference

事件与API参考

📄 Read: references/events-and-api.md

Complete event reference (Change, Focus, Blur, Open, Close)
Event handling patterns in Blazor
Event arguments and return values
Component API methods (Open, Close, Focus, Refresh)
Property access and state updates
Reactive patterns for state management
Real-world event handling examples

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

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

Advanced Scenarios

高级场景

📄 Read: references/advanced-scenarios.md

Form integration and validation
Localization and globalization setup
Custom value creation and suggestion
Performance optimization techniques
Multiple dropdown instances management
Server-side vs. client-side filtering
Real-world use cases and patterns
Edge cases and troubleshooting
Best practices and gotchas

📄 阅读：references/advanced-scenarios.md

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

Quick Start

快速入门

Minimal Example

最简示例

1. Install NuGet Package:

bash

dotnet add package Syncfusion.Blazor.DropDowns

2. Add to
_Imports.razor
:

csharp

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

3. Register Service in
Program.cs
:

csharp

builder.Services.AddSyncfusionBlazor();

4. Add Theme in
App.razor
:

html

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

5. Use MultiSelect Dropdown:

csharp

@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. 安装NuGet包：

bash

dotnet add package Syncfusion.Blazor.DropDowns

2. 添加到
_Imports.razor
：

csharp

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

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

csharp

builder.Services.AddSyncfusionBlazor();

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

html

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

5. 使用MultiSelect Dropdown：

csharp

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

Common Patterns

常见模式

Pattern 1: Two-Way Binding with Selection Change

模式1：双向绑定与选择变更

csharp

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

csharp

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

Pattern 2: Filtering with Remote Data

模式2：带远程数据的过滤

csharp

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

csharp

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

Pattern 3: Custom Validation in Form

模式3：表单中的自定义验证

csharp

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

csharp

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

Key Props Reference

关键属性参考

Property	Type	Description	When to Use
`DataSource`	`IEnumerable<TItem>`	Collection of items to display	Always required
`Value`	`TValue`	Currently selected values (array or collection)	Binding selections
`Placeholder`	`string`	Placeholder text when empty	UX improvement
`AllowFiltering`	`bool`	Enable/disable search filtering	For searchable lists
`Mode`	`VisualMode`	Selection display mode (Default, Box, Delimiter, CheckBox)	Customize display style
`Enabled`	`bool`	Enable/disable component (default: true)	Conditional states
`AllowCustomValue`	`bool`	Allow user-entered custom values	Free-form input
`EnableVirtualization`	`bool`	Enable virtualization for large data	Performance optimization
`PopupHeight`	`string`	Height of dropdown popup (default: 300px)	Customize appearance
`PopupWidth`	`string`	Width of dropdown popup (default: 100%)	Customize appearance
`CssClass`	`string`	Custom CSS class	Custom styling
`ShowSelectAll`	`bool`	Show select all option in CheckBox mode	Bulk selection
`ShowClearButton`	`bool`	Display clear button (default: true)	Allow clearing selection
`ShowDropDownIcon`	`bool`	Display dropdown icon (default: true)	Visual indicator
`MaximumSelectionLength`	`int`	Max items that can be selected (default: 1000)	Limit selections
`HideSelectedItem`	`bool`	Hide selected items in popup	Clean popup display
`EnableSelectionOrder`	`bool`	Enable selection order display (default: true)	Show selection sequence
`EnableCloseOnSelect`	`bool`	Auto-close popup after selection	Quick selection UX
`DelimiterChar`	`string`	Separator for Delimiter mode (default: ",")	Customize separator
`FilterBarPlaceholder`	`string`	Placeholder for filter input	Filter UX
`FloatLabelType`	`FloatLabelType`	Floating label behavior (Never, Always, Auto)	Modern form styling
`EnableRtl`	`bool`	Right-to-left language support	International apps
`ReadOnly`	`bool`	Read-only mode (default: false)	Display-only state
`TabIndex`	`int`	Tab order index (default: 0)	Keyboard navigation

属性	类型	描述	使用场景
`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）	键盘导航

Common Use Cases

常见使用场景

Case 1: Employee Selection in Team Assignment

User needs to select multiple employees for a team
Use checkbox mode for clear selection
Add filtering for easier search
Validate minimum selection requirement

Case 2: Category/Tag Selection for Content

User tags content with multiple categories
Use custom values for new tags
Show selected items as chips
Allow deselect with delete key

Case 3: Department/Location Multi-Filter

Filter data by multiple departments and locations
Remote data source from API
Grouping by department/location
Programmatic selection updates

Case 4: Subscription Preferences

User selects multiple notification types
Grouping by category (Email, SMS, Push)
All-select/deselect functionality
RTL support for international apps

Ready to implement MultiSelect Dropdown? Start with Getting Started for setup, then navigate to other references based on your specific needs.

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

用户需要为团队选择多个员工
使用复选框模式实现清晰选择
添加过滤功能便于搜索
验证最小选择数量要求

场景2：内容的类别/标签选择

用户为内容添加多个类别标签
使用自定义值支持新标签创建
将选中项显示为芯片
允许通过删除键取消选择

场景3：部门/位置多过滤

通过多个部门和位置过滤数据
来自API的远程数据源
按部门/位置分组
程序化更新选择

场景4：订阅偏好设置

用户选择多种通知类型
按类别分组（邮件、短信、推送）
全选/取消全选功能
国际化应用的RTL支持

准备好实现MultiSelect Dropdown了吗？ 从快速入门开始配置，然后根据具体需求浏览其他参考文档。

Mention

The Mention component provides @mention functionality for tagging users, items, or entities within text content. It displays a suggestion list when users type a trigger character (default:

), enabling easy selection and insertion of tagged items.

Mention组件提供@提及功能，用于在文本内容中标记用户、项或实体。当用户输入触发字符（默认：

）时，会显示建议列表，方便用户选择并插入标记项。

When to Use This Skill

使用场景

Use the Mention component when you need to:

Add @mention tagging in comments, chat, or social features
Tag users, products, or entities in text areas
Implement autocomplete suggestions with a trigger character
Create collaborative commenting systems
Build social media-style mention features
Enable context-aware item selection in text input

当你需要以下功能时使用Mention组件：

在评论、聊天或社交功能中添加@提及标记
在文本区域中标记用户、产品或实体
实现带触发字符的自动完成建议
创建协作评论系统
构建社交媒体风格的提及功能
在文本输入中启用上下文感知的项选择

Component Overview

组件概述

The Mention component is a dropdown that enables users to mention items from a configured data source by typing a trigger character (default:

). It displays a filtered suggestion list that users can select from, automatically inserting the mention into the target element.

Mention组件是一个下拉框，用户输入提及字符（默认：

）时，会从配置的数据源中显示建议列表，用户可选择项并自动插入到目标元素中。

Key Capabilities

核心能力

Trigger-based suggestions: Displays suggestions when users type the mention character
Multiple data source types: Supports local primitives, complex objects, enums, and remote data
Advanced filtering: StartsWith, Contains, EndsWith filter types with minimum character limits
Templating: Customize item display, mention format, empty states, and loading indicators
Accessibility: Full WCAG 2.2 compliance with keyboard navigation and screen reader support
Remote data: OData v4, Web API adaptors with offline mode support

触发式建议：用户输入提及字符时显示建议
多类型数据源：支持本地基本类型、复杂对象、枚举和远程数据
高级过滤：StartsWith、Contains、EndsWith过滤类型，支持最小字符限制
模板化：自定义项显示、提及格式、空状态和加载指示器
无障碍支持：完全符合WCAG 2.2标准，支持键盘导航和屏幕阅读器
远程数据：OData v4、Web API适配器，支持离线模式

Documentation & Navigation Guide

文档导航指南

Choose your topic below to get started:

选择以下主题开始：

📄 Getting Started

📄 快速入门

Read: references/getting-started.md

Installation and package setup (NuGet, themes)
Creating Blazor WASM and Server applications
Basic Mention component implementation
Target element configuration (div, textarea, input)
Initial data binding

阅读：references/getting-started.md

安装和包配置（NuGet、主题）
创建Blazor WASM和服务器应用
基础Mention组件实现
目标元素配置（div、textarea、input）
初始数据绑定

📄 Working with Data

📄 数据处理

Read: references/working-with-data.md

Binding local data (primitives, complex objects, ExpandoObject)
Enum data binding
Remote data binding with DataManager
OData v4 and Web API adaptors
Offline mode for caching
Data fetch events (ActionBegin, ActionComplete, ActionFailure)

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

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

📄 Filtering & Search

📄 过滤与搜索

Read: references/filtering-and-search.md

MinLength property for minimum search characters
FilterType options (StartsWith, Contains, EndsWith)
AllowSpaces for multi-word searching
SuggestionCount for result limiting

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

触发搜索的最小字符数MinLength属性
FilterType选项（StartsWith、Contains、EndsWith）
AllowSpaces支持多词搜索
SuggestionCount限制结果数量

📄 Customization

📄 自定义

Read: references/customization.md

ShowMentionChar to display mention character in selected text
SuffixText for adding space or newline after mention
Popup dimensions (PopupHeight, PopupWidth)
Custom mention trigger character
RequireLeadingSpace for space-prefixed triggers

阅读：references/customization.md

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

📄 Templates & Display

📄 模板与显示

Read: references/templates.md

ItemTemplate for custom suggestion list styling
DisplayTemplate for formatted mention display
NoRecordsTemplate for empty states
SpinnerTemplate for loading states
Template context access and data usage

阅读：references/templates.md

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

📄 Accessibility

📄 无障碍

Read: references/accessibility.md

WCAG 2.2 compliance details
WAI-ARIA attributes (aria-selected, aria-activedescendent)
Keyboard navigation shortcuts
Screen reader support
Mobile and RTL language support

阅读：references/accessibility.md

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

Quick Start Example

快速入门示例

razor

<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 = "alice@company.com" },
        new PersonData { Name = "Bob Smith", Email = "bob@company.com" },
        new PersonData { Name = "Carol White", Email = "carol@company.com" }
    };
}

razor

<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 = "alice@company.com" },
        new PersonData { Name = "Bob Smith", Email = "bob@company.com" },
        new PersonData { Name = "Carol White", Email = "carol@company.com" }
    };
}

Common Patterns

常见模式

Pattern 1: Comment Section with User Mentions

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

razor

<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 = '@';
}

razor

<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 = '@';
}

Pattern 2: Filtered Suggestions with Remote Data

模式2：带远程数据的过滤建议

razor

<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 = '@';
}

razor

<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 = '@';
}

Pattern 3: Custom Display with Templates

模式3：带自定义显示的模板

razor

<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 = '@';
}

razor

<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 = '@';
}

Key Properties

关键属性

Property	Type	Default	Purpose
`TItem`	Generic	-	Data source item type
`DataSource`	IEnumerable<TItem>	-	Local data collection
`MentionChar`	char	`'@'`	Trigger character for suggestions
`Target`	string	-	CSS selector for target element
`MinLength`	int	0	Minimum characters to show suggestions
`FilterType`	FilterType	Contains	Search filter mode (StartsWith, Contains, EndsWith)
`AllowSpaces`	bool	false	Allow spaces in mention search
`ShowMentionChar`	bool	false	Display trigger character with mention
`SuffixText`	string	-	Text appended after mention (space, newline)
`RequireLeadingSpace`	bool	false	Require space before mention character
`PopupHeight`	string	300px	Suggestion list height
`PopupWidth`	string	auto	Suggestion list width
`SuggestionCount`	int	25	Maximum items in suggestion list

属性	类型	默认值	用途
`TItem`	泛型	-	数据源项类型
`DataSource`	IEnumerable<TItem>	-	本地数据集合
`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	建议列表的最大项数

Common Use Cases

常见使用场景

User Tagging in Comments

Create collaboration tools where users mention @username in comments
Combine with DisplayTemplate to show user avatars
Use remote data binding to fetch team members dynamically

Task Assignment Notifications

Mention team members when assigning tasks
Customize MentionChar to use # for tasks, @ for users
Use ActionComplete event to log mentions for notifications

Code or Entity References

Use Mention to reference code snippets (#snippet)
Mention entities or resources in documentation
Support enum data binding for predefined entities

Multi-target Mention

Implement mention support in multiple textareas on same page
Each Mention component can target a different element
Use Target property with unique CSS selectors

评论中的用户标记

创建协作工具，用户在评论中@用户名
结合DisplayTemplate显示用户头像
使用远程数据绑定动态获取团队成员

任务分配通知

分配任务时提及团队成员
自定义MentionChar，用#标记任务，@标记用户
使用ActionComplete事件记录提及信息用于通知

代码或实体引用

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

多目标提及

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

Next Steps

下一步

Start here: Read Getting Started to install and set up
Bind data: Learn Working with Data for local/remote sources
Enhance UX: Explore Filtering & Search and Templates
Ensure accessibility: Review Accessibility for inclusive design
Fine-tune: Use Customization for appearance and behavior adjustments

For additional help:

Official Documentation: https://blazor.syncfusion.com/documentation/mention/getting-started
API Reference: https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfMention-1.html
Community Support: https://www.syncfusion.com/forums/blazor

从这里开始：阅读快速入门完成安装和设置
绑定数据：学习数据处理实现本地/远程源绑定
提升体验：探索过滤与搜索和模板
确保无障碍：查看无障碍实现包容性设计
精细调整：使用自定义调整外观和行为

获取更多帮助：

官方文档：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

ListBox

A comprehensive skill for implementing and working with the SfListBox component in Blazor applications. The ListBox displays a scrollable list of items with support for single/multiple selection, checkboxes, filtering, drag-and-drop, icons, and custom templates.

这是一份关于在Blazor应用中实现和使用SfListBox组件的全面指南。ListBox显示可滚动的项列表，支持单/多选、复选框、过滤、拖拽、图标和自定义模板。

When to Use This Skill

使用场景

Use this skill when you need to:

Installation & Setup
- Install Syncfusion.Blazor.DropDowns NuGet package
- Register services and configure themes
- Set up Blazor WebAssembly, Server, or Web App projects
Data Binding
- Bind array of strings or objects to ListBox
- Map complex nested objects to list items
- Load data from remote sources (DataManager, APIs)
- Update data dynamically
Selection & Interaction
- Implement single or multiple selection modes
- Add checkboxes for item selection
- Enable "Select All" functionality
- Set maximum selection limits
- Retrieve selected items and values
- Handle selection change events
Features & Customization
- Enable filtering and search capabilities
- Implement drag-and-drop reordering
- Create dual-listbox patterns (source/target)
- Enable/disable specific items
- Add icons and custom templates
- Apply sorting and grouping
Styling & Appearance
- Apply themes (Bootstrap, Material, Fluent, Tailwind)
- Customize CSS and styling
- Create responsive layouts
- Implement dark mode
Accessibility
- Ensure WCAG 2.1 compliance
- Configure keyboard navigation
- Add ARIA labels and roles
- Support screen readers

当你需要以下功能时使用本指南：

安装与设置
- 安装Syncfusion.Blazor.DropDowns NuGet包
- 注册服务并配置主题
- 设置Blazor WebAssembly、Server或Web App项目
数据绑定
- 将字符串数组或对象绑定到ListBox
- 将复杂嵌套对象映射到列表项
- 从远程源加载数据（DataManager、API）
- 动态更新数据
选择与交互
- 实现单选或多选模式
- 添加复选框用于项选择
- 启用"全选"功能
- 设置最大选择限制
- 获取选中项和值
- 处理选择变更事件
功能与自定义
- 启用过滤和搜索功能
- 实现拖拽重排序
- 创建双列表模式（源/目标）
- 启用/禁用特定项
- 添加图标和自定义模板
- 应用排序和分组
样式与外观
- 应用主题（Bootstrap、Material、Fluent、Tailwind）
- 自定义CSS和样式
- 创建响应式布局
- 实现暗色模式
无障碍
- 确保WCAG 2.1合规性
- 配置键盘导航
- 添加ARIA标签和角色
- 支持屏幕阅读器

Component Overview

组件概述

The SfListBox component is a flexible dropdown alternative that displays items in a scrollable list format.

Key Characteristics:

TValue: Type parameter for selected values (e.g.,
```
string[]
```
,
```
int[]
```
)
TItem: Type parameter for data source items
Multiple Selection: Default behavior; supports single mode
Checkbox Support: Optional checkboxes for item selection
Field Mapping: Maps data object properties to display and value
Templates: Supports custom item templates for rich formatting
Data Binding: Supports local arrays, objects, remote data
Events: Change, select, focus events for interaction handling

SfListBox组件是灵活的下拉框替代方案，以可滚动列表格式显示项。

核心特性：

TValue：选中值的类型参数（如
```
string[]
```
、
```
int[]
```
）
TItem：数据源项的类型参数
多选：默认行为；支持单选模式
复选框支持：可选的项选择复选框
字段映射：将数据对象属性映射到显示和值
模板支持：支持自定义项模板实现富格式
数据绑定：支持本地数组、对象、远程数据
事件：Change、select、focus等交互事件

Quick Start Example

快速入门示例

razor

@using Syncfusion.Blazor.DropDowns

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

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

With data binding:

razor

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

razor

@using Syncfusion.Blazor.DropDowns

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

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

带数据绑定的示例：

razor

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

Key Props & Events

关键属性与事件

Important Properties:

```
DataSource
```
- Array or list of items to display
```
TValue
```
- Type of selected values (string[], int[], etc.)
```
TItem
```
- Type of data source items
```
Value
```
- Currently selected values (two-way bindable)
```
MaximumSelectionLength
```
- Limit number of selections (default: 500)
```
Enabled
```
- Enable/disable the component
```
AllowFiltering
```
- Enable search/filter functionality
```
Allowdragging
```
- Enable drag-and-drop reordering

Selection Settings:

```
Mode
```
- SelectionMode.Single or SelectionMode.Multiple
```
ShowCheckbox
```
- Show checkboxes for selection
```
ShowSelectAll
```
- Show "Select All" checkbox

Common Events:

```
ValueChange
```
- Fires when selected values change
```
Change
```
- Fires on item selection change
```
Select
```
- Fires when item is selected

重要属性：

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

选择设置：

```
Mode
```
- SelectionMode.Single或SelectionMode.Multiple
```
ShowCheckbox
```
- 显示选择复选框
```
ShowSelectAll
```
- 显示"全选"复选框

常见事件：

```
ValueChange
```
- 选中值变更时触发
```
Change
```
- 项选择变更时触发
```
Select
```
- 项被选中时触发

Common Patterns

常见模式

1. Single Selection Mode

1. 单选模式

razor

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

razor

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

2. Multiple Selection with Checkboxes

2. 带复选框的多选

razor

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

razor

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

3. Getting Selected Values

3. 获取选中值

razor

@bind-Value="@SelectedValues"

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

razor

@bind-Value="@SelectedValues"

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

4. Handling Selection Change

4. 处理选择变更

razor

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

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

razor

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

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

5. Filtering Enabled

5. 启用过滤

razor

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

razor

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

Documentation & Navigation Guide

文档导航指南

Choose the reference that matches your current task:

根据当前任务选择对应的参考文档：

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and NuGet package setup
Project configuration (WebAssembly, Server, Web App)
Basic component markup and first example
Theme configuration and stylesheets
Running and testing your first ListBox

📄 阅读：references/getting-started.md

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

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding array of strings
Binding array of objects with field mapping
Binding complex nested objects
Remote data loading with DataManager
Dynamic data updates
Best practices for data binding

📄 阅读：references/data-binding.md

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

Selection & Modes

选择与模式

📄 Read: references/selection-and-modes.md

Single selection configuration
Multiple selection (default mode)
Checkbox selection with ShowCheckbox
Select All functionality
Getting selected items and values
MaximumSelectionLength constraints
Selection change events
Common selection patterns

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

单选配置
多选（默认模式）
带ShowCheckbox的复选框选择
全选功能
获取选中项和值
MaximumSelectionLength限制
选择变更事件
常见选择模式

Features & Interactions

功能与交互

📄 Read: references/features-and-interactions.md

Filtering and search capabilities
Drag-and-drop reordering (Allowdragging)
Item enable/disable functionality
Icons and icon CSS classes
Item templates for custom rendering
Sorting and grouping data
Dual ListBox pattern (source to target)
Accessibility attributes

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

过滤和搜索功能
拖拽重排序（Allowdragging）
项启用/禁用功能
图标和图标CSS类
自定义渲染的项模板
数据排序和分组
双ListBox模式（源到目标）
无障碍属性

Styling & Appearance

样式与外观

📄 Read: references/styling-and-appearance.md

Theme application (Bootstrap, Material, Fluent, Tailwind)
CSS class customization
Custom item templates for styling
Icon integration and styling
Dark mode implementation
Responsive design patterns
Layout and sizing

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

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

Accessibility & Events

无障碍与事件

📄 Read: references/accessibility-and-events.md

WCAG 2.1 compliance guidelines
Keyboard navigation support
ARIA labels and roles
Event binding (ValueChange, Change, Select)
Event handling patterns
Focus management
Screen reader support
Common accessibility patterns

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

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

Use Case Examples

使用场景示例

Choose a reference based on your scenario:

"I need to add a ListBox to my Blazor project" → Getting Started
"How do I bind data to ListBox?" → Data Binding
"I want users to select multiple items with checkboxes" → Selection & Modes
"Can I let users search/filter the list?" → Features & Interactions
"How do I customize colors and styling?" → Styling & Appearance
"Does ListBox support keyboard navigation?" → Accessibility & Events
"I need a source/target ListBox pattern" → Features & Interactions

根据你的场景选择参考文档：

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

Next Steps

下一步

New to ListBox? Start with Getting Started
Have data to bind? Go to Data Binding
Need multi-selection? Check Selection & Modes
Want advanced features? Explore Features & Interactions
Making it look good? Read Styling & Appearance
Accessibility needed? Review Accessibility & Events

首次使用ListBox？ 从快速入门开始
有数据要绑定？ 查看数据绑定
需要多选？ 阅读选择与模式
想要高级功能？ 探索功能与交互
优化外观？ 查看样式与外观
需要无障碍支持？ 参考无障碍与事件