syncfusion-winui-combobox

实现组合框（Syncfusion WinUI）

何时使用此技能

在用户需要执行以下操作时使用此技能：

• 在 WinUI 应用程序中实现下拉选择控件
• 启用从列表中单选或多选项目
• 为下拉列表添加筛选和搜索功能
• 创建支持自动完成的可编辑下拉列表
• 将所选项目显示为令牌或以分隔符分隔的值
• 按类别对下拉列表项目分组
• 使用模板自定义下拉列表外观
• 处理用户输入验证和无效条目
• 在下拉列表中实现键盘导航

组件概述

Syncfusion WinUI ComboBox（SfComboBox）是功能丰富的下拉选择控件，支持：

• 选择模式： 支持复选框的单选和多选
• 筛选： 内置 StartsWith 或 Contains 模式筛选
• 编辑： 可编辑和不可编辑模式，并支持自动完成
• 显示模式： 多选时以令牌或分隔符分隔的形式显示
• 搜索： 支持高亮显示的文本搜索
• 分组： 将项目归类
• 自定义： 丰富的模板和样式选项
• 键盘支持： 完整的键盘导航和快捷键
• 无障碍功能： 符合 WCAG 标准，并支持屏幕阅读器

⚠️ 安全注意事项

在 ComboBox 中使用外部数据源或自定义筛选时：

• 数据源安全： 仅将可信的内部数据源绑定到 ItemsSource。显示任何外部数据前都应进行验证。
• 图像绑定： 不要将 Image.Source 绑定到不可信的外部 URL。请改用嵌入式资源（ms-appx:///）或本地文件（file:///）。
• 自定义筛选： 如果使用外部 API 实现 IComboBoxFilterBehavior，务必将允许的域加入白名单，并清理响应内容。
• 用户输入： 在可编辑模式下，应验证并清理用户输入，尤其是在将其传递给后端服务时。

何时使用 ComboBox 与其他下拉控件：

• 使用 ComboBox 的情况： 需要筛选、编辑或带令牌的多选时
• 使用 DropDownList 的情况： 需要简单的单选且不可编辑时
• 使用 MultiSelect Dropdown 的情况： 需要不带令牌的多选（仅使用复选框）时
• 使用 AutoComplete 的情况： 需要输入时提供建议，但不需要保留下拉列表时

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装 NuGet 包（Syncfusion.Editors.WinUI）
• 安装 NuGet 包（Syncfusion.Editors.WinUI）
• 注意：发布前，请确保将 Syncfusion.Editors.WinUI NuGet 包更新到最新可用版本。
• 在 XAML 和 C# 中实现基本的 ComboBox
• 使用 SfComboBoxItem 填充项目
• 使用 ItemsSource 进行数据绑定
• 设置 DisplayMemberPath 和 TextMemberPath
• 自定义 SelectionBox UI

选择模式

📄 阅读： references/selection.md

• 单选（UI 和编程方式）
• SelectionChangeTrigger（Committed 与 Always）
• 使用复选框进行多选
• 多选的分隔符显示模式
• 带可移除令牌的令牌显示模式
• 隐藏或显示复选框
• 自动追加 UI 类型（TextWithSelection 与 Text）
• SelectionChanged 和 SelectionChanging 事件

筛选和搜索

📄 阅读： references/filtering.md

• 使用 IsFilteringEnabled 启用筛选
• 筛选模式（StartsWith、Contains）
• 配置 TextSearchMode
• 使用 IComboBoxFilterBehavior 进行自定义筛选
• 为自定义逻辑实现 GetMatchingIndexes
• 筛选示例和模式

📄 阅读： references/searching.md

• 文本搜索功能
• IsTextSearchEnabled 属性
• 自动完成行为
• 高亮显示搜索结果
• 搜索自定义选项

编辑模式

📄 阅读： references/editing.md

• 可编辑与不可编辑模式（IsEditable 属性）
• 自动补全和文本追加
• 使用 AllowNull 设置 null 值
• 通过代码打开下拉框（IsDropDownOpen）
• 使用 InputSubmitted 事件处理无效输入
• 输入验证模式

分组和组织

📄 阅读： references/grouping.md

• 按类别对项目分组
• GroupMemberPath 配置
• 自定义组标题
• 组模板和样式
• 在组内排序

UI 自定义

📄 阅读： references/ui-customization.md

• 下拉项目的 ItemTemplate
• 用于显示所选项目的 SelectionBoxItemTemplate
• 标题和页脚模板
• 设置 ComboBox 元素的样式
• 主题自定义
• 设置令牌模式下 ComboBoxTokenItem 的样式
• 自定义模板示例

键盘和高级功能

📄 阅读： references/keyboard-and-advanced.md

• 键盘导航快捷键
• 前置视图和后置视图
• 水印/占位文本（PlaceholderText）
• 无障碍功能
• 针对大型数据集的性能优化
• 常见问题排查

快速入门示例

