syncfusion-wpf-autocomplete

实现 WPF 自动完成（SfTextBoxExt）

本指南全面介绍如何实现 Syncfusion WPF 自动完成控件（SfTextBoxExt），提供智能文本建议、高级筛选、多选功能和丰富的自定义选项，从而改善用户输入体验。

何时使用此技能

在以下情况使用此技能：

• 实现自动完成文本框，提供预测文本建议
• 添加搜索功能，提供经过筛选的下拉建议
• 启用多选，支持令牌或分隔符模式
• 创建输入即搜索的输入框，提供智能筛选
• 构建可搜索的下拉列表，支持自定义数据源
• 实现标签／令牌选择 UI，用于选择多个项目
• 为文本输入控件添加建议框
• 配置高级筛选，支持 18 种以上筛选模式
• 自定义文本输入外观，支持水印和模板
• 处理选择事件并获取所选值
• 支持不区分变音符号的搜索，适用于国际文本
• 突出显示建议列表中的匹配文本

本技能全面介绍 SfTextBoxExt 控件，并详细讲解所有功能的实现方法，包括数据绑定、筛选策略、选择处理、下拉列表自定义和高级功能。

组件概览

SfTextBoxExt 是一种增强型 TextBox 控件，在标准 WPF TextBox 功能的基础上扩展了自动完成功能。它可根据用户输入提供智能建议，支持多种筛选模式，并支持单选和多选场景。

主要功能

核心功能：

• 18 种以上筛选模式：StartsWith、EndsWith、Contains、Equals、Custom 等
• 多种自动完成模式：Suggest、Append、SuggestAppend
• 支持多选：令牌和分隔符模式
• 丰富的数据绑定：支持简单和复杂的数据类型
• 自定义模板：自动完成项、水印和无结果模板
• 事件驱动：选择、弹出窗口和建议变更事件

高级功能：

• 变音符号敏感度：跨语言搜索，支持不区分重音符号的筛选
• 文本突出显示：直观显示匹配的文本
• 自定义筛选：实现多路径或复杂筛选逻辑
• 弹出窗口配置：位置、延迟、高度和行为设置
• 性能优化：最少前缀字符数和最大建议数

UI 自定义：

• 水印支持：占位文本和自定义模板
• 视觉样式：字体、颜色和背景自定义
• 令牌外观：支持图像的自定义令牌模板
• 下拉列表样式：背景、选中颜色和项目模板
• 按钮控件：可选的下拉和清除按钮

文档和导航指南

本技能采用渐进式披露模式。请先阅读 SKILL.md，了解概览和导航信息，然后根据实现需求阅读相应的参考文件。

入门

📄 阅读： references/getting-started.md

何时阅读： 首次设置 SfTextBoxExt 或进行初始实现时

内容包括：

• 程序集部署和 NuGet 包安装
• 使用 SfTextBoxExt 创建 WPF 应用程序
• 通过设计器、XAML 和 C# 添加控件
• 使用数据源填充自动完成列表
• 数据模型和 ViewModel 设置
• 自动完成模式（Suggest、Append、SuggestAppend、None）
• 基本选择配置
• 主题支持和样式

自动完成与筛选

📄 阅读： references/autocomplete-filtering.md

阅读时机： 实现筛选逻辑、自定义建议行为时

内容包括：

• AutoCompleteSource 属性和数据绑定
• 使用 SearchItemPath 处理自定义数据对象
• 使用 AutoCompleteItemTemplate 自定义外观
• SuggestionMode 选项（18 种以上筛选模式，包括 StartsWith、EndsWith、Contains、Equals、Custom）
• MinimumPrefixCharacters 配置
• 使用 IgnoreCase 进行不区分大小写的筛选
• 使用 ImageMemberPath 显示图片
• 使用 MaximumSuggestionsCount 限制结果数量
• NoResultsFoundTemplate 自定义
• 用于手动筛选的 FilterSuggestions 方法
• SuggestionsChanged 事件处理

选择与值获取

📄 阅读： references/selection.md

阅读时机： 实现单选或多选、获取选中值时

内容包括：

• MultiSelectMode 选项（None、Token、Delimiter）
• 用于单选的 SelectedItem 属性
• 用于多选的 SelectedItems 集合
• 令牌的表示和布局
• TokensWrapMode（Wrap、None）配置
• 使用 EnableAutoSize 动态调整高度
• 使用自定义分隔符的 Delimiter 模式
• Delimiter 属性配置
• SelectedValue 和 ValueMemberPath
• 用于选中项索引的 SuggestionIndex
• 使用 ImageMemberPath 设置令牌图片
• SelectedItemChanged 事件处理

