syncfusion-aspnetcore-dropdowns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing DropDownList in ASP.NET Core

在ASP.NET Core中实现DropDownList

The DropDownList (

<ejs-dropdownlist>

) is a single-selection control that displays a list of predefined values. It supports local and remote data binding, real-time filtering, grouping, custom templates, virtual scrolling, popup resize, localization, and full WCAG 2.2 AA accessibility.

DropDownList（

<ejs-dropdownlist>

）是一款单选控件，可显示预定义值列表。它支持本地与远程数据绑定、实时过滤、分组、自定义模板、虚拟滚动、弹窗调整大小、本地化以及完全符合WCAG 2.2 AA标准的无障碍特性。

Component Overview

组件概述

Tag Helper:

<ejs-dropdownlist>

Namespace:

Syncfusion.EJ2.DropDowns

NuGet:

Syncfusion.EJ2.AspNet.Core

Key Features:

Data binding from local arrays and remote sources (OData V4, Web API, URL Adaptor)
Value binding for primitive types and complex objects (
```
allowObjectBinding
```
)
Real-time filtering with search box (
```
allowFiltering
```
,
```
filterType
```
,
```
debounceDelay
```
)
Grouping items using
```
fields.groupBy
```
Disabled items using
```
fields.disabled
```

Customizable templates:

itemTemplate

valueTemplate

headerTemplate

footerTemplate

groupTemplate

noRecordsTemplate

actionFailureTemplate

Virtual scrolling for large datasets (
```
enableVirtualization
```
)
Popup resize by user (
```
allowResize
```
)
WCAG 2.2 AA compliance, keyboard navigation, ARIA support
RTL rendering (
```
enableRtl
```
)
Localization (
```
locale
```
)
Float label support (
```
floatLabelType
```
)
State persistence (
```
enablePersistence
```
)
Clear button (
```
showClearButton
```
)

Tag Helper:

<ejs-dropdownlist>

命名空间:

Syncfusion.EJ2.DropDowns

NuGet包:

Syncfusion.EJ2.AspNet.Core

核心功能:

支持从本地数组和远程数据源（OData V4、Web API、URL适配器）绑定数据
支持基本类型和复杂对象的值绑定（
```
allowObjectBinding
```
）
带搜索框的实时过滤（
```
allowFiltering
```
、
```
filterType
```
、
```
debounceDelay
```
）
使用
```
fields.groupBy
```
对项进行分组
使用
```
fields.disabled
```
禁用指定项

可自定义模板：

itemTemplate

、

valueTemplate

、

headerTemplate

、

footerTemplate

、

groupTemplate

、

noRecordsTemplate

、

actionFailureTemplate

针对大型数据集的虚拟滚动（
```
enableVirtualization
```
）
允许用户调整弹窗大小（
```
allowResize
```
）
符合WCAG 2.2 AA标准、支持键盘导航和ARIA属性
RTL渲染支持（
```
enableRtl
```
）
本地化支持（
```
locale
```
）
浮动标签支持（
```
floatLabelType
```
）
状态持久化（
```
enablePersistence
```
）
清除按钮（
```
showClearButton
```
）

API Reference

API参考

📄 Full API: references/api.md

All properties with types, defaults, and descriptions
All events
Field settings (
```
<e-dropdownlist-fields>
```
)
Tag helper syntax examples for all features

📄 完整API文档: references/api.md

包含所有属性的类型、默认值及描述
所有事件说明
字段设置（
```
<e-dropdownlist-fields>
```
）
所有功能的Tag Helper语法示例

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

NuGet package installation
TagHelper registration (
```
_ViewImports.cshtml
```
)
⚠️ CDN vs. Local Hosting: See Security & Trust Boundary below for SRI and local hosting alternatives
Script Manager registration
Basic DropDownList tag helper usage
Popup height/width configuration
Change event handling

📄 阅读: references/getting-started.md

NuGet包安装
TagHelper注册（
```
_ViewImports.cshtml
```
）
⚠️ CDN vs. 本地托管: 请参阅下方“安全与信任边界”章节了解SRI和本地托管替代方案
脚本管理器注册
基础DropDownList Tag Helper用法
弹窗高度/宽度配置
变更事件处理

Data Binding and Value Binding

数据绑定与值绑定

📄 Read: references/data-binding.md

Binding array of primitive data (strings, numbers)
Binding complex JSON objects with
```
<e-dropdownlist-fields>
```
Nested/complex data with dot-notation field paths
Value binding for primitive types (pre-selecting)
Object binding with
```
allowObjectBinding
```
Remote data: OData V4, OData, Web API, URL Adaptor
Offline mode (
```
DataManager offline="true"
```
)
```
actionBegin
```
,
```
actionComplete
```
,
```
actionFailure
```
events

📄 阅读: references/data-binding.md

绑定基本类型数组（字符串、数字）
使用
```
<e-dropdownlist-fields>
```
绑定复杂JSON对象
使用点标记字段路径绑定嵌套/复杂数据
基本类型的值绑定（预选择）
使用
```
allowObjectBinding
```
进行对象绑定
远程数据：OData V4、OData、Web API、URL适配器
离线模式（
```
DataManager offline="true"
```
）
```
actionBegin
```
、
```
actionComplete
```
、
```
actionFailure
```
事件

Filtering and Grouping

过滤与分组

📄 Read: references/filtering-grouping.md

Enable filtering with
```
allowFiltering
```
Filter types:
```
StartsWith
```
,
```
Contains
```
,
```
EndsWith
```
Minimum character limit before remote request
Case-sensitive filtering with
```
ignoreCase
```
Diacritics filtering with
```
ignoreAccent
```
Debounce delay with
```
debounceDelay
```
Filter bar placeholder with
```
filterBarPlaceholder
```
Grouping with
```
fields.groupBy
```
Custom group header with
```
groupTemplate
```
Disabled items with
```
fields.disabled
```
Sort order:
```
None
```
,
```
Ascending
```
,
```
Descending
```

📄 阅读: references/filtering-grouping.md

使用
```
allowFiltering
```
启用过滤
过滤类型：
```
StartsWith
```
、
```
Contains
```
、
```
EndsWith
```
触发远程请求的最小字符限制
使用
```
ignoreCase
```
区分大小写过滤
使用
```
ignoreAccent
```
支持变音符号过滤
使用
```
debounceDelay
```
设置防抖延迟
使用
```
filterBarPlaceholder
```
设置过滤栏占位符
使用
```
fields.groupBy
```
进行分组
使用
```
groupTemplate
```
自定义分组头
使用
```
fields.disabled
```
禁用项
排序顺序：
```
None
```
、
```
Ascending
```
、
```
Descending
```

Templates and Styling

模板与样式

📄 Read: references/templates-styling.md

```
itemTemplate
```
— customize popup list items
```
valueTemplate
```
— customize selected value in input
```
headerTemplate
```
— static header in popup
```
footerTemplate
```
— static footer in popup
```
groupTemplate
```
— custom group headers
```
noRecordsTemplate
```
— no data state
```
actionFailureTemplate
```
— remote fetch failure state
```
floatLabelType
```
— float label behavior
```
cssClass
```
— custom CSS class
CSS structures for appearance customization

📄 阅读: references/templates-styling.md

```
itemTemplate
```
— 自定义弹窗列表项
```
valueTemplate
```
— 自定义输入框中选中值的显示
```
headerTemplate
```
— 弹窗中的静态头部
```
footerTemplate
```
— 弹窗中的静态底部
```
groupTemplate
```
— 自定义分组头
```
noRecordsTemplate
```
— 无数据状态模板
```
actionFailureTemplate
```
— 远程数据获取失败状态模板
```
floatLabelType
```
— 浮动标签行为
```
cssClass
```
— 自定义CSS类
用于外观定制的CSS结构

Accessibility and Localization

无障碍与本地化

📄 Read: references/accessibility-features.md

WCAG 2.2 Level AA compliance
WAI-ARIA attributes (
```
aria-haspopup
```
,
```
aria-expanded
```
,
```
aria-selected
```
, etc.)
Full keyboard navigation shortcut reference
RTL support with
```
enableRtl
```
Localization with
```
locale
```
and
```
L10n.load()
```
Readonly vs disabled states
```
enablePersistence
```
for state persistence
```
isDeviceFullScreen
```
for mobile popup behavior

📄 阅读: references/accessibility-features.md

符合WCAG 2.2 AA级标准
WAI-ARIA属性（
```
aria-haspopup
```
、
```
aria-expanded
```
、
```
aria-selected
```
等）
完整的键盘导航快捷键参考
使用
```
enableRtl
```
支持RTL布局
使用
```
locale
```
和
```
L10n.load()
```
实现本地化
只读与禁用状态
使用
```
enablePersistence
```
实现状态持久化
使用
```
isDeviceFullScreen
```
适配移动端弹窗行为

