syncfusion-winui-autocomplete

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing AutoComplete (SfAutoComplete)

实现AutoComplete（SfAutoComplete）

The Syncfusion WinUI AutoComplete (

SfAutoComplete

) is a highly optimized control for providing filtered suggestions from large datasets as users type. It supports both single and multiple item selection, displaying selected items as tokens with images, text, and close buttons for easy removal.

Syncfusion WinUI AutoComplete（

SfAutoComplete

）是一款高度优化的控件，可在用户输入时从大型数据集中提供过滤后的建议。它支持单选和多选，选中的项会以带图片、文本和关闭按钮的令牌形式显示，方便移除。

When to Use This Skill

适用场景

Use this skill when the user needs to:

Implement autocomplete search functionality in WinUI applications
Create searchable dropdowns with filtered suggestions based on user input
Build tag or token input fields with multi-select capability
Filter large datasets based on characters entered by the user
Provide search-as-you-type experiences with auto-suggestions
Implement multi-select dropdowns with chip/token display
Add watermark text to guide user input in search fields
Customize suggestion item display with images and custom templates
Handle "no results found" scenarios with custom messaging
Add leading/trailing icons or buttons to autocomplete inputs

当用户需要以下功能时，可使用本技能：

在WinUI应用中实现自动完成搜索功能
创建可搜索下拉框，根据用户输入过滤建议
构建标签或令牌输入字段，支持多选
根据用户输入的字符过滤大型数据集
提供带自动建议的输入即搜体验
实现带芯片/令牌显示的多选下拉框
为搜索字段添加水印文本以引导用户输入
使用图片和自定义模板自定义建议项显示
处理“无结果”场景，显示自定义提示信息
为自动完成输入框添加前置/后置图标或按钮

Component Overview

组件概述

Package:

Syncfusion.Editors.WinUI

Namespace:

Syncfusion.UI.Xaml.Editors

Control:

SfAutoComplete

Key Capabilities:

Single and multiple selection modes
Real-time filtering (StartsWith or Contains)
Custom filtering logic support
Token/chip display for selected items
Highlighting of matched text
Grouping of suggestions
Leading and trailing views
Watermark/placeholder text
Keyboard navigation
Template customization

包：

Syncfusion.Editors.WinUI

命名空间：

Syncfusion.UI.Xaml.Editors

控件：

SfAutoComplete

核心功能：

单选和多选模式
实时过滤（StartsWith或Contains）
支持自定义过滤逻辑
选中项的令牌/芯片显示
匹配文本高亮
建议项分组
前置和后置视图
水印/占位符文本
键盘导航
模板自定义

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

When the user needs to:

Install the AutoComplete package
Create and configure the control
Set up data binding with ItemsSource
Configure TextMemberPath and DisplayMemberPath
Implement basic autocomplete functionality

📄 阅读： references/getting-started.md

当用户需要：

安装AutoComplete包
创建并配置控件
设置ItemsSource数据绑定
配置TextMemberPath和DisplayMemberPath
实现基础自动完成功能

Selection

选择功能

📄 Read: references/selection.md

When the user needs to:

Configure single vs multiple selection
Handle selected items programmatically
Display tokens/chips for multiple selections
Listen to selection change events
Work with SelectedItem or SelectedItems properties

📄 阅读： references/selection.md

当用户需要：

配置单选或多选模式
以编程方式处理选中项
为多选显示令牌/芯片
监听选择变更事件
使用SelectedItem或SelectedItems属性

Searching and Filtering

搜索与过滤

📄 Read: references/searching-filtering.md

When the user needs to:

Configure filtering behavior (StartsWith or Contains)
Implement custom filtering logic
Search based on specific properties
Handle auto-fill and auto-suggestions
Select default items after filtering

📄 阅读： references/searching-filtering.md

当用户需要：

配置过滤行为（StartsWith或Contains）
实现自定义过滤逻辑
基于特定属性搜索
处理自动填充和自动建议
过滤后选择默认项

UI Customization

UI自定义

📄 Read: references/ui-customization.md

When the user needs to:

Customize dropdown item templates
Add leading icons or buttons
Add trailing actions or clear buttons
Style selected item tokens
Handle "no results found" UI
Set watermark/placeholder text

📄 阅读： references/ui-customization.md

当用户需要：

自定义下拉项模板
添加前置图标或按钮
添加后置操作或清除按钮
设置选中项令牌样式
处理“无结果”UI
设置水印/占位符文本

