syncfusion-aspnetcore-dropdownlist

在 ASP.NET Core 中实现下拉列表

下拉列表是一种单选控件，用于显示预定义值列表。用户可以从下拉列表中选择一个值。它支持数据绑定、筛选、分组、自定义模板和无障碍功能。

何时使用此技能

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

• 在 ASP.NET Core 应用程序中创建单选下拉列表
• 从服务器端数据源（数组、数据库、API）绑定下拉列表数据
• 为大型列表启用筛选
• 对相关项进行分组
• 使用模板自定义项的外观
• 确保符合无障碍要求
• 根据父级选择级联下拉列表
• 使用事件处理用户选择

组件概览

主要功能：

• 从本地数组和远程数据源绑定数据
• 使用搜索框实时筛选
• 自动对项进行分组
• 可自定义项模板和值模板
• 支持 WCAG 无障碍功能和键盘导航
• 支持级联下拉列表
• 针对大型数据集的虚拟滚动

常用属性：

• DataSource - 数据数组或 DataManager
• Fields - 字段映射（text、value、groupBy、iconCss）
• AllowFiltering - 启用或禁用筛选
• FilterType - 筛选算法（StartsWith、Contains、EndsWith）
• GroupBy - 用于分组的字段名称
• ItemTemplate - 自定义项渲染
• ValueTemplate - 自定义选中值的渲染
• Placeholder - 提示文本
• Value - 选中的值
• ReadOnly - 只读状态

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包配置
• TagHelper 注册和配置
• 基本的下拉列表实现
• HTML 结构和简要示例
• CSS 主题导入
• 点击和更改事件处理程序

数据绑定与数据源

📄 阅读： references/data-binding.md

• 绑定简单数据（字符串、数字）数组
• 绑定复杂 JSON 对象
• 嵌套数据结构映射
• 使用 DataManager 绑定远程数据
• OData 和 Web API 集成
• 字段映射和值绑定
• 了解文本字段和值字段

筛选与分组

📄 阅读： references/filtering-grouping.md

• 启用和配置筛选
• 筛选类型（StartsWith、Contains、EndsWith）
• 不区分大小写的筛选
• 按类别对项进行分组
• 自定义组标题
• 排序顺序配置（升序/降序）
• 用于提升性能的虚拟分组

模板与样式

📄 阅读： references/templates-styling.md

• 自定义项模板
• 选中值模板
• 页眉和页脚模板
• 组标题模板
• 自定义 CSS 类
• 主题样式和配色方案
• 响应式尺寸和定位

无障碍与功能

📄 阅读： references/accessibility-features.md

• 符合 WCAG 2.1 Level AA 标准
• 键盘导航（方向键、Enter、Tab）
• ARIA 属性和屏幕阅读器支持
• 焦点管理和焦点指示器
• 禁用状态处理
• RTL（从右到左）语言支持
• 工具提示和帮助文本集成

高级场景

📄 阅读： references/advanced-scenarios.md

• 级联下拉列表（依赖选择）
• 多选下拉列表模式
• 针对大型数据集的虚拟滚动
• 搜索和自动完成模式
• API 集成和异步数据加载
• 错误处理和空状态
• 性能优化技巧

快速入门示例

控制器（HomeController.cs）：

public class HomeController : Controller
{
    public IActionResult Index()
    {
        ViewBag.Fruits = new List<string> { "Apple", "Orange", "Banana", "Mango" };
        return View();
    }
}

视图（Index.cshtml）：

@Html.EJ2().DropDownList()
    .Id("DropdownList")
    .DataSource(ViewBag.Fruits)
    .Placeholder("Select fruit")
    .Render()

常见模式

模式 1：带事件处理的基本选择

模型：

public class Category
{
    public int Id { get; set; }
    public string Name { get; set; }
}

控制器：

public IActionResult Index()
{
    var categories = new List<Category>
    {
        new Category { Id = 1, Name = "Electronics" },
        new Category { Id = 2, Name = "Furniture" },
        new Category { Id = 3, Name = "Clothing" }
    };
    ViewBag.Categories = categories;
    return View();
}

视图：

@Html.EJ2().DropDownList()
    .Id("Category")
    .DataSource(ViewBag.Categories)
    .Fields(fields => fields.Text("Name").Value("Id"))
    .Change("onCategoryChange")
    .Placeholder("Select category")
    .Render()

