syncfusion-wpf-autocomplete（同步融合 wpf 自动完成）

Implementing WPF Autocomplete (SfTextBoxExt)

A comprehensive guide for implementing the Syncfusion WPF Autocomplete control (SfTextBoxExt) that provides intelligent text suggestions, advanced filtering, multi-selection capabilities, and extensive customization options for enhanced user input experiences.

When to Use This Skill

Use this skill when user need to:

• Implement autocomplete textbox with predictive text suggestions
• Add search functionality with filtered dropdown suggestions
• Enable multi-selection with token or delimiter modes
• Create type-ahead input fields with intelligent filtering
• Build searchable dropdowns with custom data sources
• Implement tag/token selection UI for multiple items
• Add suggestion boxes to text input controls
• Configure advanced filtering with 18+ filter modes
• Customize text input appearance with watermarks and templates
• Handle selection events and retrieve selected values
• Support diacritic-insensitive search for international text
• Highlight matching text in suggestion lists

This skill covers the complete SfTextBoxExt control with detailed implementation guides for all features including data binding, filtering strategies, selection handling, dropdown customization, and advanced capabilities.

Component Overview

SfTextBoxExt is an enhanced TextBox control that extends standard WPF TextBox functionality with autocomplete capabilities. It provides intelligent suggestions based on user input, supports multiple filtering modes, and enables both single and multi-selection scenarios.

Key Capabilities

Core Features:

• 18+ Filtering Modes: StartsWith, EndsWith, Contains, Equals, Custom, and more
• Multiple AutoComplete Modes: Suggest, Append, SuggestAppend
• Multi-Selection Support: Token and Delimiter modes
• Rich Data Binding: Support for simple and complex data types
• Custom Templates: AutoComplete items, watermark, no-results templates
• Event-Driven: Selection, popup, and suggestion change events

Advanced Features:

• Diacritic Sensitivity: Search across languages with accent-insensitive filtering
• Text Highlighting: Visual indication of matching text
• Custom Filtering: Implement multi-path or complex filter logic
• Popup Configuration: Placement, delay, height, and behavior settings
• Performance Optimization: Minimum prefix characters, maximum suggestions

UI Customization:

• Watermark Support: Placeholder text and custom templates
• Visual Styling: Font, color, background customization
• Token Appearance: Custom token templates with images
• Dropdown Styling: Background, selection color, item templates
• Button Controls: Optional dropdown and clear buttons

Documentation and Navigation Guide

This skill uses a progressive disclosure pattern. Start with SKILL.md for overview and navigation, then read specific reference files based on your implementation needs.

Getting Started

📄 Read: references/getting-started.md

When to read: Setting up SfTextBoxExt for the first time, initial implementation

What's covered:

• Assembly deployment and NuGet package installation
• Creating WPF application with SfTextBoxExt
• Adding control via designer, XAML, and C#
• Populating AutoComplete with data sources
• Data models and ViewModel setup
• AutoComplete modes (Suggest, Append, SuggestAppend, None)
• Basic selection configuration
• Theme support and styling

AutoComplete and Filtering

📄 Read: references/autocomplete-filtering.md

When to read: Implementing filtering logic, customizing suggestion behavior

What's covered:

• AutoCompleteSource property and data binding
• SearchItemPath for custom data objects
• AutoCompleteItemTemplate for visual customization
• SuggestionMode options (18+ filter modes including StartsWith, EndsWith, Contains, Equals, Custom)
• MinimumPrefixCharacters configuration
• IgnoreCase for case-insensitive filtering
• ImageMemberPath for displaying images
• MaximumSuggestionsCount to limit results
• NoResultsFoundTemplate customization
• FilterSuggestions method for manual filtering
• SuggestionsChanged event handling

Selection and Value Retrieval

📄 Read: references/selection.md

When to read: Implementing single or multi-selection, retrieving selected values

What's covered:

• MultiSelectMode options (None, Token, Delimiter)
• SelectedItem property for single selection
• SelectedItems collection for multi-selection
• Token representation and layout
• TokensWrapMode (Wrap, None) configuration
• EnableAutoSize for dynamic height
• Delimiter mode with custom separators
• Delimiter property configuration
• SelectedValue and ValueMemberPath
• SuggestionIndex for selected item index
• ImageMemberPath for token images
• SelectedItemChanged event handling

Dropdown Customization

📄 Read: references/dropdown-customization.md

When to read: Customizing suggestion popup appearance and behavior

What's covered:

• DropDownBackground for suggestion box styling
• SuggestionBoxPlacement options (Bottom, Top, None)
• MaximumDropDownHeight configuration
• ShowSuggestionsOnFocus behavior
• PopupDelay for delayed display
• SelectionBackgroundColor for selected items
• AutoHighlightMatchedItem API
• SuggestionPopupOpened event
• SuggestionPopupClosed event
• Complete dropdown styling examples

TextBox Customization

📄 Read: references/textbox-customization.md

When to read: Customizing TextBox appearance, adding watermark or buttons

What's covered:

• Watermark property for placeholder text
• WatermarkTemplate for custom placeholder UI
• Text styling (FontSize, FontWeight, FontFamily)
• ShowDropDownButton for dropdown icon
• ShowClearButton for clear functionality
• Visual customization patterns
• Template customization examples

Advanced Features

📄 Read: references/advanced-features.md

When to read: Implementing diacritic search, text highlighting, custom filters

What's covered:

• Diacritic sensitivity with IgnoreDiacritic
• TextHighlightMode (FirstOccurrence, MultiOccurrence)
• HighlightedTextColor configuration
• HighlightedTextStyle customization
• Multipath search implementation
• Custom SuggestionMode setup
• Filter property for custom filtering logic
• Custom filter implementation examples
• Dispose method for resource cleanup
• Performance optimization tips

Quick Start Example

Basic AutoComplete with Suggestions

<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 = "john@example.com" },
            new Employee { Name = "Jane Smith", Email = "jane@example.com" },
            new Employee { Name = "Mike Johnson", Email = "mike@example.com" }
        };
    }
}

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

Multi-Selection with Tokens

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

Common Patterns

Pattern 1: Basic AutoComplete with Case-Insensitive Search

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

Pattern 2: Multi-Selection with Event Handling

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

Pattern 3: Custom Filtering

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

Pattern 4: Popup Configuration

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

Key Properties Reference

Essential Properties

Configuration Properties

Customization Properties

Events

Common Use Cases

1. Employee Search and Selection

Implement autocomplete for searching employees by name, email, or department with multi-field filtering.

2. Tag/Label Selection

Enable multi-selection with token mode for selecting tags, categories, or labels with visual token representation.

3. Product Search

Create searchable product dropdown with images, custom templates, and rich item display.

4. Email Recipients (To/CC/BCC)

Build email recipient selection with token mode, delimiter support, and contact suggestions.

5. Location Search

Implement location autocomplete with address suggestions, diacritic-insensitive search for international addresses.

6. Code Editor Auto-Completion

Create code suggestion dropdown with syntax highlighting, custom filtering, and keyboard navigation.

7. Form Auto-Fill

Add intelligent form input suggestions based on historical data or predefined options.

8. Multi-Language Search

Implement search with diacritic sensitivity for international content with accent-insensitive matching.

Related Resources

• Syncfusion Documentation: https://help.syncfusion.com/wpf/autocomplete/overview
• API Reference: https://help.syncfusion.com/cr/wpf/Syncfusion.Windows.Controls.Input.SfTextBoxExt.html
• Sample Browser: Available via Syncfusion Control Panel
• GitHub Samples: https://github.com/SyncfusionExamples/wpf-textboxext-examples

Support and Licensing

SfTextBoxExt is part of Syncfusion Essential Studio for WPF, a commercial product requiring a valid license. Visit https://www.syncfusion.com/sales/products for licensing information.

Next Steps: Navigate to the specific reference file based on your implementation needs. Start with getting-started.md for initial setup, or jump directly to feature-specific guides for advanced scenarios.