syncfusion-winui-autocomplete

实现自动完成（SfAutoComplete）

Syncfusion WinUI AutoComplete（SfAutoComplete）是一款高度优化的控件，可在用户输入时从大型数据集中提供筛选后的建议。它支持单选和多选，并将所选项显示为包含图像、文本和关闭按钮的令牌，方便移除。

何时使用此技能

在用户需要以下功能时使用此技能：

• 在 WinUI 应用程序中实现自动完成搜索功能
• 创建可搜索的下拉列表，根据用户输入筛选建议
• 构建标签或令牌输入字段，支持多选
• 根据用户输入的字符筛选大型数据集
• 提供输入即搜索体验，并自动显示建议
• 实现多选下拉列表，以芯片/令牌形式显示选项
• 添加水印文本，引导用户在搜索字段中输入内容
• 自定义建议项的显示方式，包含图像和自定义模板
• **处理“未找到结果”**的情况，并提供自定义消息
• 在自动完成输入框中添加前置/后置图标或按钮

组件概览

包： Syncfusion.Editors.WinUI
命名空间： Syncfusion.UI.Xaml.Editors
控件： SfAutoComplete

主要功能：

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

文档与导航指南

入门

📄 阅读： references/getting-started.md

当用户需要：

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

选择

📄 阅读： references/selection.md

当用户需要：

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

搜索与筛选

📄 阅读： references/searching-filtering.md

当用户需要：

• 配置筛选行为（StartsWith 或 Contains）
• 实现自定义筛选逻辑
• 根据特定属性进行搜索
• 处理自动填充和自动建议
• 筛选后选择默认项

UI 自定义

📄 阅读： references/ui-customization.md

当用户需要：

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

高级功能

📄 阅读： references/advanced-features.md

当用户需要：

• 按类别对建议进行分组
• 高亮建议中的匹配文本
• 实现键盘快捷键
• 确保符合无障碍要求
• 处理高级用户交互

快速入门示例

基本单选自动完成

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

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

带令牌的多选

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

常见模式

模式 1：使用 Contains 筛选进行搜索

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

适用于用户需要按文本中的任意部分查找项，而不仅仅是按开头查找的场景。

模式 2：使用自定义显示方式的多选标签

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

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

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

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

用于为自动完成字段提供视觉提示（例如，搜索图标）。

模式 4：自定义“未找到结果”消息

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

用于在筛选没有匹配项时提供有用的反馈。

主要属性

属性	类型	描述
ItemsSource	object	要显示的数据项集合
DisplayMemberPath	string	下拉列表项的显示属性路径
TextMemberPath	string	选择框文本的属性路径
SelectionMode	AutoCompleteSelectionMode	Single 或 Multiple 选择模式
TextSearchMode	AutoCompleteTextSearchMode	使用 StartsWith 或 Contains 进行筛选
PlaceholderText	string	内容为空时显示的水印文本
SelectedItem	object	当前选中的项（单选模式）
SelectedItems	ObservableCollection	选中项集合（多选模式）
NoResultsFoundContent	object	未找到匹配项时显示的内容
LeadingView	object	显示在文本输入框之前的内容
TrailingView	object	显示在文本输入框之后的内容
GroupMemberPath	string	对项进行分组的属性路径
HighlightedTextColor	Brush	匹配文本的高亮颜色
FilterBehavior	AutoCompleteFilterBehavior	自定义筛选逻辑

常见用例

邮件收件人选择器

使用多选自动补全从联系人列表中选择邮件收件人，并将已选联系人显示为可移除的标记。

产品搜索

在电商应用中使用单选自动补全查找产品，并通过包含匹配进行筛选，实现灵活搜索。

分类标记

使用多选自动补全为项目分配多个类别或标记，并自定义标记的显示方式。

地点搜索

使用单选自动补全显示分组建议（国家 > 城市），并通过 StartsWith 筛选快速导航。

技能搜索

使用多选自动补全从预定义列表中选择用户技能，并在无法识别条目时显示“无结果”消息。

相关组件

• ComboBox - 用于不带自动补全筛选的简单下拉选择
• TextBox - 用于不带建议的基本文本输入（如有文档）

集成提示

与 MVVM 配合：

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

性能：

• 对大型数据集（>1000 项）使用虚拟化
• 对远程数据源考虑异步加载
• 对超大列表使用 TextSearchMode.StartsWith 以获得更好的性能

无障碍性：

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

故障排除快速修复

问题	解决方案
未显示建议	检查 ItemsSource 是否已绑定且包含数据；确认 DisplayMemberPath 设置正确
显示的文本不正确	将 TextMemberPath 设置为正确的属性名称
筛选不起作用	确保已设置 TextSearchMode；确认属性数据类型为字符串
多选不起作用	设置 SelectionMode="Multiple"
自定义模板未应用	检查 ItemTemplate 的 DataContext 绑定是否与数据模型匹配
未显示无结果消息	设置 NoResultsFoundContent 属性

---

**后续步骤：**如需了解详细实现，请使用上方的文档指南，导航到与需求相符的特定参考文件。