Advanced Features

高级功能

📄 Read: references/advanced-features.md

When the user needs to:

Group suggestions by category
Highlight matched text in suggestions
Implement keyboard shortcuts
Ensure accessibility compliance
Handle advanced user interactions

📄 阅读： references/advanced-features.md

当用户需要：

按类别分组建议项
高亮建议项中的匹配文本
实现键盘快捷键
确保无障碍合规性
处理高级用户交互

Quick Start Example

快速入门示例

Basic Single-Selection AutoComplete

基础单选AutoComplete

xaml

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfAutoComplete x:Name="autoComplete"
                                Width="250"
                                PlaceholderText="Search social media..."
                                ItemsSource="{Binding SocialMedias}"
                                DisplayMemberPath="Name"
                                TextMemberPath="Name"
                                TextSearchMode="Contains" />
    </Grid>
</Window>

csharp

// Model
public class SocialMedia
{
    public string Name { get; set; }
    public int ID { get; set; }
}

// ViewModel
public class SocialMediaViewModel
{
    public ObservableCollection<SocialMedia> SocialMedias { get; set; }
    
    public SocialMediaViewModel()
    {
        SocialMedias = new ObservableCollection<SocialMedia>
        {
            new SocialMedia { Name = "Facebook", ID = 0 },
            new SocialMedia { Name = "Instagram", ID = 1 },
            new SocialMedia { Name = "Twitter", ID = 2 },
            new SocialMedia { Name = "LinkedIn", ID = 3 }
        };
    }
}

// Set DataContext
autoComplete.DataContext = new SocialMediaViewModel();

xaml

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfAutoComplete x:Name="autoComplete"
                                Width="250"
                                PlaceholderText="Search social media..."
                                ItemsSource="{Binding SocialMedias}"
                                DisplayMemberPath="Name"
                                TextMemberPath="Name"
                                TextSearchMode="Contains" />
    </Grid>
</Window>

csharp

// Model
public class SocialMedia
{
    public string Name { get; set; }
    public int ID { get; set; }
}

// ViewModel
public class SocialMediaViewModel
{
    public ObservableCollection<SocialMedia> SocialMedias { get; set; }
    
    public SocialMediaViewModel()
    {
        SocialMedias = new ObservableCollection<SocialMedia>
        {
            new SocialMedia { Name = "Facebook", ID = 0 },
            new SocialMedia { Name = "Instagram", ID = 1 },
            new SocialMedia { Name = "Twitter", ID = 2 },
            new SocialMedia { Name = "LinkedIn", ID = 3 }
        };
    }
}

// Set DataContext
autoComplete.DataContext = new SocialMediaViewModel();

Multi-Selection with Tokens

带令牌的多选功能

xaml

<editors:SfAutoComplete x:Name="autoComplete"
                        Width="300"
                        SelectionMode="Multiple"
                        PlaceholderText="Select multiple items..."
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains" />

xaml

<editors:SfAutoComplete x:Name="autoComplete"
                        Width="300"
                        SelectionMode="Multiple"
                        PlaceholderText="Select multiple items..."
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains" />

Common Patterns

常见模式

Pattern 1: Search with Contains Filter

模式1：包含式过滤搜索

xaml

<editors:SfAutoComplete ItemsSource="{Binding Countries}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains"
                        PlaceholderText="Type to search..." />

Use when users need to find items by any part of the text, not just the beginning.

xaml

<editors:SfAutoComplete ItemsSource="{Binding Countries}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains"
                        PlaceholderText="Type to search..." />

适用于用户需要通过文本任意部分查找项，而非仅开头的场景。

Pattern 2: Multi-Select Tags with Custom Display

模式2：带自定义显示的多选标签

xaml

<editors:SfAutoComplete SelectionMode="Multiple"
                        ItemsSource="{Binding Tags}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Padding="5">
                <TextBlock Text="{Binding Name}" 
                          FontWeight="SemiBold"/>
            </StackPanel>
        </DataTemplate>
    </editors:SfAutoComplete.ItemTemplate>
</editors:SfAutoComplete>

Use for tagging systems where users select multiple items displayed as tokens.

xaml

<editors:SfAutoComplete SelectionMode="Multiple"
                        ItemsSource="{Binding Tags}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Padding="5">
                <TextBlock Text="{Binding Name}" 
                          FontWeight="SemiBold"/>
            </StackPanel>
        </DataTemplate>
    </editors:SfAutoComplete.ItemTemplate>