基本单选 ComboBox

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <editors:SfComboBox x:Name="comboBox"
                        Width="250"
                        PlaceholderText="Select a social media"
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name" />
</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 = "Twitter", ID = 1 },
            new SocialMedia { Name = "Instagram", ID = 2 }
        };
    }
}

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

带筛选功能的可编辑 ComboBox

<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="StartsWith"
                    PlaceholderText="Type to filter..."
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

使用令牌的多选

<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    IsEditable="True"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

常见模式

模式 1：带自动补全的可编辑下拉框

用户输入时，自动筛选并推荐匹配的项目：

<editors:SfComboBox IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="StartsWith"
                    IsTextSearchEnabled="True"
                    ItemsSource="{Binding Cities}"
                    DisplayMemberPath="CityName"
                    TextMemberPath="CityName" />

关键配置：

• IsEditable="True"：启用文本输入
• IsFilteringEnabled="True"：在用户输入时筛选项目
• TextSearchMode="StartsWith"：筛选以输入文本开头的项目
• IsTextSearchEnabled="True"：将第一个匹配项自动追加到输入文本

模式 2：使用自定义分隔符的多选

使用自定义分隔符显示多个所选项目：

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Delimiter"
                    DelimiterText=" | "
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

// Access selected items
var selectedItems = comboBox.SelectedItems;
foreach (var item in selectedItems)
{
    // Process each selected item
}

模式 3：使用自定义令牌模板的令牌模式

将所选项目显示为可移除的令牌，并使用自定义样式：

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.TokenItemTemplate>
        <DataTemplate>
            <Grid Background="LightBlue" 
                  Padding="8,4"
                  CornerRadius="4">
                <TextBlock Text="{Binding Name}" 
                          Foreground="DarkBlue" />
            </Grid>
        </DataTemplate>
    </editors:SfComboBox.TokenItemTemplate>
</editors:SfComboBox>

模式 4：处理无效输入

验证并处理与任何项目都不匹配的用户输入：

<editors:SfComboBox x:Name="comboBox"
                    IsEditable="True"
                    InputSubmitted="OnInputSubmitted"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

private async void OnInputSubmitted(object sender, ComboBoxInputSubmittedEventArgs e)
{
    // Option 1: Show error message
    var dialog = new ContentDialog
    {
        Content = $"'{e.Text}' is not a valid option. Please select from the list.",
        CloseButtonText = "Close"
    };
    dialog.XamlRoot = this.Content.XamlRoot;
    await dialog.ShowAsync();
    
    // Option 2: Add new item dynamically (for multiple selection)
    // e.Item = new YourModel { Name = e.Text, ID = comboBox.Items.Count };
    
    // Option 3: Prevent selection
    // e.Handled = true;
}

模式 5：自定义筛选逻辑

针对复杂场景实现自定义筛选：

public class CustomFilterBehavior : IComboBoxFilterBehavior
{
    public List<int> GetMatchingIndexes(SfComboBox source, ComboBoxFilterInfo filterInfo)
    {
        var filteredList = new List<int>();
        var items = source.Items.OfType<YourModel>().ToList();
        
        // Custom filtering logic - search in multiple properties
        filteredList.AddRange(
            from item in items
            where item.Name.Contains(filterInfo.Text, StringComparison.OrdinalIgnoreCase) ||
                  item.Category.Contains(filterInfo.Text, StringComparison.OrdinalIgnoreCase)
            select items.IndexOf(item)
        );
        
        return filteredList;
    }
}

<editors:SfComboBox ItemsSource="{Binding Items}"
                    IsEditable="True"
                    IsFilteringEnabled="True"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.FilterBehavior>
        <local:CustomFilterBehavior />
    </editors:SfComboBox.FilterBehavior>
</editors:SfComboBox>

模式 6：通过代码管理选择

通过代码控制选择，以满足动态场景需求：

// Single selection
comboBox.SelectedIndex = 2;
comboBox.SelectedItem = specificItem;

// Multiple selection
comboBox.SelectedItems.Add(item1);
comboBox.SelectedItems.Add(item2);

// Clear selection
comboBox.SelectedItems.Clear();

// React to selection changes
comboBox.SelectionChanged += (sender, e) =>
{
    foreach (var added in e.AddedItems)
    {
        // Handle newly selected items
    }
    
    foreach (var removed in e.RemovedItems)
    {
        // Handle deselected items
    }
};

关键属性

数据绑定

• ItemsSource： 要显示的项目集合（IEnumerable）
• DisplayMemberPath： 下拉列表中显示的属性名称
• TextMemberPath： 选择框中显示的属性名称
• SelectedItem： 当前所选项目（单选）
• SelectedItems： 所选项目集合（多选）
• SelectedIndex： 所选项目的索引（单选）

选择配置

• SelectionMode： Single 或 Multiple 选择
• MultiSelectionDisplayMode： 多选时使用 Delimiter 或 Token
• DelimiterText： 分隔符模式下分隔项目的字符（默认值：","）
• IsMultiSelectCheckBoxEnabled： 显示/隐藏下拉框中的复选框（默认值：true）
• SelectionChangeTrigger： 更新选择的时机——Committed 或 Always

