syncfusion-winforms-multiselect-combobox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing MultiSelectionComboBox

实现MultiSelectionComboBox

The MultiSelectionComboBox is a WinForms ComboBox control that supports multiple item selection and auto-suggestion. Selected items can be displayed as removable tag chips (VisualItem mode), comma-separated text (Delimiter mode), or single-value (Normal mode). It supports data binding via

DataSource

DisplayMember

ValueMember

, Office-style visual themes, grouping, and a rich event model.

MultiSelectionComboBox 是一款 WinForms ComboBox 控件，支持多选项选择和自动建议。选中项可以展示为可移除的标签芯片（VisualItem 模式）、逗号分隔文本（Delimiter 模式）或单值（Normal 模式）。它支持通过

DataSource

DisplayMember

ValueMember

进行数据绑定、Office 风格可视化主题、分组以及丰富的事件模型。

When to Use This Skill

何时使用本指南

Adding a multi-select dropdown to a Windows Forms application
Displaying selected values as tag chips with close buttons
Binding the combo box to a
```
DataTable
```
,
```
DataView
```
, or
```
ArrayList
```
Configuring auto-suggestion behavior (
```
AutoSuggestMode
```
)
Grouping dropdown items by initial character
Styling the drop-down list or visual item tags
Handling selection change and visual item collection events