Advanced Scenarios

高级场景

📄 Read: references/advanced-scenarios.md

Virtual scrolling with
```
enableVirtualization
```
(local and remote)
Virtualization with grouping and filtering
Customizing item count in virtualization

Popup resize with

allowResize

resizeStart

resizeStop

resizing

events

Cascading dropdowns (parent-child dependent selection)
Remote data with filtering
Pre-selecting values (by
```
value
```
,
```
text
```
, or
```
index
```
)
```
showClearButton
```
usage
```
htmlAttributes
```
for extra HTML attributes
All events reference with usage examples

📄 阅读: references/advanced-scenarios.md

使用
```
enableVirtualization
```
实现虚拟滚动（本地和远程数据）
结合分组与过滤的虚拟滚动
自定义虚拟滚动中的项数量
使用
```
allowResize
```
、
```
resizeStart
```
、
```
resizeStop
```
、
```
resizing
```
事件实现弹窗调整大小
级联下拉列表（父子依赖选择）
带过滤的远程数据
预选择值（通过
```
value
```
、
```
text
```
或
```
index
```
）
```
showClearButton
```
用法
使用
```
htmlAttributes
```
添加额外HTML属性
所有事件的参考及用法示例

Quick Start Example

快速入门示例

Controller (
HomeController.cs
):

csharp

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

View (
Index.cshtml
):

cshtml

<ejs-dropdownlist id="category"
    dataSource="@ViewBag.data"
    placeholder="Select category"
    change="onCategoryChange">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<script>
function onCategoryChange(args) {
    console.log('Selected ID:', args.value);
}
</script>

控制器（
HomeController.cs
）:

csharp

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

视图（
Index.cshtml
）:

cshtml

<ejs-dropdownlist id="category"
    dataSource="@ViewBag.data"
    placeholder="Select category"
    change="onCategoryChange">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<script>
function onCategoryChange(args) {
    console.log('Selected ID:', args.value);
}
</script>

Common Patterns

常见模式

Pattern 1: Basic Selection with Event Handling

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

cshtml

<ejs-dropdownlist id="category"
    dataSource="@ViewBag.Categories"
    placeholder="Select category"
    change="onCategoryChange">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<script>
function onCategoryChange(args) {
    console.log('Selected ID:', args.value);
}
</script>

cshtml

<ejs-dropdownlist id="category"
    dataSource="@ViewBag.Categories"
    placeholder="Select category"
    change="onCategoryChange">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<script>
function onCategoryChange(args) {
    console.log('Selected ID:', args.value);
}
</script>

Pattern 2: Cascading Dropdowns (Secure Server-Side Proxy)

模式2：级联下拉列表（安全的服务器端代理）

⚠️ Security Note: Avoid client-side direct fetch to untrusted external endpoints. Use a server-side proxy that validates, authenticates, and sanitizes responses.

Controller (Server-Side Proxy):

csharp

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

// ✅ SECURE: Server-side proxy validates countryId and returns only whitelisted data
[HttpGet("api/cities/{countryId}")]
public IActionResult GetCities(int countryId)
{
    // Validate countryId is within acceptable range
    if (countryId <= 0 || countryId > 100)
        return BadRequest("Invalid country ID");
    
    var cities = new List<City>
    {
        new City { Id = 1, Name = "New York",  CountryId = 1 },
        new City { Id = 2, Name = "Toronto",   CountryId = 2 }
    };
    
    // Return only safe, schema-validated data
    return Json(cities.Where(c => c.CountryId == countryId)
        .Select(c => new { c.Id, c.Name })
        .ToList());
}

View (Secure Client):

cshtml

<ejs-dropdownlist id="Country"
    dataSource="@ViewBag.Countries"
    change="onCountryChange"
    placeholder="Select country">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<ejs-dropdownlist id="City" placeholder="Select city">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<script>
function onCountryChange(args) {
    var cityDDL = document.getElementById('City').ej2_instances[0];
    if (args.value) {
        // ✅ SECURE: Fetch only from same-origin API endpoint (same server)
        fetch("/api/cities/" + encodeURIComponent(args.value), {
            method: 'GET',
            headers: { 'Content-Type': 'application/json' },
            credentials: 'same-origin'  // Include CSRF tokens via cookies
        })
        .then(response => {
            if (!response.ok) throw new Error('Server error: ' + response.status);
            return response.json();
        })
        .then(data => {
            // Validate response is an array before binding
            if (Array.isArray(data)) {
                cityDDL.dataSource = data;
                cityDDL.value = null;
            } else {
                console.error('Invalid data format received');
                cityDDL.dataSource = [];
            }
        })
        .catch(error => {
            console.error('Failed to load cities:', error);
            cityDDL.dataSource = [];
        });
    } else {
        cityDDL.dataSource = [];
    }
}
</script>

⚠️ 安全提示: 避免客户端直接请求不可信的外部端点，请使用服务器端代理进行验证、认证和响应清理。

控制器（服务器端代理）:

csharp

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

// ✅ SECURE: Server-side proxy validates countryId and returns only whitelisted data
[HttpGet("api/cities/{countryId}")]
public IActionResult GetCities(int countryId)
{
    // Validate countryId is within acceptable range
    if (countryId <= 0 || countryId > 100)
        return BadRequest("Invalid country ID");
    
    var cities = new List<City>
    {
        new City { Id = 1, Name = "New York",  CountryId = 1 },
        new City { Id = 2, Name = "Toronto",   CountryId = 2 }
    };
    
    // Return only safe, schema-validated data
    return Json(cities.Where(c => c.CountryId == countryId)
        .Select(c => new { c.Id, c.Name })
        .ToList());
}

视图（安全客户端）:

cshtml

<ejs-dropdownlist id="Country"
    dataSource="@ViewBag.Countries"
    change="onCountryChange"
    placeholder="Select country">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<ejs-dropdownlist id="City" placeholder="Select city">
    <e-dropdownlist-fields text="Name" value="Id"></e-dropdownlist-fields>
</ejs-dropdownlist>

<script>
function onCountryChange(args) {
    var cityDDL = document.getElementById('City').ej2_instances[0];
    if (args.value) {
        // ✅ SECURE: Fetch only from same-origin API endpoint (same server)
        fetch("/api/cities/" + encodeURIComponent(args.value), {
            method: 'GET',
            headers: { 'Content-Type': 'application/json' },
            credentials: 'same-origin'  // Include CSRF tokens via cookies
        })
        .then(response => {
            if (!response.ok) throw new Error('Server error: ' + response.status);
            return response.json();
        })
        .then(data => {
            // Validate response is an array before binding
            if (Array.isArray(data)) {
                cityDDL.dataSource = data;
                cityDDL.value = null;
            } else {
                console.error('Invalid data format received');
                cityDDL.dataSource = [];
            }
        })
        .catch(error => {
            console.error('Failed to load cities:', error);
            cityDDL.dataSource = [];
        });
    } else {
        cityDDL.dataSource = [];
    }
}
</script>

Pattern 3: Remote Data with Filtering (Secure Same-Origin Proxy)

模式3：带过滤的远程数据（安全的同源代理）

⚠️ Security Note: Avoid

crossDomain="true"

and direct binding to external OData/WebAPI endpoints. Always proxy through your own server to control validation and access.

cshtml

<!-- ✅ SECURE: Remove crossDomain, use same-origin server proxy -->
<ejs-dropdownlist id="customers"
    allowFiltering="true"
    filtering="onfiltering"
    query="new ej.data.Query().from('api/customers').select(['ContactName', 'CustomerID']).take(6)"
    placeholder="Select a customer"
    popupHeight="200px">
    <e-dropdownlist-fields text="ContactName" value="CustomerID"></e-dropdownlist-fields>
    <e-data-manager url="/api/customers"
                    adaptor="UrlAdaptor">  <!-- UrlAdaptor for same-origin JSON endpoint -->
    </e-data-manager>
</ejs-dropdownlist>

<script>
function onfiltering(e) {
    var ddl = document.getElementById("customers").ej2_instances[0];
    var query = new ej.data.Query().from('api/customers').select(['ContactName', 'CustomerID']).take(6);
    query = e.text !== '' ? query.where('ContactName', 'startswith', e.text, true) : query;
    e.updateData(ddl.dataSource, query);
}
</script>

Controller (Server-Side Proxy):

csharp