</editors:SfAutoComplete>

适用于标签系统，用户选择的多个项会以令牌形式显示。

Pattern 3: Autocomplete with Leading Icon

模式3：带前置图标的自动完成

xaml

<editors:SfAutoComplete ItemsSource="{Binding Items}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.LeadingView>
        <Grid Padding="8">
            <Path Data="M15.5 14h-.79l-.28-.27C15.41..." 
                  Fill="{ThemeResource SystemAccentColor}"/>
        </Grid>
    </editors:SfAutoComplete.LeadingView>
</editors:SfAutoComplete>

Use to provide visual context (e.g., search icon) for the autocomplete field.

xaml

<editors:SfAutoComplete ItemsSource="{Binding Items}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.LeadingView>
        <Grid Padding="8">
            <Path Data="M15.5 14h-.79l-.28-.27C15.41..." 
                  Fill="{ThemeResource SystemAccentColor}"/>
        </Grid>
    </editors:SfAutoComplete.LeadingView>
</editors:SfAutoComplete>

用于为自动完成字段提供视觉上下文（如搜索图标）。

Pattern 4: Custom "No Results" Message

模式4：自定义“无结果”提示

xaml

<editors:SfAutoComplete ItemsSource="{Binding Products}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        NoResultsFoundContent="No products found. Try a different search." />

Use to provide helpful feedback when filtering returns no matches.

xaml

<editors:SfAutoComplete ItemsSource="{Binding Products}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        NoResultsFoundContent="No products found. Try a different search." />

用于在过滤无匹配结果时提供有用的反馈。

Key Properties

核心属性

Property	Type	Description
`ItemsSource`	`object`	Collection of data items to display
`DisplayMemberPath`	`string`	Property path for dropdown item display
`TextMemberPath`	`string`	Property path for selection box text
`SelectionMode`	`AutoCompleteSelectionMode`	`Single` or `Multiple` selection
`TextSearchMode`	`AutoCompleteTextSearchMode`	`StartsWith` or `Contains` filtering
`PlaceholderText`	`string`	Watermark text when empty
`SelectedItem`	`object`	Currently selected item (single mode)
`SelectedItems`	`ObservableCollection`	Selected items collection (multiple mode)
`NoResultsFoundContent`	`object`	Content when no matches found
`LeadingView`	`object`	Content displayed before text input
`TrailingView`	`object`	Content displayed after text input
`GroupMemberPath`	`string`	Property path for grouping items
`HighlightedTextColor`	`Brush`	Color for highlighting matched text
`FilterBehavior`	`AutoCompleteFilterBehavior`	Custom filtering logic

属性	类型	说明
`ItemsSource`	`object`	要显示的数据项集合
`DisplayMemberPath`	`string`	下拉项显示的属性路径
`TextMemberPath`	`string`	选择框文本的属性路径
`SelectionMode`	`AutoCompleteSelectionMode`	单选或多选模式
`TextSearchMode`	`AutoCompleteTextSearchMode`	过滤方式（StartsWith或Contains）
`PlaceholderText`	`string`	为空时的水印文本
`SelectedItem`	`object`	当前选中项（单选模式）
`SelectedItems`	`ObservableCollection`	选中项集合（多选模式）
`NoResultsFoundContent`	`object`	无匹配结果时显示的内容
`LeadingView`	`object`	文本输入前显示的内容
`TrailingView`	`object`	文本输入后显示的内容
`GroupMemberPath`	`string`	项分组的属性路径
`HighlightedTextColor`	`Brush`	匹配文本的高亮颜色
`FilterBehavior`	`AutoCompleteFilterBehavior`	自定义过滤逻辑

Common Use Cases

常见使用场景

Email Recipient Selector

邮件收件人选择器

Multi-select autocomplete for selecting email recipients from a contact list, displaying selected contacts as removable tokens.

多选自动完成，用于从联系人列表中选择邮件收件人，选中的联系人以可移除令牌显示。

Product Search

产品搜索

Single-select autocomplete for finding products in an e-commerce app, with contains-based filtering for flexible searching.

单选自动完成，用于在电商应用中查找产品，使用包含式过滤实现灵活搜索。

Category Tagging

类别标签

Multi-select autocomplete for assigning multiple categories or tags to items, with custom token display.