在 Windows Forms 应用中添加多选下拉框
将选中值展示为带关闭按钮的标签芯片
将组合框绑定到
```
DataTable
```
、
```
DataView
```
或
```
ArrayList
```
配置自动建议行为（
```
AutoSuggestMode
```
）
按首字母对下拉项进行分组
自定义下拉列表或可视化项标签的样式
处理选择变更和可视化项集合事件

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly references and NuGet package setup
Adding the control via Designer or code-behind
Namespace imports (C# and VB.NET)
Basic instantiation with
```
ButtonStyle
```
,
```
UseVisualStyle
```
, and
```
Size
```
Minimal working example

📄 阅读： references/getting-started.md

程序集引用和 NuGet 包设置
通过设计器或代码后置添加控件
命名空间导入（C# 和 VB.NET）
使用
```
ButtonStyle
```
、
```
UseVisualStyle
```
和
```
Size
```
进行基础实例化
最小可用示例

Display Modes & Visual Item Input

显示模式与可视化项输入

📄 Read: references/display-modes-and-visual-items.md

```
DisplayMode.VisualItem
```
— tag chips with remove buttons
```
DisplayMode.DelimiterMode
```
— comma-separated text
```
DisplayMode.NormalMode
```
— single-value selection
```
AutoSizeMode
```
: Vertical, Horizontal, None
```
VisualItemInputMode
```
: DisplayMemberMode, ValueMemberMode, VisualItemMode
Delimiter character customization

📄 阅读： references/display-modes-and-visual-items.md

```
DisplayMode.VisualItem
```
—— 带移除按钮的标签芯片
```
DisplayMode.DelimiterMode
```
—— 逗号分隔文本
```
DisplayMode.NormalMode
```
—— 单值选择
```
AutoSizeMode
```
：垂直、水平、无
```
VisualItemInputMode
```
：DisplayMemberMode、ValueMemberMode、VisualItemMode
分隔符自定义

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding to
```
ArrayList
```
,
```
DataView
```
, and
```
DataTable
```
```
DataSource
```
,
```
DisplayMember
```
,
```
ValueMember
```
properties
Complete external data source binding example
```
DataSourceChanged
```
event handling

📄 阅读： references/data-binding.md

绑定到
```
ArrayList
```
、
```
DataView
```
和
```
DataTable
```
```
DataSource
```
、
```
DisplayMember
```
、
```
ValueMember
```
属性
完整外部数据源绑定示例
```
DataSourceChanged
```
事件处理

Styling & Customization

样式与自定义

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

Visual styles: Default, Office2016Colorful, Office2016White, Office2016Black, Office2016DarkGray
Drop-down styling:
```
ShowCheckBox
```
, group header colors, item/drop-down dimensions
Visual item tag colors: BackColor, ForeColor, SelectionColor, BorderColor
Grouping:
```
ShowGroups
```
, runtime enable/disable
Auto-suggestion modes:
```
Begin
```
,
```
Match
```
,
```
Disabled
```

📄 阅读： references/styling-and-customization.md

可视化样式：Default、Office2016Colorful、Office2016White、Office2016Black、Office2016DarkGray
下拉框样式：
```
ShowCheckBox
```
、分组头部颜色、项/下拉框尺寸
可视化项标签颜色：BackColor、ForeColor、SelectionColor、BorderColor
分组：
```
ShowGroups
```
、运行时启用/禁用
自动建议模式：
```
Begin
```
、
```
Match
```
、
```
Disabled
```

Events & Advanced Features

事件与高级特性

📄 Read: references/events-and-advanced-features.md

```
SelectedItemCollectionChanged
```
— when the selected items change
```
VisualItemCollectionChanged
```
— when visual item tags are added/removed

AutoSizeModeChanged

DataSourceChanged

DropDown

events

Detecting VisualItemCollection modifications at runtime

📄 阅读： references/events-and-advanced-features.md

```
SelectedItemCollectionChanged
```
—— 选中项发生变更时触发
```
VisualItemCollectionChanged
```
—— 可视化项标签被添加/移除时触发

AutoSizeModeChanged

、

DataSourceChanged

、

DropDown

事件

运行时检测 VisualItemCollection 变更

Quick Start

快速开始

csharp

using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Windows.Forms;

// Create and configure the control
var combo = new MultiSelectionComboBox();
combo.ButtonStyle = ButtonAppearance.Metro;
combo.UseVisualStyle = true;
combo.Size = new System.Drawing.Size(250, 30);
combo.DisplayMode = DisplayMode.VisualItem;

// Add items manually
combo.Items.AddRange(new object[] { "Apple", "Banana", "Cherry", "Date", "Elderberry" });

this.Controls.Add(combo);

Imports Syncfusion.Windows.Forms.Tools
Imports Syncfusion.Windows.Forms

Dim combo As New MultiSelectionComboBox()
combo.ButtonStyle = ButtonAppearance.Metro
combo.UseVisualStyle = True
combo.Size = New System.Drawing.Size(250, 30)
combo.DisplayMode = DisplayMode.VisualItem
combo.Items.AddRange(New Object() {"Apple", "Banana", "Cherry"})
Me.Controls.Add(combo)

csharp

using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Windows.Forms;

// Create and configure the control
var combo = new MultiSelectionComboBox();
combo.ButtonStyle = ButtonAppearance.Metro;
combo.UseVisualStyle = true;
combo.Size = new System.Drawing.Size(250, 30);
combo.DisplayMode = DisplayMode.VisualItem;

// Add items manually
combo.Items.AddRange(new object[] { "Apple", "Banana", "Cherry", "Date", "Elderberry" });

this.Controls.Add(combo);

Imports Syncfusion.Windows.Forms.Tools
Imports Syncfusion.Windows.Forms

Dim combo As New MultiSelectionComboBox()
combo.ButtonStyle = ButtonAppearance.Metro
combo.UseVisualStyle = True
combo.Size = New System.Drawing.Size(250, 30)
combo.DisplayMode = DisplayMode.VisualItem
combo.Items.AddRange(New Object() {"Apple", "Banana", "Cherry"})
Me.Controls.Add(combo)

Common Patterns

常用场景

Bind to a DataTable and display as tag chips

绑定到 DataTable 并展示为标签芯片

csharp

DataTable dt = new DataTable();
dt.Columns.Add("ID");
dt.Columns.Add("Name");
dt.Rows.Add("1", "Alice");
dt.Rows.Add("2", "Bob");
dt.Rows.Add("3", "Carol");

combo.DataSource = dt;
combo.DisplayMember = "Name";
combo.ValueMember = "ID";
combo.DisplayMode = DisplayMode.VisualItem;

csharp

DataTable dt = new DataTable();
dt.Columns.Add("ID");
dt.Columns.Add("Name");
dt.Rows.Add("1", "Alice");
dt.Rows.Add("2", "Bob");
dt.Rows.Add("3", "Carol");

combo.DataSource = dt;
combo.DisplayMember = "Name";
combo.ValueMember = "ID";
combo.DisplayMode = DisplayMode.VisualItem;

React to selection changes

响应选择变更事件

csharp

combo.SelectedItemCollectionChanged += (sender, e) =>
{
    if (e.Action == Actions.Added)
        Console.WriteLine("Added: " + e.SelectedItems[0]);
    else
        Console.WriteLine("Removed: " + e.SelectedItems[0]);
};

csharp

combo.SelectedItemCollectionChanged += (sender, e) =>
{
    if (e.Action == Actions.Added)
        Console.WriteLine("Added: " + e.SelectedItems[0]);
    else
        Console.WriteLine("Removed: " + e.SelectedItems[0]);
};

Apply Office 2016 Colorful theme

应用 Office 2016 多彩主题

csharp

combo.Style = MultiSelectionComboBoxStyle.Office2016Colorful;

csharp

combo.Style = MultiSelectionComboBoxStyle.Office2016Colorful;

Key Properties

核心属性

Property	Purpose
`DisplayMode`	VisualItem / DelimiterMode / NormalMode
`AutoSuggestMode`	Begin / Match / Disabled
`AutoSizeMode`	Vertical / Horizontal / None
`ShowCheckBox`	Show checkboxes in the dropdown
`ShowGroups`	Group items by initial character
`DelimiterChar`	Separator character (Delimiter mode)
`DataSource`	Bind to ArrayList, DataView, DataTable
`DisplayMember`	Property name shown in the control
`ValueMember`	Property used as the actual value
`Style`	Visual theme (Office2016Colorful, etc.)
`VisualItemInputMode`	DisplayMemberMode / ValueMemberMode / VisualItemMode

属性	用途
`DisplayMode`	VisualItem / DelimiterMode / NormalMode
`AutoSuggestMode`	Begin / Match / Disabled
`AutoSizeMode`	Vertical / Horizontal / None
`ShowCheckBox`	在下拉框中显示复选框
`ShowGroups`	按首字母对项进行分组
`DelimiterChar`	分隔符（Delimiter 模式下）
`DataSource`	绑定到 ArrayList、DataView、DataTable
`DisplayMember`	控件中展示的属性名
`ValueMember`	作为实际值使用的属性
`Style`	可视化主题（Office2016Colorful 等）
`VisualItemInputMode`	DisplayMemberMode / ValueMemberMode / VisualItemMode