// ✅ SECURE: Server validates, filters, and returns safe subset of data
[HttpGet("api/customers")]
public IActionResult GetCustomers([FromQuery] string skip = "0", [FromQuery] string take = "6", [FromQuery] string where = "")
{
    int skipVal = Math.Max(0, int.TryParse(skip, out var s) ? s : 0);
    int takeVal = Math.Min(50, int.TryParse(take, out var t) && t > 0 ? t : 6);
    
    // Example: fetch from secure internal data source
    var customers = _context.Customers
        .AsNoTracking()
        .Select(c => new { c.CustomerID, c.ContactName })
        .Skip(skipVal)
        .Take(takeVal)
        .ToList();
    
    return Ok(new { d = customers, count = customers.Count });
}

⚠️ 安全提示: 避免使用

crossDomain="true"

并直接绑定到外部OData/WebAPI端点，请始终通过自己的服务器进行代理，以控制验证和访问权限。

cshtml

<!-- ✅ SECURE: Remove crossDomain, use same-origin server proxy -->
<ejs-dropdownlist id="customers"
    allowFiltering="true"
    filtering="onfiltering"
    query="new ej.data.Query().from('api/customers').select(['ContactName', 'CustomerID']).take(6)"
    placeholder="Select a customer"
    popupHeight="200px">
    <e-dropdownlist-fields text="ContactName" value="CustomerID"></e-dropdownlist-fields>
    <e-data-manager url="/api/customers"
                    adaptor="UrlAdaptor">  <!-- UrlAdaptor for same-origin JSON endpoint -->
    </e-data-manager>
</ejs-dropdownlist>

<script>
function onfiltering(e) {
    var ddl = document.getElementById("customers").ej2_instances[0];
    var query = new ej.data.Query().from('api/customers').select(['ContactName', 'CustomerID']).take(6);
    query = e.text !== '' ? query.where('ContactName', 'startswith', e.text, true) : query;
    e.updateData(ddl.dataSource, query);
}
</script>

控制器（服务器端代理）:

csharp

// ✅ SECURE: Server validates, filters, and returns safe subset of data
[HttpGet("api/customers")]
public IActionResult GetCustomers([FromQuery] string skip = "0", [FromQuery] string take = "6", [FromQuery] string where = "")
{
    int skipVal = Math.Max(0, int.TryParse(skip, out var s) ? s : 0);
    int takeVal = Math.Min(50, int.TryParse(take, out var t) && t > 0 ? t : 6);
    
    // Example: fetch from secure internal data source
    var customers = _context.Customers
        .AsNoTracking()
        .Select(c => new { c.CustomerID, c.ContactName })
        .Skip(skipVal)
        .Take(takeVal)
        .ToList();
    
    return Ok(new { d = customers, count = customers.Count });
}

Key Properties and When to Use

核心属性及适用场景

Property	Attribute	When to Use
`DataSource`	`dataSource`	Always required to populate items
`Fields`	`<e-dropdownlist-fields>`	When binding complex JSON objects
`Value`	`value`	Pre-selecting an item
`Index`	`index`	Pre-selecting by position
`AllowFiltering`	`allowFiltering`	For lists with many items
`FilterType`	`filterType`	Customize search match behavior
`DebounceDelay`	`debounceDelay`	Reduce filter frequency while typing
`EnableVirtualization`	`enableVirtualization`	For very large datasets
`AllowResize`	`allowResize`	Allow user to resize popup
`ItemTemplate`	`itemTemplate`	Rich item rendering
`ValueTemplate`	`valueTemplate`	Custom selected value display
`GroupTemplate`	`groupTemplate`	Custom group headers
`ShowClearButton`	`showClearButton`	Allow clearing selection
`Enabled`	`enabled`	Conditional enable/disable
`Readonly`	`readonly`	Display-only mode
`EnableRtl`	`enableRtl`	RTL language support
`Locale`	`locale`	Localized text

属性	标签属性	适用场景
`DataSource`	`dataSource`	填充列表项时必填
`Fields`	`<e-dropdownlist-fields>`	绑定复杂JSON对象时使用
`Value`	`value`	预选择项时使用
`Index`	`index`	通过位置预选择项时使用
`AllowFiltering`	`allowFiltering`	列表项较多时使用
`FilterType`	`filterType`	自定义搜索匹配行为时使用
`DebounceDelay`	`debounceDelay`	减少输入时的过滤频率
`EnableVirtualization`	`enableVirtualization`	处理超大型数据集时使用
`AllowResize`	`allowResize`	允许用户调整弹窗大小时使用
`ItemTemplate`	`itemTemplate`	实现富文本项渲染时使用
`ValueTemplate`	`valueTemplate`	自定义选中值显示时使用
`GroupTemplate`	`groupTemplate`	自定义分组头时使用
`ShowClearButton`	`showClearButton`	允许清除选中值时使用
`Enabled`	`enabled`	需要条件启用/禁用组件时使用
`Readonly`	`readonly`	仅展示模式时使用
`EnableRtl`	`enableRtl`	支持RTL语言时使用
`Locale`	`locale`	需要本地化文本时使用

Next Steps

下一步操作

Just starting? → Getting Started
Binding server data? → Data Binding
Need filtering or grouping? → Filtering and Grouping
Customizing appearance? → Templates and Styling
Accessibility or localization? → Accessibility and Localization
Virtual scroll, resize, cascading? → Advanced Scenarios
Complete API reference? → API Reference

刚入门？ → 快速入门
绑定服务器数据？ → 数据绑定
需要过滤或分组？ → 过滤与分组
自定义外观？ → 模板与样式
无障碍或本地化？ → 无障碍与本地化
虚拟滚动、弹窗调整、级联？ → 高级场景
完整API参考？ → API参考

Implementing MultiSelect Dropdown in ASP.NET Core

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

The Syncfusion MultiSelect Dropdown is a powerful component for selecting multiple values from a predefined list. It supports checkbox selection, filtering, grouping, templates, virtual scrolling, and rich data binding — all using ASP.NET Core TagHelper syntax.

Syncfusion MultiSelect下拉列表是一款功能强大的组件，支持从预定义列表中选择多个值。它支持复选框选择、过滤、分组、模板、虚拟滚动和丰富的数据绑定——全部使用ASP.NET Core TagHelper语法。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

NuGet package installation and TagHelper setup
CDN stylesheet and script references
First MultiSelect with basic configuration
Popup height/width configuration
Form integration and MultiSelectFor

📄 阅读: references/getting-started.md

NuGet包安装及TagHelper配置
CDN样式表和脚本引用
第一个MultiSelect的基础配置
弹窗高度/宽度配置
表单集成及MultiSelectFor

Data Binding & Value Binding

数据绑定与值绑定

📄 Read: references/data-binding.md

Binding array of strings, objects, and complex data
Remote data: OData, WebAPI, URL Adaptor, offline mode
Fields mapping (text, value, groupBy, iconCss, disabled)
Primitive vs object value binding (
```
allowObjectBinding
```
)
Preselecting values via
```
value
```
property
Using
```
isSelected
```
field to preselect via data source

📄 阅读: references/data-binding.md

绑定字符串数组、对象数组及复杂数据
远程数据：OData、WebAPI、URL适配器、离线模式
字段映射（text、value、groupBy、iconCss、disabled）
基本类型与对象值绑定（
```
allowObjectBinding
```
）
通过
```
value
```
属性预选择值
使用
```
isSelected
```
字段通过数据源预选择

Checkbox & Selection Modes

复选框与选择模式

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

Checkbox mode with
```
CheckBoxSelection
```
module
Select All / Unselect All with
```
showSelectAll
```
Customizing "Select All" and "Unselect All" text
Maximum selection limit (
```
maximumSelectionLength
```
)
Selection reordering (
```
enableSelectionOrder
```
)
Display modes: Default, Box, Delimiter, CheckBox
```
closePopupOnSelect
```
behavior
```
hideSelectedItem
```
to remove selected items from list
```
changeOnBlur
```
for event timing control

📄 阅读: references/checkbox-and-selection.md

使用
```
CheckBoxSelection
```
模块启用复选框模式
使用
```
showSelectAll
```
实现全选/取消全选
自定义“全选”和“取消全选”文本
最大选择限制（
```
maximumSelectionLength
```
）
选择排序（
```
enableSelectionOrder
```
）
显示模式：默认、框式、分隔符、复选框
```
closePopupOnSelect
```
行为
使用
```
hideSelectedItem
```
从列表中移除已选项目
使用
```
changeOnBlur
```
控制事件触发时机

Filtering

过滤

📄 Read: references/filtering.md

Enabling filtering with
```
allowFiltering
```
Filter types: StartsWith, Contains, EndsWith
Minimum character threshold before remote fetch
Case-sensitive filtering
Diacritics / accent-insensitive filtering (
```
ignoreAccent
```
)
Debounce delay (
```
debounceDelay
```
)
Custom filtering logic via
```
filtering
```
event