下拉框自定义

📄 阅读： references/dropdown-customization.md

阅读时机： 自定义建议弹出框的外观和行为时

内容包括：

• 使用 DropDownBackground 设置建议框样式
• SuggestionBoxPlacement 选项（Bottom、Top、None）
• MaximumDropDownHeight 配置
• ShowSuggestionsOnFocus 行为
• 使用 PopupDelay 延迟显示
• 使用 SelectionBackgroundColor 设置选中项颜色
• AutoHighlightMatchedItem API
• SuggestionPopupOpened 事件
• SuggestionPopupClosed 事件
• 完整的下拉框样式示例

文本框自定义

📄 阅读： references/textbox-customization.md

阅读时机： 自定义文本框外观、添加水印或按钮时

内容包括：

• 使用 Watermark 属性设置占位文本
• 使用 WatermarkTemplate 自定义占位内容的 UI
• 文本样式（FontSize、FontWeight、FontFamily）
• 使用 ShowDropDownButton 显示下拉图标
• 使用 ShowClearButton 实现清除功能
• 外观自定义模式
• 模板自定义示例

高级功能

📄 阅读： references/advanced-features.md

阅读时机： 实现变音符号搜索、文本高亮、自定义筛选器时

内容包括：

• 使用 IgnoreDiacritic 设置变音符号敏感度
• TextHighlightMode（FirstOccurrence、MultiOccurrence）
• HighlightedTextColor 配置
• HighlightedTextStyle 自定义
• 多路径搜索实现
• 自定义 SuggestionMode 设置
• 用于自定义筛选逻辑的 Filter 属性
• 自定义筛选器实现示例
• 用于资源清理的 Dispose 方法
• 性能优化提示

快速入门示例

带建议项的基本自动完成

<Window xmlns:editors="http://schemas.syncfusion.com/wpf">
    <Window.DataContext>
        <local:EmployeeViewModel/>
    </Window.DataContext>
    
    <editors:SfTextBoxExt 
        Width="300"
        Height="40"
        Watermark="Search employees..."
        SearchItemPath="Name"
        AutoCompleteMode="Suggest"
        SuggestionMode="Contains"
        AutoCompleteSource="{Binding Employees}" />
</Window>

// ViewModel
public class EmployeeViewModel
{
    public List<Employee> Employees { get; set; }
    
    public EmployeeViewModel()
    {
        Employees = new List<Employee>
        {
            new Employee { Name = "John Doe", Email = "[email protected]" },
            new Employee { Name = "Jane Smith", Email = "[email protected]" },
            new Employee { Name = "Mike Johnson", Email = "[email protected]" }
        };
    }
}

// Model
public class Employee
{
    public string Name { get; set; }
    public string Email { get; set; }
}

使用令牌进行多选

<editors:SfTextBoxExt 
    Width="400"
    Height="60"
    Watermark="Select multiple items..."
    SearchItemPath="Name"
    AutoCompleteMode="Suggest"
    MultiSelectMode="Token"
    TokensWrapMode="Wrap"
    EnableAutoSize="True"
    AutoCompleteSource="{Binding Items}" />

// Code-behind
var textBoxExt = new SfTextBoxExt
{
    Width = 400,
    Watermark = "Select multiple items...",
    SearchItemPath = "Name",
    AutoCompleteMode = AutoCompleteMode.Suggest,
    MultiSelectMode = MultiSelectMode.Token,
    TokensWrapMode = TokensWrapMode.Wrap,
    EnableAutoSize = true,
    AutoCompleteSource = viewModel.Items
};

常见模式

模式 1：支持不区分大小写搜索的基本自动完成

var autoComplete = new SfTextBoxExt
{
    AutoCompleteMode = AutoCompleteMode.Suggest,
    SuggestionMode = SuggestionMode.Contains,
    IgnoreCase = true,
    MinimumPrefixCharacters = 2,
    AutoCompleteSource = GetDataSource()
};

模式 2：带事件处理的多选

<editors:SfTextBoxExt 
    SearchItemPath="Name"
    AutoCompleteMode="Suggest"
    MultiSelectMode="Token"
    SelectedItemChanged="OnSelectedItemChanged"
    AutoCompleteSource="{Binding Items}" />

private void OnSelectedItemChanged(object sender, SelectedItemChangedEventArgs e)
{
    var selectedItems = (sender as SfTextBoxExt)?.SelectedItems;
    // Handle selected items
    foreach (var item in selectedItems)
    {
        Console.WriteLine(item.ToString());
    }
}