编辑和筛选

• IsEditable： 启用/禁用文本编辑（默认值：false）
• IsFilteringEnabled： 启用/禁用筛选（默认值：false）
• TextSearchMode： 筛选模式——StartsWith 或 Contains
• IsTextSearchEnabled： 启用/禁用自动补全（默认值：true）
• AllowNull： 文本清空时允许选择 null（默认值：false）

显示和 UI

• PlaceholderText： 无选择时显示的水印文本
• IsDropDownOpen： 以编程方式打开/关闭下拉列表
• SelectionBoxItemTemplate： 已选项的显示模板
• ItemTemplate： 下拉列表项的模板
• HeaderTemplate： 下拉列表标题的模板
• FooterTemplate： 下拉列表页脚的模板

分组

• GroupMemberPath： 用于对项目分组的属性名称

常见用例

用例 1：国家/州选择

两级级联下拉列表：

<editors:SfComboBox x:Name="countryComboBox"
                    PlaceholderText="Select Country"
                    ItemsSource="{Binding Countries}"
                    SelectionChanged="OnCountryChanged"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

<editors:SfComboBox x:Name="stateComboBox"
                    PlaceholderText="Select State"
                    ItemsSource="{Binding States}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

private void OnCountryChanged(object sender, ComboBoxSelectionChangedEventArgs e)
{
    if (e.AddedItems.Count > 0)
    {
        var country = e.AddedItems[0] as Country;
        // Update states collection based on selected country
        viewModel.LoadStates(country.ID);
    }
}

用例 2：博客文章的标签选择

使用令牌显示进行多选，以选择多个标签：

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    IsEditable="True"
                    PlaceholderText="Add tags..."
                    ItemsSource="{Binding AvailableTags}"
                    InputSubmitted="OnTagInputSubmitted"
                    DisplayMemberPath="TagName"
                    TextMemberPath="TagName" />

用例 3：可搜索的员工目录

带筛选功能的可编辑下拉列表，方便快速查找员工：

⚠️ 安全提示： 显示员工照片或外部图片时，请确保图片仅从可信的内部来源加载。未经验证，请勿绑定外部 URL。

<editors:SfComboBox IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="Contains"
                    PlaceholderText="Search employee..."
                    ItemsSource="{Binding Employees}"
                    DisplayMemberPath="FullName"
                    TextMemberPath="FullName">
    <editors:SfComboBox.ItemTemplate>
        <DataTemplate>
            <Grid>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto" />
                    <ColumnDefinition Width="*" />
                </Grid.ColumnDefinitions>
                
                <Ellipse Width="32" Height="32" Margin="8">
                    <Ellipse.Fill>
                        <ImageBrush ImageSource="{Binding PhotoUrl}" />
                    </Ellipse.Fill>
                </Ellipse>
                <StackPanel Grid.Column="1" VerticalAlignment="Center">
                    <TextBlock Text="{Binding FullName}" FontWeight="SemiBold" />
                    <TextBlock Text="{Binding Department}" 
                              FontSize="12" 
                              Foreground="Gray" />
                </StackPanel>
            </Grid>
        </DataTemplate>
    </editors:SfComboBox.ItemTemplate>
</editors:SfComboBox>

用例 4：包含分组选项的设置面板

对相关配置选项进行分组：

<editors:SfComboBox ItemsSource="{Binding Settings}"
                    GroupMemberPath="Category"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.GroupStyle>
        <GroupStyle>
            <GroupStyle.HeaderTemplate>
                <DataTemplate>
                    <TextBlock Text="{Binding Key}" 
                              FontWeight="Bold"
                              Foreground="DarkBlue"
                              Margin="8,4" />
                </DataTemplate>
            </GroupStyle.HeaderTemplate>
        </GroupStyle>
    </editors:SfComboBox.GroupStyle>
</editors:SfComboBox>

最佳实践

1. 绑定复杂对象时，始终设置 DisplayMemberPath 和 TextMemberPath
2. 设置 IsEditable="True" 和 IsFilteringEnabled="True"，以提升大列表的用户体验
3. 使用可编辑模式时，处理 InputSubmitted 事件，以验证用户输入
4. 选择合适的 TextSearchMode： 对可预测的列表使用 StartsWith，对灵活搜索使用 Contains
5. 空间允许时，多选请使用 Token 模式；需要紧凑显示时，使用 Delimiter 模式
6. 针对复杂筛选场景实现自定义 FilterBehavior（多个属性、模糊匹配）
7. 设置 PlaceholderText，引导用户选择内容
8. 实时更新时设置 SelectionChangeTrigger="Always"；为了提升性能，使用 Committed
9. 如果用例允许空值选择，请在可编辑模式下启用 AllowNull
10. 自定义 ItemTemplate，以通过图片、图标或多行文本丰富视觉呈现