📄 阅读: references/filtering.md

使用
```
allowFiltering
```
启用过滤
过滤类型：StartsWith、Contains、EndsWith
触发远程请求的最小字符阈值
区分大小写过滤
支持变音符号/重音不敏感过滤（
```
ignoreAccent
```
）
防抖延迟（
```
debounceDelay
```
）
通过
```
filtering
```
事件实现自定义过滤逻辑

Templates & Customization

模板与定制

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

Item template for custom list item layout
Value template for selected chip display
Group template for category headers
Header and footer templates
No records template and action failure template
Chip customization via
```
tagging
```
event and
```
setClass
```
CSS customization for wrapper, chips, icons, popup
Icon support via
```
iconCss
```
field

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

项模板：自定义列表项布局
值模板：自定义选中标签的显示
分组模板：自定义分类头部
头部和底部模板
无数据模板和请求失败模板
通过
```
tagging
```
事件和
```
setClass
```
自定义标签样式
包装器、标签、图标、弹窗的CSS定制
通过
```
iconCss
```
字段支持图标

Grouping & Virtualization

分组与虚拟滚动

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

Grouping items using
```
groupBy
```
field
Grouping with checkboxes (
```
enableGroupCheckBox
```
)
Virtual scrolling for large datasets (
```
enableVirtualization
```
)
Virtualization with remote data, grouping, filtering, checkboxes
Preselecting values with virtualization
Custom item count in virtualization

📄 阅读: references/grouping-and-virtualization.md

使用
```
groupBy
```
字段对项进行分组
结合复选框的分组（
```
enableGroupCheckBox
```
）
针对大型数据集的虚拟滚动（
```
enableVirtualization
```
）
结合远程数据、分组、过滤、复选框的虚拟滚动
虚拟滚动下的预选择值
自定义虚拟滚动中的项数量

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Custom value entry (
```
allowCustomValue
```
)
Disabled items via
```
fields.disabled
```
```
disableItem
```
method for dynamic disabling
Popup resize (
```
allowResize
```
)
Localization (
```
locale
```
, L10n translations)
Accessibility (WCAG 2.2, keyboard navigation, ARIA)
Sorting (
```
sortOrder
```
)
Right-to-left support (
```
enableRtl
```
)
State persistence (
```
enablePersistence
```
)
```
addTagOnBlur
```
behavior
```
openOnClick
```
configuration

📄 阅读: references/advanced-features.md

自定义值输入（
```
allowCustomValue
```
）
通过
```
fields.disabled
```
禁用项
使用
```
disableItem
```
方法动态禁用项
弹窗调整大小（
```
allowResize
```
）
本地化（
```
locale
```
、L10n翻译）
无障碍支持（WCAG 2.2、键盘导航、ARIA）
排序（
```
sortOrder
```
）
从右到左支持（
```
enableRtl
```
）
状态持久化（
```
enablePersistence
```
）
```
addTagOnBlur
```
行为
```
openOnClick
```
配置

API Reference

API参考

📄 Read: references/api.md

Complete properties reference with types and defaults
All events with descriptions
FieldSettings sub-properties
TagHelper attribute naming conventions

📄 阅读: references/api.md

完整的属性参考，包含类型和默认值
所有事件及描述
FieldSettings子属性
TagHelper属性命名规范

Quick Start Example

快速入门示例

cshtml

@* _ViewImports.cshtml: @addTagHelper *, Syncfusion.EJ2 *@

@{
    var games = new List<object> {
        new { Id = 1, Game = "Football" },
        new { Id = 2, Game = "Basketball" },
        new { Id = 3, Game = "Cricket" },
        new { Id = 4, Game = "Tennis" }
    };
}

<ejs-multiselect id="games"
    dataSource="@games"
    placeholder="Select games"
    mode="Box">
    <e-multiselect-fields text="Game" value="Id"></e-multiselect-fields>
</ejs-multiselect>

cshtml

@* _ViewImports.cshtml: @addTagHelper *, Syncfusion.EJ2 *@

@{
    var games = new List<object> {
        new { Id = 1, Game = "Football" },
        new { Id = 2, Game = "Basketball" },
        new { Id = 3, Game = "Cricket" },
        new { Id = 4, Game = "Tennis" }
    };
}

<ejs-multiselect id="games"
    dataSource="@games"
    placeholder="Select games"
    mode="Box">
    <e-multiselect-fields text="Game" value="Id"></e-multiselect-fields>
</ejs-multiselect>

Common Patterns

常见模式

Checkbox Mode with Select All

带全选功能的复选框模式

cshtml

<ejs-multiselect id="sports"
    dataSource="@ViewBag.Sports"
    placeholder="Select sports"
    mode="CheckBox"
    showSelectAll="true"
    selectAllText="Select All"
    unSelectAllText="Unselect All"
    filterBarPlaceholder="Search">
    <e-multiselect-fields text="Game" value="Id"></e-multiselect-fields>
</ejs-multiselect>

cshtml

<ejs-multiselect id="sports"
    dataSource="@ViewBag.Sports"
    placeholder="Select sports"
    mode="CheckBox"
    showSelectAll="true"
    selectAllText="Select All"
    unSelectAllText="Unselect All"
    filterBarPlaceholder="Search">
    <e-multiselect-fields text="Game" value="Id"></e-multiselect-fields>
</ejs-multiselect>

Filtering with Remote Data

带过滤的远程数据

cshtml

<ejs-multiselect id="customers"
    placeholder="Search customers"
    allowFiltering="true"
    filtering="onFiltering"
    popupHeight="250px">
    <e-data-manager url="url"
        adaptor="ODataV4Adaptor" crossDomain="true">
    </e-data-manager>
    <e-multiselect-fields text="ContactName" value="CustomerID"></e-multiselect-fields>
</ejs-multiselect>

cshtml

<ejs-multiselect id="customers"
    placeholder="Search customers"
    allowFiltering="true"
    filtering="onFiltering"
    popupHeight="250px">
    <e-data-manager url="url"
        adaptor="ODataV4Adaptor" crossDomain="true">
    </e-data-manager>
    <e-multiselect-fields text="ContactName" value="CustomerID"></e-multiselect-fields>
</ejs-multiselect>

Virtual Scroll for Large Data

大型数据的虚拟滚动

cshtml

<ejs-multiselect id="items"
    dataSource="@ViewBag.LargeDataset"
    enableVirtualization="true"
    allowFiltering="true"
    placeholder="Select items"
    popupHeight="200px">
    <e-multiselect-fields text="text" value="id"></e-multiselect-fields>
</ejs-multiselect>

cshtml

<ejs-multiselect id="items"
    dataSource="@ViewBag.LargeDataset"
    enableVirtualization="true"
    allowFiltering="true"
    placeholder="Select items"
    popupHeight="200px">
    <e-multiselect-fields text="text" value="id"></e-multiselect-fields>
</ejs-multiselect>

Key Properties Quick Reference

核心属性快速参考

Property	TagHelper Attribute	Purpose
`DataSource`	`dataSource`	Local array or DataManager
`Value`	`value`	Pre-selected values
`Mode`	`mode`	Default, Box, Delimiter, CheckBox
`AllowFiltering`	`allowFiltering`	Enable search/filter
`ShowSelectAll`	`showSelectAll`	Show "Select All" in checkbox mode
`MaximumSelectionLength`	`maximumSelectionLength`	Limit selections
`EnableVirtualization`	`enableVirtualization`	Virtual scroll
`AllowCustomValue`	`allowCustomValue`	Accept new typed values
`Placeholder`	`placeholder`	Input placeholder text
`PopupHeight`	`popupHeight`	Popup list height
`PopupWidth`	`popupWidth`	Popup list width
`AllowResize`	`allowResize`	Resizable popup

属性	TagHelper属性	用途
`DataSource`	`dataSource`	本地数组或DataManager
`Value`	`value`	预选择值
`Mode`	`mode`	默认、框式、分隔符、复选框
`AllowFiltering`	`allowFiltering`	启用搜索/过滤
`ShowSelectAll`	`showSelectAll`	复选框模式下显示“全选”
`MaximumSelectionLength`	`maximumSelectionLength`	限制选择数量
`EnableVirtualization`	`enableVirtualization`	虚拟滚动
`AllowCustomValue`	`allowCustomValue`	接受手动输入的新值
`Placeholder`	`placeholder`	输入框占位文本
`PopupHeight`	`popupHeight`	弹窗列表高度
`PopupWidth`	`popupWidth`	弹窗列表宽度
`AllowResize`	`allowResize`	可调整大小的弹窗