模式 3：自定义筛选

var autoComplete = new SfTextBoxExt
{
    SuggestionMode = SuggestionMode.Custom,
    AutoCompleteSource = employees
};

// Custom filter for multi-field search
autoComplete.Filter = (search, item) =>
{
    if (item is Employee emp)
    {
        return emp.Name.Contains(search, StringComparison.OrdinalIgnoreCase) ||
               emp.Email.Contains(search, StringComparison.OrdinalIgnoreCase) ||
               emp.Department.Contains(search, StringComparison.OrdinalIgnoreCase);
    }
    return false;
};

模式 4：弹出框配置

<editors:SfTextBoxExt 
    AutoCompleteMode="Suggest"
    ShowSuggestionsOnFocus="True"
    PopupDelay="00:00:00.3"
    MaxDropDownHeight="200"
    SuggestionBoxPlacement="Bottom"
    AutoHighlightMatchedItem="True"
    AutoCompleteSource="{Binding Data}" />

关键属性参考

核心属性

属性	类型	描述
AutoCompleteSource	IEnumerable	建议的数据源
SearchItemPath	string	用于筛选自定义对象的属性路径
AutoCompleteMode	AutoCompleteMode	建议显示模式（Suggest、Append、SuggestAppend、None）
SuggestionMode	SuggestionMode	筛选策略（StartsWith、Contains、Equals 等）
MultiSelectMode	MultiSelectMode	选择模式（None、Token、Delimiter）
SelectedItem	object	当前选中的项（单选）
SelectedItems	ObservableCollection<object>	选中的项（多选）
SelectedValue	object	所选项的值

配置属性

属性	类型	默认值	描述
MinimumPrefixCharacters	int	1	开始筛选前的最少字符数
IgnoreCase	bool	false	忽略大小写进行筛选
MaximumSuggestionsCount	int	0（不限）	显示的建议数量上限
ShowSuggestionsOnFocus	bool	false	聚焦时显示所有建议
PopupDelay	TimeSpan	00:00:00	弹出窗口打开前的延迟
MaxDropDownHeight	double	Auto	弹出窗口的最大高度

自定义属性

属性	类型	描述
Watermark	string	占位文本
WatermarkTemplate	DataTemplate	自定义占位模板
AutoCompleteItemTemplate	DataTemplate	自定义建议项模板
NoResultsFoundTemplate	DataTemplate	未找到匹配项时使用的模板
ShowDropDownButton	bool	显示下拉按钮
ShowClearButton	bool	显示清除按钮

事件

事件	描述
SelectedItemChanged	所选项更改时触发
SuggestionsChanged	筛选后的建议更新时触发
SuggestionPopupOpened	弹出窗口打开时触发
SuggestionPopupClosed	弹出窗口关闭时触发

常见用例

1. 员工搜索与选择

实现自动完成，按姓名、电子邮件或部门搜索员工，并支持多字段筛选。

2. 标签选择

启用 Token 模式进行多选，以选择标签、类别或标记，并以可视化令牌形式展示。

3. 产品搜索

创建可搜索的产品下拉列表，支持图片、自定义模板和丰富的项目信息展示。

4. 电子邮件收件人（To/CC/BCC）

构建电子邮件收件人选择功能，支持 Token 模式、分隔符和联系人建议。

5. 位置搜索

实现位置自动完成，提供地址建议，并支持针对国际地址的忽略变音符号搜索。

6. 代码编辑器自动完成

创建代码建议下拉列表，支持语法高亮、自定义筛选和键盘导航。

7. 表单自动填充

根据历史数据或预定义选项，为表单输入添加智能建议。

8. 多语言搜索

实现支持变音符号敏感性的搜索，以匹配国际内容，并支持忽略重音符号进行匹配。

相关资源

• Syncfusion 文档： https://help.syncfusion.com/wpf/autocomplete/overview
• API 参考： https://help.syncfusion.com/cr/wpf/Syncfusion.Windows.Controls.Input.SfTextBoxExt.html
• 示例浏览器： 可通过 Syncfusion Control Panel 使用
• GitHub 示例： https://github.com/SyncfusionExamples/wpf-textboxext-examples

支持与许可

SfTextBoxExt 是 Syncfusion Essential Studio for WPF 的一部分，属于需要有效许可证的商业产品。有关许可信息，请访问 https://www.syncfusion.com/sales/products。

---

后续步骤： 根据实现需求，转到相应的参考文件。初次设置请从 getting-started.md 开始，或直接查看特定功能指南，了解高级用例。