syncfusion-winforms-combobox（同步融合 winforms 组合框）

Implementing ComboBoxes

This skill explains how to implement and customize the Syncfusion Windows Forms SfComboBox control.

When to Use This Skill

• Use when the user needs a combobox/dropdown control in Windows Forms applications
• Use when implementing autocomplete functionality with Suggest, Append, or SuggestAppend modes
• Use when enabling multi-selection with checkboxes or token-based selection
• Use when binding combobox to data sources (lists, databases, LINQ to SQL)
• Use when implementing filtering or sorting in dropdown lists
• Use when customizing dropdown appearance, watermarks, or themes
• Use when adding custom controls to dropdown headers/footers
• Use when implementing token-based multi-selection (chip-style inputs)

Navigation Guide

Follow the links below to open focused reference pages for each task.

Getting Started

📄 Read: references/getting-started.md

• Assembly deployment and dependencies
• Creating SfComboBox via designer or code
• Basic data binding setup
• Quick autocomplete example
• Quick multi-selection example

Overview

📄 Read: references/overview.md

• Component features and capabilities
• Comparison with ComboBoxAdv, MultiSelectionComboBox, ComboBoxAutoComplete
• API comparison table
• When to use SfComboBox vs alternatives

Data Binding

📄 Read: references/data-binding.md

• DataSource, DisplayMember, ValueMember properties
• Binding to custom objects and collections
• Binding from Microsoft Access database
• Binding from LINQ to SQL classes
• Complex data binding scenarios

AutoComplete

📄 Read: references/autocomplete.md

• AutoCompleteMode: Suggest, Append, SuggestAppend
• Case-sensitive autocomplete
• AutoCompleteSuggestMode: StartsWith, Contains
• Setting autocomplete delay
• Complete code examples

Selection

📄 Read: references/selection.md

• Single selection (SelectedIndex, SelectedValue, SelectedItem)
• SelectedIndexChanged and SelectedValueChanged events
• Multi-selection mode with checkboxes
• Select all feature
• Delimiter character customization
• Tooltip for selected items
• Clear button customization

Token Support

📄 Read: references/token.md

• EnableToken property for chip-style selection
• Token appearance customization (TokenStyle)
• Adding and removing tokens
• Keyboard navigation for tokens
• SelectedValueChanged event for token tracking

Filtering

📄 Read: references/filtering.md

• Filter property with custom predicates
• RefreshFilter method
• Complete filtering example
• Custom filter conditions

Sorting

📄 Read: references/sorting.md

• SortDescriptors property
• Ascending and descending sort
• Custom comparer support

Dropdown Customization

📄 Read: references/dropdown.md

• MaxDropDownItems for limiting visible items
• AllowDropDownResize for resize gripper
• DropDownOpening and DropDownClosing events
• DropDownPosition customization
• DropDownWidth customization
• Loading custom header/footer controls
• Complete custom control example

Watermark

📄 Read: references/watermark.md

• AllowNull property for null value support
• Watermark text customization
• WatermarkForeColor styling

Appearance & Styling

📄 Read: references/appearance.md

• Visual styles and theming
• BackColor, ForeColor customization
• Border and font customization
• Office 2016 themes

Editing

📄 Read: references/editing.md

• DropDownStyle property
• Edit behavior customization
• Read-only mode

Item Height

📄 Read: references/item-height.md

• ItemHeight property
• Customizing dropdown item heights

Localization

📄 Read: references/localization.md

• Culture-specific formatting
• Resource file integration

UI Automation

📄 Read: references/ui-automation.md

• Accessibility features
• Screen reader support
• Keyboard navigation

Quick Start

Minimal SfComboBox example (C#):

using Syncfusion.WinForms.ListView;

namespace WindowsFormsApp
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();

            // Create SfComboBox
            SfComboBox sfComboBox1 = new SfComboBox();
            sfComboBox1.Location = new Point(20, 20);
            sfComboBox1.Size = new Size(200, 28);

            // Bind data
            List<string> states = new List<string> { "Alaska", "Arizona", "California", "Colorado", "Delaware" };
            sfComboBox1.DataSource = states;

            this.Controls.Add(sfComboBox1);
        }
    }
}

With autocomplete:

sfComboBox1.AutoCompleteMode = AutoCompleteMode.SuggestAppend;
sfComboBox1.AutoCompleteSuggestMode = AutoCompleteSuggestMode.Contains;

With multi-selection:

sfComboBox1.ComboBoxMode = ComboBoxMode.MultiSelection;
sfComboBox1.AllowSelectAll = true;

Common Patterns

Pattern 1: Data Binding with Custom Objects

public class USState
{
    public string LongName { get; set; }
    public string ShortName { get; set; }
}

List<USState> states = new List<USState>
{
    new USState { LongName = "California", ShortName = "CA" },
    new USState { LongName = "Texas", ShortName = "TX" }
};

sfComboBox1.DataSource = states;
sfComboBox1.DisplayMember = "LongName";
sfComboBox1.ValueMember = "ShortName";

Pattern 2: Multi-Selection with Tokens

sfComboBox1.EnableToken = true;
sfComboBox1.Style.TokenStyle.BackColor = Color.LightBlue;
sfComboBox1.Style.TokenStyle.BorderColor = Color.Blue;

Pattern 3: Custom Dropdown Header

sfComboBox1.DropDownListView.ShowHeader = true;
TextBox searchBox = new TextBox { Height = 25 };
sfComboBox1.DropDownListView.HeaderControl = searchBox;

Pattern 4: Filtering with Predicate

sfComboBox1.DropDownListView.View.Filter = (data) =>
{
    return ((USState)data).LongName.StartsWith("C");
};
sfComboBox1.DropDownListView.View.RefreshFilter();

Key Properties

Common Use Cases

Use Case 1: Country/State Selector

Implement a country or state dropdown with autocomplete for quick selection in address forms.

Use Case 2: Tag/Category Selection

Use multi-selection with tokens for selecting multiple tags or categories in content management systems.

Use Case 3: Searchable Dropdown

Add a search textbox in the dropdown header to filter large lists dynamically.

Use Case 4: Dependent Dropdowns

Implement cascading dropdowns where the second dropdown filters based on the first selection.

Use Case 5: Custom Item Templates

Create custom visual representations for dropdown items with images or multiple text lines.

Troubleshooting

Issue: Autocomplete not working

• Solution: Ensure AutoCompleteMode is set to Suggest, Append, or SuggestAppend (not None)

Issue: Multi-selection checkboxes not showing

• Solution: Set ComboBoxMode = ComboBoxMode.MultiSelection

Issue: DataSource not displaying items

• Solution: Verify DisplayMember matches a public property name in your data objects

Issue: Tokens not appearing

• Solution: Set EnableToken = true and select items from the dropdown

Issue: Dropdown not resizing

• Solution: Check AllowDropDownResize property is true (default)

Issue: SelectedValue returns null

• Solution: Ensure ValueMember is set correctly, or use SelectedItem directly

Issue: Filtering not working

• Solution: Call DropDownListView.View.RefreshFilter() after setting the Filter predicate