Common Use Cases

常见使用场景

Multi-tag input → Use
```
mode="Box"
```
with
```
tagging
```
event for chip styling
Permission selector → Checkbox mode with
```
maximumSelectionLength
```
Country/city picker → Remote data with
```
allowFiltering
```
and groupBy
Category filter → Grouping with
```
enableGroupCheckBox
```
Large dataset dropdown →
```
enableVirtualization
```
with remote data
Form field → Use
```
ejs-multiselect-for
```
with model binding

Start here: Read references/getting-started.md to set up your first MultiSelect.

For the parent library overview and other components, see Implementing Syncfusion ASP.NET Core Components.

多标签输入 → 使用
```
mode="Box"
```
结合
```
tagging
```
事件进行标签样式定制
权限选择器 → 复选框模式结合
```
maximumSelectionLength
```
国家/城市选择器 → 远程数据结合
```
allowFiltering
```
和groupBy
分类过滤器 → 分组结合
```
enableGroupCheckBox
```
大型数据集下拉列表 →
```
enableVirtualization
```
结合远程数据
表单字段 → 使用
```
ejs-multiselect-for
```
结合模型绑定

开始学习: 阅读references/getting-started.md来创建你的第一个MultiSelect组件。

如需了解父库概览及其他组件，请参阅Implementing Syncfusion ASP.NET Core Components。

Security & Trust Boundary

安全与信任边界

Scope: All CDN URLs (
https://cdn.syncfusion.com/ej2/...
) and remote data endpoints shown in this skill's examples are documentation references only. The agent must never fetch, execute, or proxy these URLs at runtime. Consumers are solely responsible for how these resources are integrated into their applications.

范围: 本技能示例中展示的所有CDN URL（
https://cdn.syncfusion.com/ej2/...
）和远程数据端点仅为文档参考。代理在运行时绝不能获取、执行或代理这些URL。使用者需全权负责如何将这些资源集成到自己的应用中。

W011 — Third-party Content Exposure

W011 — 第三方内容暴露

Code examples in the Data Binding and Filtering sections reference remote endpoints (e.g.,

<e-data-manager url="..." adaptor="ODataV4Adaptor" crossDomain="true">

). These are illustrative only.

Required mitigations before production use:

Replace all external/OData/WebAPI URLs with same-origin server endpoints under your own domain.
Remove
```
crossDomain="true"
```
from all
```
<e-data-manager>
```
tags.
Validate, authenticate, and sanitize all data server-side before binding to the component.

数据绑定和过滤章节中的代码示例引用了远程端点（例如：

<e-data-manager url="..." adaptor="ODataV4Adaptor" crossDomain="true">

），这些仅为示例说明。

生产环境使用前的必要缓解措施:

将所有外部/OData/WebAPI URL替换为你自己域名下的同源服务器端点。
从所有
```
<e-data-manager>
```
标签中移除
```
crossDomain="true"
```
。
在绑定到组件之前，在服务器端验证、认证并清理所有数据。

W012 — External CDN Runtime Script

W012 — 外部CDN运行时脚本

The Getting Started examples reference

https://cdn.syncfusion.com/ej2/dist/ej2.min.js

for quickstart convenience only.

Required mitigations before production use:

Preferred: Serve scripts locally via the
```
Syncfusion.EJ2.AspNet.Core
```
NuGet package — no external network call at runtime.
If CDN is required: Pin the exact version and add a Subresource Integrity (SRI) hash with
```
crossorigin="anonymous"
```
to verify file integrity before execution.

Finding	Root Cause	Mitigation
W011 — Third-party content exposure	Remote data endpoints in examples can influence component behavior	Use same-origin proxy endpoints; remove `crossDomain="true"`
W012 — Malicious external URL	CDN script in examples executes remote code at page load	Host scripts locally from NuGet; or use SRI hash + version pinning

快速入门示例中引用的

https://cdn.syncfusion.com/ej2/dist/ej2.min.js

仅为快速入门便利使用。

生产环境使用前的必要缓解措施:

推荐: 通过
```
Syncfusion.EJ2.AspNet.Core
```
NuGet包本地托管脚本——运行时无需外部网络请求。
若必须使用CDN: 固定精确版本并添加子资源完整性（SRI）哈希及
```
crossorigin="anonymous"
```
，以在执行前验证文件完整性。

问题	根本原因	缓解措施
W011 — 第三方内容暴露	示例中的远程数据端点会影响组件行为	使用同源代理端点；移除 `crossDomain="true"`
W012 — 恶意外部URL	示例中的CDN脚本在页面加载时执行远程代码	从NuGet本地托管脚本；或使用SRI哈希+版本固定

Implementing AutoComplete in ASP.NET Core

在ASP.NET Core中实现AutoComplete

The Syncfusion ASP.NET Core AutoComplete (

<ejs-autocomplete>

) is a textbox component that provides a list of suggestions as users type. It supports local and remote data binding, filtering, grouping, templates, virtual scrolling, accessibility, and rich customization options.

Syncfusion ASP.NET Core AutoComplete（

<ejs-autocomplete>

）是一款文本框组件，可在用户输入时提供建议列表。它支持本地与远程数据绑定、过滤、分组、模板、虚拟滚动、无障碍及丰富的定制选项。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

NuGet package installation and setup
Tag helper registration and CDN references
Basic AutoComplete rendering with
```
<ejs-autocomplete>
```
Custom values with
```
allowCustom
```
Popup height and width configuration

📄 阅读: references/getting-started.md

NuGet包安装及配置
Tag Helper注册及CDN引用
使用
```
<ejs-autocomplete>
```
渲染基础AutoComplete
使用
```
allowCustom
```
支持自定义值
弹窗高度和宽度配置

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding array of strings and array of objects
Binding complex/nested object data
Remote data binding (OData, OData V4, Web API, URL Adaptor)
Offline mode with DataManager
Fields mapping (
```
value
```
,
```
groupBy
```
,
```
iconCss
```
)

📄 阅读: references/data-binding.md

绑定字符串数组和对象数组
绑定复杂/嵌套对象数据
远程数据绑定（OData、OData V4、Web API、URL适配器）
使用DataManager的离线模式
字段映射（
```
value
```
、
```
groupBy
```
、
```
iconCss
```
）

Filtering

过滤

📄 Read: references/filtering.md

Filter types:
```
StartsWith
```
,
```
EndsWith
```
,
```
Contains
```
Limiting suggestion count with
```
suggestionCount
```
Minimum character length with
```
minLength
```
Case-sensitive filtering with
```
ignoreCase
```
Diacritics/accent-insensitive filtering with
```
ignoreAccent
```
Debounce delay to reduce filtering frequency

📄 阅读: references/filtering.md

过滤类型：
```
StartsWith
```
、
```
EndsWith
```
、
```
Contains
```
使用
```
suggestionCount
```
限制建议数量
使用
```
minLength
```
设置最小字符长度
使用
```
ignoreCase
```
区分大小写过滤
使用
```
ignoreAccent
```
支持变音符号/重音不敏感过滤
使用防抖延迟减少过滤频率

Grouping

分组

📄 Read: references/grouping.md

Grouping list items by category using
```
groupBy
```
field
Inline and fixed group headers
Custom group header with
```
groupTemplate
```

📄 阅读: references/grouping.md

使用
```
groupBy
```
字段按类别分组列表项
内联和固定分组头
使用
```
groupTemplate
```
自定义分组头

Templates

模板

📄 Read: references/templates.md

Item template (
```
itemTemplate
```
) for custom list item content
Group template (
```
groupTemplate
```
) for group headers
Header template (
```
headerTemplate
```
) for static popup header
Footer template (
```
footerTemplate
```
) for static popup footer
No records template (
```
noRecordsTemplate
```
)
Action failure template (
```
actionFailureTemplate
```
)

📄 阅读: references/templates.md

项模板（
```
itemTemplate
```
）：自定义列表项内容
分组模板（
```
groupTemplate
```
）：自定义分组头
头部模板（
```
headerTemplate
```
）：弹窗静态头部
底部模板（
```
footerTemplate
```
）：弹窗静态底部
无数据模板（
```
noRecordsTemplate
```
）
请求失败模板（
```
actionFailureTemplate
```
）

Value Binding

值绑定

📄 Read: references/value-binding.md

Binding primitive values (string, number, boolean) with
```
value
```
Object binding with
```
allowObjectBinding
```
Pre-selecting values

📄 阅读: references/value-binding.md

使用
```
value
```
绑定基本类型值（字符串、数字、布尔值）
使用
```
allowObjectBinding
```
进行对象绑定
预选择值

