syncfusion-aspnetcore-combobox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion ASP.NET Core ComboBox

实现Syncfusion ASP.NET Core ComboBox

Component Overview

组件概述

The ComboBox is a powerful dropdown control that combines:

User-friendly selection with searchable/filterable options
Data binding support for local arrays and remote data sources
Rich customization through templates and styling
Advanced features like grouping, sorting, virtual scrolling, and cascading
Accessibility built-in for keyboard navigation and screen readers
ASP.NET Core integration via Tag Helper syntax

Key Capabilities:

Type-ahead/autocomplete with filtering
Custom values (allowing user-entered data not in list)
Data grouping and sorting
Dropdown templates for list items, headers, footers
Remote data binding with DataManager
Virtual scrolling for large datasets
RTL (right-to-left) support
WCAG 2.1 AA compliance

ComboBox是一款功能强大的下拉控件，具备以下特性：

用户友好的选择体验，支持可搜索/过滤的选项
数据绑定支持，兼容本地数组和远程数据源
丰富的自定义能力，可通过模板和样式定制
高级功能，如分组、排序、虚拟滚动和级联
内置无障碍支持，适配键盘导航和屏幕阅读器
ASP.NET Core集成，支持Tag Helper语法

核心能力：

预输入/自动完成搭配过滤功能
自定义值（允许用户输入列表外的数据）
数据分组与排序
列表项、页眉、页脚的下拉模板
基于DataManager的远程数据绑定
针对大数据集的虚拟滚动
RTL（从右到左）布局支持
符合WCAG 2.1 AA无障碍标准

Documentation and Navigation Guide

文档与导航指南

Read the following references based on your needs:

根据你的需求阅读以下参考文档：

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and NuGet package setup
Adding ComboBox to your ASP.NET Core project
Minimal working example with Tag Helper syntax
CSS/script imports and configuration
Running your first ComboBox

📄 阅读： references/getting-started.md

安装与NuGet包配置
在ASP.NET Core项目中添加ComboBox
使用Tag Helper语法的最简示例
CSS/脚本导入与配置
运行你的第一个ComboBox

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding local array data (strings and objects)
Binding remote data via DataManager
Mapping complex data structures
Custom value support
OData and Web API integration

📄 阅读： references/data-binding.md

绑定本地数组数据（字符串和对象）
通过DataManager绑定远程数据
复杂数据结构的映射
自定义值支持
OData与Web API集成

Filtering & Search

过滤与搜索

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

Enabling autocomplete and filtering
Search as user types
Changing filter type (contains, startsWith, endsWith)
Case-sensitive vs insensitive filtering
Setting minimum character threshold
Remote filtering from server

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

启用自动完成与过滤
用户输入时实时搜索
更改过滤类型（包含、开头匹配、结尾匹配）
区分大小写与不区分大小写过滤
设置最小触发字符阈值
从服务器进行远程过滤

Templates & Customization

模板与自定义

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

Item templates for list display
Header and footer templates
Group header customization
CSS class customization
Theme customization with CSS variables
Popup height/width configuration

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

列表显示的项模板
页眉与页脚模板
分组页眉自定义
CSS类定制
基于CSS变量的主题定制
弹窗高度/宽度配置

Grouping & Sorting

分组与排序

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

Grouping items by category
Sorting in ascending/descending order
Custom sort functions
Combining grouping with sorting
Group header styling

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

按类别分组项
升序/降序排序
自定义排序函数
分组与排序结合使用
分组页眉样式定制

Autofill & Autocomplete

自动填充与自动完成

📄 Read: references/autofill-and-autocomplete.md

Enable autofill for faster data entry
Autocomplete as user types
Combine autofill with filtering
Keyboard handling for suggestions
Performance with large datasets

📄 阅读： references/autofill-and-autocomplete.md

启用自动填充以加快数据输入
用户输入时自动完成
自动填充与过滤结合
建议项的键盘操作
大数据集下的性能优化

Popup Resizing

弹窗调整大小

📄 Read: references/popup-resize.md

Enable user-resizable popup
Set initial width/height
Persist resized dimensions
Responsive resize behavior
Resize handle styling

📄 阅读： references/popup-resize.md

启用用户可调整大小的弹窗
设置初始宽度/高度
保存调整后的尺寸
响应式调整行为
调整手柄样式定制

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Creating cascading ComboBoxes
Virtual scrolling for large datasets
Keyboard navigation (Tab, Enter, Arrow keys)
Accessibility attributes (ARIA labels)
RTL (right-to-left) support
Custom validation
Event handling (change, selecting, select, filtering)

📄 阅读： references/advanced-features.md

创建级联ComboBox
针对大数据集的虚拟滚动
键盘导航（Tab、Enter、方向键）
无障碍属性（ARIA标签）
RTL（从右到左）布局支持
自定义验证
事件处理（change、selecting、select、filtering）

Quick Start Example

快速入门示例

Here's a minimal ComboBox setup in ASP.NET Core:

html

<!-- In _Layout.cshtml or Index.cshtml -->
@{
    ViewData["Title"] = "ComboBox Example";
    List<string> sports = new List<string> { "Cricket", "Badminton", "Basketball", "Tennis" };
}

<ejs-combobox id="games" dataSource="@sports" placeholder="Select a sport"></ejs-combobox>

With data binding:

html

@{
    var data = new List<object>
    {
        new { Id = 1, Text = "Microsoft", Code = "US" },
        new { Id = 2, Text = "Google", Code = "US" },
        new { Id = 3, Text = "Apple", Code = "US" }
    };
}

<ejs-combobox id="countries" 
              dataSource="@data" 
              fields-text="Text" 
              fields-value="Id"
              placeholder="Select a company">