多选自动完成，用于为项分配多个类别或标签，支持自定义令牌显示。

Location Search

位置搜索

Single-select autocomplete with grouped suggestions (Countries > Cities), using StartsWith filtering for quick navigation.

单选自动完成，带分组建议（国家>城市），使用StartsWith过滤实现快速导航。

Skill Search

技能搜索

Multi-select autocomplete for selecting user skills from a predefined list, with "no results" message for unrecognized entries.

多选自动完成，用于从预定义列表中选择用户技能，对未识别条目显示“无结果”提示。

Related Components

Integration Tips

集成技巧

With MVVM:

Bind
```
ItemsSource
```
to ViewModel's
```
ObservableCollection
```
Use
```
SelectedItem
```
or
```
SelectedItems
```
with two-way binding
Handle selection changes in ViewModel via binding commands

Performance:

Use virtualization for large datasets (>1000 items)
Consider async loading for remote data sources
Use
```
TextSearchMode.StartsWith
```
for better performance with very large lists

Accessibility:

Always set
```
PlaceholderText
```
to guide users
Use
```
AutomationProperties.Name
```
for screen readers
Ensure keyboard navigation works (Tab, Enter, Esc)
Test with high contrast themes

与MVVM集成：

将
```
ItemsSource
```
绑定到ViewModel的
```
ObservableCollection
```
使用双向绑定的
```
SelectedItem
```
或
```
SelectedItems
```
通过绑定命令在ViewModel中处理选择变更

性能优化：

大型数据集（>1000项）使用虚拟化
远程数据源考虑异步加载
超大型列表使用
```
TextSearchMode.StartsWith
```
以提升性能

无障碍支持：

始终设置
```
PlaceholderText
```
引导用户
为屏幕阅读器设置
```
AutomationProperties.Name
```
确保键盘导航正常工作（Tab、Enter、Esc）
测试高对比度主题

Troubleshooting Quick Fixes

故障排除快速修复

Issue	Solution
Suggestions not showing	Check `ItemsSource` is bound and contains data; verify `DisplayMemberPath`
Wrong text displayed	Set `TextMemberPath` to the correct property name
Filtering not working	Ensure `TextSearchMode` is set; verify property data types are strings
Multiple selection not working	Set `SelectionMode="Multiple"`
Custom template not applied	Check `ItemTemplate` DataContext binding matches data model
No results message not showing	Set `NoResultsFoundContent` property

Next Steps: For detailed implementation, navigate to the specific reference file matching your needs using the documentation guide above.

问题	解决方案
建议项不显示	检查 `ItemsSource` 是否已绑定且包含数据；验证 `DisplayMemberPath`
显示文本错误	将 `TextMemberPath` 设置为正确的属性名称
过滤不生效	确保已设置 `TextSearchMode` ；验证属性数据类型为字符串
多选不生效	设置 `SelectionMode="Multiple"`
自定义模板未应用	检查 `ItemTemplate` 的DataContext绑定是否匹配数据模型
无结果提示不显示	设置 `NoResultsFoundContent` 属性

下一步： 如需详细实现，请根据上述文档指南，导航至符合需求的具体参考文件。

syncfusion-winui-autocomplete

Original

Translation

Implementing AutoComplete (SfAutoComplete)

实现AutoComplete（SfAutoComplete）

When to Use This Skill

适用场景

Component Overview

组件概述

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

Selection

选择功能

Searching and Filtering

搜索与过滤

UI Customization

UI自定义

Advanced Features

高级功能

Quick Start Example

快速入门示例

Basic Single-Selection AutoComplete

基础单选AutoComplete

Multi-Selection with Tokens

带令牌的多选功能

Common Patterns

常见模式

Pattern 1: Search with Contains Filter

模式1：包含式过滤搜索

Pattern 2: Multi-Select Tags with Custom Display

模式2：带自定义显示的多选标签

Pattern 3: Autocomplete with Leading Icon

模式3：带前置图标的自动完成

Pattern 4: Custom "No Results" Message

模式4：自定义“无结果”提示

Key Properties

核心属性

Common Use Cases

常见使用场景

Email Recipient Selector

邮件收件人选择器

Product Search

产品搜索

Category Tagging

类别标签

Location Search

位置搜索

Skill Search

技能搜索

Related Components

相关组件

Integration Tips

集成技巧

Troubleshooting Quick Fixes

故障排除快速修复