Virtual Scrolling

虚拟滚动

📄 Read: references/virtual-scroll.md

Enable virtualization with
```
enableVirtualization
```
Virtual scrolling with local data
Virtual scrolling with remote data
Customizing item count in virtualization
Grouping with virtualization

📄 阅读: references/virtual-scroll.md

使用
```
enableVirtualization
```
启用虚拟化
本地数据的虚拟滚动
远程数据的虚拟滚动
自定义虚拟化中的项数量
结合分组的虚拟化

Disabled Items & Component State

禁用项与组件状态

📄 Read: references/disabled-items.md

Disabling individual items with
```
fields.disabled
```
Using
```
disableItem
```
method dynamically
Disabling the entire component with
```
enabled
```

📄 阅读: references/disabled-items.md

使用
```
fields.disabled
```
禁用单个项
使用
```
disableItem
```
方法动态禁用项
使用
```
enabled
```
禁用整个组件

Localization

本地化

📄 Read: references/localization.md

Localizing
```
noRecordsTemplate
```
and
```
actionFailureTemplate
```
Loading translations with L10n
Setting locale with
```
locale
```
property

📄 阅读: references/localization.md

本地化
```
noRecordsTemplate
```
和
```
actionFailureTemplate
```
使用L10n加载翻译
使用
```
locale
```
属性设置区域

Popup Resizing

弹窗调整大小

📄 Read: references/resize.md

Enabling resizable popup with
```
allowResize
```
Resize persistence across sessions

📄 阅读: references/resize.md

使用
```
allowResize
```
启用可调整大小的弹窗
跨会话的调整大小持久化

Styling & CSS Customization

样式与CSS定制

📄 Read: references/style.md

Customizing wrapper, icon, focus, placeholder, text selection
Customizing popup item appearance
Outline theme and float label customization

📄 阅读: references/style.md

自定义包装器、图标、焦点、占位符、文本选择样式
自定义弹窗项外观
轮廓主题和浮动标签定制

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.2, Section 508, screen reader support
WAI-ARIA attributes and roles
Full keyboard navigation shortcuts

📄 阅读: references/accessibility.md

支持WCAG 2.2、Section 508、屏幕阅读器
WAI-ARIA属性和角色
完整的键盘导航快捷键

How-To Scenarios

操作场景

📄 Read: references/how-to.md

Autofill (auto-complete while typing with
```
autofill
```
)
Custom highlight search (
```
highlight
```
property)
Show list items with icons (
```
iconCss
```
)
Filter by both text and value fields
AutoCompleteFor with model binding and data annotations

📄 阅读: references/how-to.md

自动填充（输入时自动补全，使用
```
autofill
```
）
自定义高亮搜索（
```
highlight
```
属性）
显示带图标的列表项（
```
iconCss
```
）
同时按文本和值字段过滤
使用AutoCompleteFor结合模型绑定和数据注释

API Reference

API参考

📄 Read: references/api.md

Complete list of all properties, events, and their default values

Properties:

actionFailureTemplate

allowCustom

allowObjectBinding

allowResize

autofill

cssClass

dataSource

debounceDelay

enabled

enablePersistence

enableRtl

enableVirtualization

fields

filterType

floatLabelType

footerTemplate

groupTemplate

headerTemplate

highlight

htmlAttributes

ignoreAccent

ignoreCase

isDeviceFullScreen

itemTemplate

locale

minLength

noRecordsTemplate

placeholder

popupHeight

popupWidth

query

readonly

showClearButton

showPopupButton

sortOrder

suggestionCount

value

width

zIndex

Events:

actionBegin

actionComplete

actionFailure

beforeOpen

blur

change

close

created

customValueSpecifier

dataBound

destroyed

filtering

focus

open

resizeStart

resizeStop

resizing

select

📄 阅读: references/api.md

完整的属性、事件列表及默认值

属性：

actionFailureTemplate

、

allowCustom

、

allowObjectBinding

、

allowResize

、

autofill

、

cssClass

、

dataSource

、

debounceDelay

、

enabled

、

enablePersistence

、

enableRtl

、

enableVirtualization

、

fields

、

filterType

、

floatLabelType

、

footerTemplate

、

groupTemplate

、

headerTemplate

、

highlight

、

htmlAttributes

、

ignoreAccent

、

ignoreCase

、

isDeviceFullScreen

、

itemTemplate

、

locale

、

minLength

、

noRecordsTemplate

、

placeholder

、

popupHeight

、

popupWidth

、

query

、

readonly

、

showClearButton

、

showPopupButton

、

sortOrder

、

suggestionCount

、

value

、

width

、

zIndex

事件：

actionBegin

、

actionComplete

、

actionFailure

、

beforeOpen

、

blur

、

change

、

close

、

created

、

customValueSpecifier

、

dataBound

、

destroyed

、

filtering

、

focus

、

open

、

resizeStart

、

resizeStop

、

resizing

、

select

Quick Start

快速入门

Basic AutoComplete (array of strings):

cshtml

@{
    var sports = new string[] { "Badminton", "Basketball", "Cricket", "Football", "Golf", "Hockey", "Tennis" };
}

<ejs-autocomplete id="sports" dataSource="sports" placeholder="Select a sport">
</ejs-autocomplete>

AutoComplete with object data source:

cshtml

@{
    List<Countries> countries = new List<Countries> {
        new Countries { Name = "India", Code = "IN" },
        new Countries { Name = "United States", Code = "US" },
        new Countries { Name = "Germany", Code = "DE" }
    };
}

<ejs-autocomplete id="country" dataSource="@countries" placeholder="Select a country">
    <e-autocomplete-fields value="Name"></e-autocomplete-fields>
</ejs-autocomplete>

Model class:

csharp

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

基础AutoComplete（字符串数组）:

cshtml

@{
    var sports = new string[] { "Badminton", "Basketball", "Cricket", "Football", "Golf", "Hockey", "Tennis" };
}

<ejs-autocomplete id="sports" dataSource="sports" placeholder="Select a sport">
</ejs-autocomplete>

带对象数据源的AutoComplete:

cshtml

@{
    List<Countries> countries = new List<Countries> {
        new Countries { Name = "India", Code = "IN" },
        new Countries { Name = "United States", Code = "US" },
        new Countries { Name = "Germany", Code = "DE" }
    };
}

<ejs-autocomplete id="country" dataSource="@countries" placeholder="Select a country">
    <e-autocomplete-fields value="Name"></e-autocomplete-fields>
</ejs-autocomplete>

模型类:

csharp

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

Common Patterns

常见模式

Remote Data with OData

带OData的远程数据

cshtml

<ejs-autocomplete id="customers"
    query="new ej.data.Query().from('Customers').select(['ContactName'])"
    placeholder="Find a customer"
    filterType="StartsWith"
    popupHeight="200px">
    <e-autocomplete-fields value="ContactName"></e-autocomplete-fields>
    <e-data-manager url="url"
        adaptor="ODataV4Adaptor" crossDomain="true">
    </e-data-manager>
</ejs-autocomplete>

cshtml

<ejs-autocomplete id="customers"
    query="new ej.data.Query().from('Customers').select(['ContactName'])"
    placeholder="Find a customer"
    filterType="StartsWith"
    popupHeight="200px">
    <e-autocomplete-fields value="ContactName"></e-autocomplete-fields>
    <e-data-manager url="url"
        adaptor="ODataV4Adaptor" crossDomain="true">
    </e-data-manager>
</ejs-autocomplete>

Grouped List with Custom Filter

带自定义过滤的分组列表

cshtml

<ejs-autocomplete id="vegetables"
    dataSource="@vegList"
    placeholder="Select a vegetable"
    filterType="StartsWith"
    suggestionCount="10"
    minLength="1">
    <e-autocomplete-fields value="Vegetable" groupBy="Category"></e-autocomplete-fields>
</ejs-autocomplete>

cshtml

<ejs-autocomplete id="vegetables"
    dataSource="@vegList"
    placeholder="Select a vegetable"
    filterType="StartsWith"
    suggestionCount="10"
    minLength="1">
    <e-autocomplete-fields value="Vegetable" groupBy="Category"></e-autocomplete-fields>
</ejs-autocomplete>

Virtual Scrolling for Large Data

大型数据的虚拟滚动

cshtml

<ejs-autocomplete id="records"
    dataSource="@data"
    placeholder="e.g. Item 1"
    enableVirtualization="true"
    popupHeight="200px">
    <e-autocomplete-fields value="Text"></e-autocomplete-fields>
</ejs-autocomplete>

cshtml

<ejs-autocomplete id="records"
    dataSource="@data"
    placeholder="e.g. Item 1"
    enableVirtualization="true"
    popupHeight="200px">
    <e-autocomplete-fields value="Text"></e-autocomplete-fields>