</ejs-combobox>

以下是ASP.NET Core中ComboBox的最简配置：

html

<!-- 在 _Layout.cshtml 或 Index.cshtml 中 -->
@{
    ViewData["Title"] = "ComboBox Example";
    List<string> sports = new List<string> { "Cricket", "Badminton", "Basketball", "Tennis" };
}

<ejs-combobox id="games" dataSource="@sports" placeholder="Select a sport"></ejs-combobox>

数据绑定示例：

html

@{
    var data = new List<object>
    {
        new { Id = 1, Text = "Microsoft", Code = "US" },
        new { Id = 2, Text = "Google", Code = "US" },
        new { Id = 3, Text = "Apple", Code = "US" }
    };
}

<ejs-combobox id="countries" 
              dataSource="@data" 
              fields-text="Text" 
              fields-value="Id"
              placeholder="Select a company">
</ejs-combobox>

How-To Guides

操作指南

Quick Autofill

快速自动填充

Use autofill for faster user input with autocomplete suggestions:

html

<ejs-combobox autofill="true" allowFiltering="true"></ejs-combobox>

使用自动填充功能，结合自动完成建议加快用户输入：

html

<ejs-combobox autofill="true" allowFiltering="true"></ejs-combobox>

Resizable Popup

可调整大小的弹窗

Let users resize the dropdown popup for better visibility:

html

<ejs-combobox allowResize="true" popupWidth="400px" popupHeight="300px"></ejs-combobox>

允许用户调整下拉弹窗大小以提升可见性：

html

<ejs-combobox allowResize="true" popupWidth="400px" popupHeight="300px"></ejs-combobox>

Common Patterns

常见模式

Pattern 1: Filtered Search Enable filtering so users can search while typing:

html

<ejs-combobox id="combobox" 
              dataSource="@data" 
              allowFiltering="true"
              placeholder="Type to search">
</ejs-combobox>

Pattern 2: Cascading ComboBoxes Second ComboBox data depends on first selection. See advanced-features.md for complete example.

Pattern 3: Custom Value Entry Allow users to enter values not in the list:

html

<ejs-combobox id="combobox" 
              allowCustom="true" 
              dataSource="@data">
</ejs-combobox>

Pattern 4: Grouped Data Group items by category:

html

<ejs-combobox id="combobox" 
              dataSource="@data" 
              fields-groupBy="Category"
              fields-text="Name">
</ejs-combobox>

模式1：过滤搜索 启用过滤功能，让用户输入时实时搜索：

html

<ejs-combobox id="combobox" 
              dataSource="@data" 
              allowFiltering="true"
              placeholder="Type to search">
</ejs-combobox>

模式2：级联ComboBox 第二个ComboBox的数据依赖于第一个的选择。完整示例请查看advanced-features.md。

模式3：自定义值输入 允许用户输入列表外的数值：

html

<ejs-combobox id="combobox" 
              allowCustom="true" 
              dataSource="@data">
</ejs-combobox>

模式4：分组数据 按类别分组项：

html

<ejs-combobox id="combobox" 
              dataSource="@data" 
              fields-groupBy="Category"
              fields-text="Name">
</ejs-combobox>

Key Properties

核心属性

Property	Type	Purpose
`dataSource`	array or DataManager	Items to display in dropdown
`fields-text`	string	Which field to display as label
`fields-value`	string	Which field to use as selected value
`placeholder`	string	Hint text when empty
`allowFiltering`	bool	Enable search/filter as you type
`allowCustom`	bool	Allow user to enter values not in list
`fields-groupBy`	string	Field to group items by
`sortOrder`	Ascending/Descending	Sort order of items
`popupHeight`	string	Height of dropdown (e.g., "300px")
`popupWidth`	string	Width of dropdown
`read-only`	bool	Prevent user input, only allow selection
`enabled`	bool	Enable/disable the control

属性	类型	用途
`dataSource`	array 或 DataManager	下拉列表中显示的项
`fields-text`	string	用作标签显示的字段
`fields-value`	string	用作选中值的字段
`placeholder`	string	为空时的提示文本
`allowFiltering`	bool	启用输入时的搜索/过滤
`allowCustom`	bool	允许用户输入列表外的值
`fields-groupBy`	string	用于分组项的字段
`sortOrder`	Ascending/Descending	项的排序顺序
`popupHeight`	string	下拉弹窗高度（如 "300px"）
`popupWidth`	string	下拉弹窗宽度
`read-only`	bool	禁止用户输入，仅允许选择
`enabled`	bool	启用/禁用控件

Common Use Cases

常见使用场景

Selecting from a list of countries/cities → Use data binding + optional grouping
Searching through large datasets → Use filtering + virtual scrolling
Creating dependent dropdowns → Use cascading pattern (see advanced features)
Displaying categorized items → Use grouping and custom templates
Matching API response data → Use DataManager with fields mapping
Building accessible forms → Use ARIA attributes (see advanced features)

Next Steps:

Start with Getting Started to install and set up
Move to Data Binding for connecting your data
Explore Advanced Features for complex scenarios

For issues or troubleshooting, check individual reference files for gotchas and edge cases.

从国家/城市列表中选择 → 使用数据绑定 + 可选分组
在大数据集中搜索 → 使用过滤 + 虚拟滚动
创建依赖下拉框 → 使用级联模式（查看高级功能）
显示分类项 → 使用分组和自定义模板
匹配API响应数据 → 使用DataManager进行字段映射
构建无障碍表单 → 使用ARIA属性（查看高级功能）

下一步：

从快速入门开始安装和配置
学习数据绑定以连接你的数据
探索高级功能以处理复杂场景

如需问题排查，请查看各参考文档中的注意事项和边缘情况说明。