<script>
function onCategoryChange(args) {
    console.log('Selected ID:', args.value);
    console.log('Selected Text:', args.text);
    // Perform action based on selection
}
</script>

模式 2：级联下拉列表

模型：

public class Country
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public class City
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int CountryId { get; set; }
}

控制器：

public IActionResult Index()
{
    var countries = new List<Country>
    {
        new Country { Id = 1, Name = "USA" },
        new Country { Id = 2, Name = "Canada" },
        new Country { Id = 3, Name = "Mexico" }
    };
    ViewBag.Countries = countries;
    return View();
}

[HttpGet("api/cities/{countryId}")]
public IActionResult GetCities(int countryId)
{
    var cities = new List<City>
    {
        new City { Id = 1, Name = "New York", CountryId = 1 },
        new City { Id = 2, Name = "Los Angeles", CountryId = 1 },
        new City { Id = 3, Name = "Toronto", CountryId = 2 },
        new City { Id = 4, Name = "Vancouver", CountryId = 2 }
    };
    
    var filtered = cities.Where(c => c.CountryId == countryId)
        .Select(c => new { c.Id, c.Name })
        .ToList();
    
    return Json(filtered);
}

视图：

@Html.EJ2().DropDownList()
    .Id("Country")
    .DataSource(ViewBag.Countries)
    .Fields(fields => fields.Text("Name").Value("Id"))
    .Change("onCountryChange")
    .Placeholder("Select country")
    .Render()


@Html.EJ2().DropDownList()
    .Id("City")
    .Placeholder("Select city")
    .Render()

<script>
function onCountryChange(args) {
    var cityDropdown = document.getElementById('City').ej2_instances[0];
    
    if (args.value) {
        // Fetch cities for selected country
        fetch('/home/GetCities/' + args.value)
            .then(response => response.json())
            .then(data => {
                cityDropdown.dataSource = data;
                cityDropdown.value = null;
            })
            .catch(error => console.error('Error:', error));
    } else {
        cityDropdown.dataSource = [];
    }
}
</script>

模式 3：使用远程数据的筛选列表

模型：

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

API 控制器：

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetProducts()
    {
        var products = new List<Product>
        {
            new Product { Id = 1, Name = "Laptop", Price = 999.99m },
            new Product { Id = 2, Name = "Mouse", Price = 25.50m },
            new Product { Id = 3, Name = "Keyboard", Price = 75.00m },
            new Product { Id = 4, Name = "Monitor", Price = 299.99m }
        };
        return Ok(products);
    }
}

视图：

@Html.EJ2().DropDownList()
    .Id("Products")
    .DataSource(d => d.Url("/api/products"))
    .Fields(fields => fields.Text("Name").Value("Id"))
    .AllowFiltering(true)
    .FilterType(FilterType.Contains)
    .Placeholder("Search products...")
    .Render()

关键属性及适用场景

属性	类型	适用场景
DataSource	Array/DataManager	填充项时始终必需
Fields	FieldSettings	绑定复杂数据对象时
Value	string/number	预选某个项时
AllowFiltering	bool	列表包含 10 项以上时
FilterType	FilterType	自定义搜索行为
GroupBy	string	项目具有逻辑类别时
ItemTemplate	string	需要丰富的项目内容时
Placeholder	string	提供更好的 UX 提示时
ReadOnly	bool	需要阻止用户更改时
Enabled	bool	需要有条件地启用时

常见用例

1. 表单选择字段

用于在表单中选择类别、状态或类型的下拉列表

2. 级联选择

多个下拉列表，子级选项取决于父级选项

3. 可搜索列表

为包含大量项目的下拉列表启用筛选

4. 分组项目

按类别组织项目（例如，产品类别 > 子类别）

5. 动态数据

根据用户操作从 API 或数据库加载项目

6. 模板自定义

在下拉列表项中显示包含图标、图片或徽章的丰富内容

---

后续步骤

• 刚开始使用？ 阅读入门指南
• 需要绑定服务器数据？ 阅读数据绑定
• 需要筛选？ 阅读筛选与分组
• 需要自定义外观？ 阅读模板与样式
• 需要无障碍支持？ 阅读无障碍功能
• 需要处理高级场景？ 阅读高级场景

---

有关父级库概览和其他组件，请参阅实现 Syncfusion ASP.NET Core 组件。