</ejs-autocomplete>

Key Properties Quick Reference

核心属性快速参考

Property	Type	Default	Purpose
`dataSource`	object	null	Local array or DataManager
`fields`	AutoCompleteFieldSettings	null	Map value, groupBy, iconCss
`filterType`	FilterType	Contains	StartsWith / EndsWith / Contains
`placeholder`	string	null	Input hint text
`value`	object	null	Selected value
`allowCustom`	bool	true	Allow values not in data source
`minLength`	double	1	Minimum chars before filtering
`suggestionCount`	double	20	Max suggestion items
`autofill`	bool	false	Auto-complete first match inline
`highlight`	bool	false	Highlight matched characters
`enableVirtualization`	bool	false	Virtual scrolling for large lists
`allowResize`	bool	false	Resizable popup
`enabled`	bool	true	Enable/disable component

属性	类型	默认值	用途
`dataSource`	object	null	本地数组或DataManager
`fields`	AutoCompleteFieldSettings	null	映射value、groupBy、iconCss
`filterType`	FilterType	Contains	StartsWith / EndsWith / Contains
`placeholder`	string	null	输入提示文本
`value`	object	null	选中值
`allowCustom`	bool	true	允许数据源中不存在的值
`minLength`	double	1	触发过滤的最小字符数
`suggestionCount`	double	20	最大建议项数量
`autofill`	bool	false	自动补全第一个匹配项
`highlight`	bool	false	高亮匹配字符
`enableVirtualization`	bool	false	大型列表的虚拟滚动
`allowResize`	bool	false	可调整大小的弹窗
`enabled`	bool	true	启用/禁用组件

Implementing Mention in ASP.NET Core

在ASP.NET Core中实现Mention

The Syncfusion ASP.NET Core Mention (

<ejs-mention>

) is an inline suggestion component that listens to a target element (a

contenteditable

div or textarea) and displays a suggestion popup when the user types a trigger character (default:

). It supports local and remote data binding, custom templates, configurable filtering, sorting, disabled items, and full accessibility.

Syncfusion ASP.NET Core Mention（

<ejs-mention>

）是一款内联建议组件，监听目标元素（

contenteditable

div或textarea），当用户输入触发字符（默认：

）时显示建议弹窗。它支持本地与远程数据绑定、自定义模板、可配置过滤、排序、禁用项及完整的无障碍特性。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

NuGet package installation and project setup
Tag helper registration (
```
@addTagHelper *, Syncfusion.EJ2
```
)
CDN stylesheet and script references
Script manager registration (
```
<ejs-scripts>
```
)
Defining the target
```
contenteditable
```
element
Basic Mention rendering with
```
<ejs-mention>
```
Binding a string array as data source
Displaying the mention character with
```
showMentionChar
```
and
```
mentionChar
```

📄 阅读: references/getting-started.md

NuGet包安装及项目配置
Tag Helper注册（
```
@addTagHelper *, Syncfusion.EJ2
```
）
CDN样式表和脚本引用
脚本管理器注册（
```
<ejs-scripts>
```
）
定义目标
```
contenteditable
```
元素
使用
```
<ejs-mention>
```
渲染基础Mention组件
绑定字符串数组作为数据源
使用
```
showMentionChar
```
和
```
mentionChar
```
显示触发字符

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding simple string arrays
Binding arrays of JSON objects with
```
<e-mention-fields>
```
Binding complex/nested object data with dot-notation field mapping
Remote data binding with OData V4 adaptor
Remote data binding with Web API adaptor
Using
```
<e-data-manager>
```
for remote sources
```
query
```
property for customizing remote fetch requests

📄 阅读: references/data-binding.md

绑定简单字符串数组
使用
```
<e-mention-fields>
```
绑定JSON对象数组
使用点标记字段映射绑定复杂/嵌套对象数据
使用OData V4适配器绑定远程数据
使用Web API适配器绑定远程数据
使用
```
<e-data-manager>
```
处理远程数据源
使用
```
query
```
属性自定义远程请求

Filtering

过滤

📄 Read: references/filtering.md

Filter types:
```
StartsWith
```
,
```
EndsWith
```
,
```
Contains
```
via
```
filterType
```
Minimum character length with
```
minLength
```
(default: 0)
Allow spaces in search with
```
allowSpaces
```
Limit visible suggestions with
```
suggestionCount
```
Case-sensitive filtering with
```
ignoreCase
```
Reducing filter calls with
```
debounceDelay
```
Custom server-side filtering with the
```
filtering
```
event

📄 阅读: references/filtering.md

过滤类型：通过
```
filterType
```
设置
```
StartsWith
```
、
```
EndsWith
```
、
```
Contains
```
使用
```
minLength
```
设置最小字符长度（默认：0）
使用
```
allowSpaces
```
允许搜索中包含空格
使用
```
suggestionCount
```
限制可见建议数量
使用
```
ignoreCase
```
区分大小写过滤
使用
```
debounceDelay
```
减少过滤请求次数
通过
```
filtering
```
事件实现自定义服务器端过滤

Templates

模板

📄 Read: references/templates.md

```
itemTemplate
```
— customize each item in the suggestion popup
```
displayTemplate
```
— customize what is inserted into the editor upon selection
```
noRecordsTemplate
```
— custom message when no items match search
```
spinnerTemplate
```
— custom loading indicator for remote data

📄 阅读: references/templates.md

```
itemTemplate
```
— 自定义建议弹窗中的每个项
```
displayTemplate
```
— 自定义选中后插入编辑器的内容
```
noRecordsTemplate
```
— 无匹配项时的自定义消息
```
spinnerTemplate
```
— 远程数据加载时的自定义加载指示器

Customization

定制

📄 Read: references/customization.md

Show or hide mention character prefix with
```
showMentionChar
```
Change trigger character with
```
mentionChar
```
(default:
```
@
```
)
Append suffix after selection with
```
suffixText
```
(space, newline)
Control popup dimensions with
```
popupHeight
```
and
```
popupWidth
```
Leading space requirement with
```
requireLeadingSpace
```
Apply custom CSS styles with
```
cssClass
```
Highlight matched characters with
```
highlight
```

📄 阅读: references/customization.md

使用
```
showMentionChar
```
显示/隐藏触发字符前缀
使用
```
mentionChar
```
修改触发字符（默认：
```
@
```
）
使用
```
suffixText
```
在选中后追加后缀（空格、换行）
使用
```
popupHeight
```
和
```
popupWidth
```
控制弹窗尺寸
使用
```
requireLeadingSpace
```
设置触发字符前需要空格
使用
```
cssClass
```
应用自定义CSS样式
使用
```
highlight
```
高亮匹配字符

Disabled Items

禁用项

📄 Read: references/disabled-items.md

Disable individual items via
```
fields.disabled
```
data source mapping
Dynamically disable items at runtime using the
```
disableItem
```
method
Disable multiple items by iterating

📄 阅读: references/disabled-items.md

通过
```
fields.disabled
```
数据源映射禁用单个项
使用
```
disableItem
```
方法在运行时动态禁用项
通过循环禁用多个项

Sorting

排序

📄 Read: references/sorting.md

Sort suggestion list with
```
sortOrder
```
(
```
None
```
,
```
Ascending
```
,
```
Descending
```
)
Ascending and descending sort examples

📄 阅读: references/sorting.md

使用
```
sortOrder
```
对建议列表排序（
```
None
```
、
```
Ascending
```
、
```
Descending
```
）
升序和降序排序示例

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.2 (AA), Section 508, screen reader compliance

WAI-ARIA attributes (

aria-selected

aria-activedescendant

aria-owns

)

Full keyboard navigation (Arrow keys, Escape, Enter, Tab)
Tips for accessible target element setup

📄 阅读: references/accessibility.md

符合WCAG 2.2（AA）、Section 508、屏幕阅读器标准

WAI-ARIA属性（

aria-selected

、

aria-activedescendant

、

aria-owns

）

完整的键盘导航（箭头键、Esc、Enter、Tab）
无障碍目标元素设置技巧

API Reference

API参考

📄 Read: references/api.md

Complete properties:

allowSpaces

cssClass

dataSource

debounceDelay

displayTemplate

fields

filterType

highlight

htmlAttributes

ignoreCase

itemTemplate

locale

mentionChar

minLength

noRecordsTemplate

popupHeight

popupWidth

query

requireLeadingSpace

showMentionChar

sortOrder

spinnerTemplate

suffixText

suggestionCount

target

MentionFieldSettings:

text

value

groupBy

iconCss

disabled

htmlAttributes

All events:

actionBegin

actionComplete

actionFailure

beforeOpen

change

closed

created

destroyed

filtering

opened

select

📄 阅读: references/api.md

完整属性：

allowSpaces

、

cssClass

、

dataSource

、

debounceDelay

、

displayTemplate

、

fields

、

filterType

、

highlight

、

htmlAttributes

、

ignoreCase

、

itemTemplate

、

locale

、

mentionChar

、

minLength

、

noRecordsTemplate

、

popupHeight

、

popupWidth

、

query

、

requireLeadingSpace

、

showMentionChar

、

sortOrder

、

spinnerTemplate

、

suffixText

、

suggestionCount

、

target

MentionFieldSettings:

text

、

value

、

groupBy

、

iconCss

、

disabled

、

htmlAttributes

所有事件：

actionBegin

、

actionComplete

、

actionFailure

、

beforeOpen

、

change

、

closed

、

created

、

destroyed

、

filtering

、

opened

、

select

Quick Start

快速入门

Minimal Mention with string array:

cshtml

@{
    var users = new string[] { "Adeline MacAdams", "Alba Torres", "Amy Fernandez", "Andrew Jack" };
}

<div id="mentionTarget" contenteditable="true"
     style="min-height: 100px; border: 1px solid #ccc; padding: 10px;">
    Type @ to mention someone
</div>

<ejs-mention id="mentionElement" target="#mentionTarget" dataSource="@users">
</ejs-mention>

Mention with object data and field mapping:

cshtml

<div id="mentionTarget" contenteditable="true"
     style="min-height: 100px; border: 1px solid #ccc; padding: 10px;">
</div>

<ejs-mention id="mentionElement" target="#mentionTarget" dataSource="@ViewBag.data">
    <e-mention-fields text="Name" value="EmailId"></e-mention-fields>
</ejs-mention>

Controller:

csharp

public IActionResult Index()
{
    ViewBag.data = new List<EmailData>
    {
        new EmailData { Name = "Adeline MacAdams", EmailId = "adeline@example.com" },
        new EmailData { Name = "Alba Torres", EmailId = "alba@example.com" },
        new EmailData { Name = "Amy Fernandez", EmailId = "amy@example.com" }
    };
    return View();
}

public class EmailData
{
    public string Name { get; set; }
    public string EmailId { get; set; }
}

基础Mention（字符串数组）:

cshtml

@{
    var users = new string[] { "Adeline MacAdams", "Alba Torres", "Amy Fernandez", "Andrew Jack" };
}

<div id="mentionTarget" contenteditable="true"
     style="min-height: 100px; border: 1px solid #ccc; padding: 10px;">
    Type @ to mention someone
</div>

<ejs-mention id="mentionElement" target="#mentionTarget" dataSource="@users">
</ejs-mention>

带对象数据和字段映射的Mention:

cshtml

<div id="mentionTarget" contenteditable="true"
     style="min-height: 100px; border: 1px solid #ccc; padding: 10px;">
</div>

<ejs-mention id="mentionElement" target="#mentionTarget" dataSource="@ViewBag.data">
    <e-mention-fields text="Name" value="EmailId"></e-mention-fields>
</ejs-mention>

控制器:

csharp

public IActionResult Index()
{
    ViewBag.data = new List<EmailData>
    {
        new EmailData { Name = "Adeline MacAdams", EmailId = "adeline@example.com" },
        new EmailData { Name = "Alba Torres", EmailId = "alba@example.com" },
        new EmailData { Name = "Amy Fernandez", EmailId = "amy@example.com" }
    };
    return View();
}

public class EmailData
{
    public string Name { get; set; }
    public string EmailId { get; set; }
}

Common Patterns

常见模式

Custom Trigger Character (# for tags)

自定义触发字符（#用于标签）

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    mentionChar="#"
    showMentionChar="true">
    <e-mention-fields text="TagName"></e-mention-fields>
</ejs-mention>

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    mentionChar="#"
    showMentionChar="true">
    <e-mention-fields text="TagName"></e-mention-fields>
</ejs-mention>

Mention with Suffix Space + No Leading Space Required

带后缀空格且无需前置空格的Mention

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    suffixText=" "
    requireLeadingSpace="false">
    <e-mention-fields text="Name"></e-mention-fields>
</ejs-mention>

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    suffixText=" "
    requireLeadingSpace="false">
    <e-mention-fields text="Name"></e-mention-fields>
</ejs-mention>

Remote Data with Filtering

带过滤的远程数据

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    minLength="2"
    filterType="StartsWith"
    suggestionCount="10">
    <e-mention-fields text="ContactName" value="CustomerID"></e-mention-fields>
    <e-data-manager url="url"
        adaptor="ODataV4Adaptor" crossDomain="true">
    </e-data-manager>
</ejs-mention>

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    minLength="2"
    filterType="StartsWith"
    suggestionCount="10">
    <e-mention-fields text="ContactName" value="CustomerID"></e-mention-fields>
    <e-data-manager url="url"
        adaptor="ODataV4Adaptor" crossDomain="true">
    </e-data-manager>
</ejs-mention>

Custom Item Template

自定义项模板

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    itemTemplate="<span><img src='${EmpImage}' class='avatar'/><b>${FirstName}</b> - ${Department}</span>">
    <e-mention-fields text="FirstName" value="FirstName"></e-mention-fields>
</ejs-mention>

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    itemTemplate="<span><img src='${EmpImage}' class='avatar'/><b>${FirstName}</b> - ${Department}</span>">
    <e-mention-fields text="FirstName" value="FirstName"></e-mention-fields>
</ejs-mention>

Handle Selection Event

处理选择事件

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    select="onMentionSelect">
    <e-mention-fields text="Name" value="EmailId"></e-mention-fields>
</ejs-mention>

<script>
    function onMentionSelect(args) {
        console.log("Mentioned user:", args.itemData.Name);
        console.log("Email:", args.itemData.EmailId);
    }
</script>

cshtml

<ejs-mention id="mentionElement" target="#mentionTarget"
    dataSource="@ViewBag.data"
    select="onMentionSelect">
    <e-mention-fields text="Name" value="EmailId"></e-mention-fields>
</ejs-mention>

<script>
    function onMentionSelect(args) {
        console.log("Mentioned user:", args.itemData.Name);
        console.log("Email:", args.itemData.EmailId);
    }
</script>

Key Properties Quick Reference

核心属性快速参考

Property	Type	Default	Purpose
`target`	string	null	CSS selector for the editable target element (required)
`dataSource`	object	null	Local array or DataManager
`fields`	MentionFieldSettings	null	Map text, value, groupBy, iconCss, disabled
`mentionChar`	char	`'@'`	The character that triggers the suggestion popup
`showMentionChar`	bool	false	Show trigger character as prefix in inserted text
`suffixText`	string	null	Text appended after the inserted value (e.g., `" "` )
`requireLeadingSpace`	bool	true	Require a space before the trigger character
`filterType`	FilterType	Contains	Filter match strategy
`minLength`	int	0	Min chars before search activates
`suggestionCount`	int	25	Max items in suggestion list
`allowSpaces`	bool	false	Allow spaces in the search term
`sortOrder`	SortOrder	None	Sort suggestion list order
`popupHeight`	string	"300px"	Height of the suggestion popup
`popupWidth`	string	"auto"	Width of the suggestion popup
`highlight`	bool	false	Highlight matched characters in suggestions
`ignoreCase`	bool	true	Case-insensitive search
`debounceDelay`	double	300	Delay (ms) before filtering runs

属性	类型	默认值	用途
`target`	string	null	可编辑目标元素的CSS选择器（必填）
`dataSource`	object	null	本地数组或DataManager
`fields`	MentionFieldSettings	null	映射text、value、groupBy、iconCss、disabled
`mentionChar`	char	`'@'`	触发建议弹窗的字符
`showMentionChar`	bool	false	在插入文本中显示触发字符前缀
`suffixText`	string	null	插入值后追加的文本（例如： `" "` ）
`requireLeadingSpace`	bool	true	触发字符前需要空格
`filterType`	FilterType	Contains	过滤匹配策略
`minLength`	int	0	触发搜索的最小字符数
`suggestionCount`	int	25	建议列表中的最大项数
`allowSpaces`	bool	false	允许搜索词中包含空格
`sortOrder`	SortOrder	None	建议列表排序顺序
`popupHeight`	string	"300px"	建议弹窗高度
`popupWidth`	string	"auto"	建议弹窗宽度
`highlight`	bool	false	高亮建议中的匹配字符
`ignoreCase`	bool	true	不区分大小写搜索
`debounceDelay`	double	300	过滤执行前的延迟（毫秒）