syncfusion-winui-autocomplete（Synfusion WinUI 自动完成）

Implementing AutoComplete (SfAutoComplete)

The Syncfusion WinUI AutoComplete (SfAutoComplete) is a highly optimized control for providing filtered suggestions from large datasets as users type. It supports both single and multiple item selection, displaying selected items as tokens with images, text, and close buttons for easy removal.

When to Use This Skill

Use this skill when the user needs to:

• Implement autocomplete search functionality in WinUI applications
• Create searchable dropdowns with filtered suggestions based on user input
• Build tag or token input fields with multi-select capability
• Filter large datasets based on characters entered by the user
• Provide search-as-you-type experiences with auto-suggestions
• Implement multi-select dropdowns with chip/token display
• Add watermark text to guide user input in search fields
• Customize suggestion item display with images and custom templates
• Handle "no results found" scenarios with custom messaging
• Add leading/trailing icons or buttons to autocomplete inputs

Component Overview

Package: Syncfusion.Editors.WinUI Namespace: Syncfusion.UI.Xaml.Editors Control: SfAutoComplete

Key Capabilities:

• Single and multiple selection modes
• Real-time filtering (StartsWith or Contains)
• Custom filtering logic support
• Token/chip display for selected items
• Highlighting of matched text
• Grouping of suggestions
• Leading and trailing views
• Watermark/placeholder text
• Keyboard navigation
• Template customization

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

When the user needs to:

• Install the AutoComplete package
• Create and configure the control
• Set up data binding with ItemsSource
• Configure TextMemberPath and DisplayMemberPath
• Implement basic autocomplete functionality

Selection

📄 Read: references/selection.md

When the user needs to:

• Configure single vs multiple selection
• Handle selected items programmatically
• Display tokens/chips for multiple selections
• Listen to selection change events
• Work with SelectedItem or SelectedItems properties

Searching and Filtering

📄 Read: references/searching-filtering.md

When the user needs to:

• Configure filtering behavior (StartsWith or Contains)
• Implement custom filtering logic
• Search based on specific properties
• Handle auto-fill and auto-suggestions
• Select default items after filtering

UI Customization

📄 Read: references/ui-customization.md

When the user needs to:

• Customize dropdown item templates
• Add leading icons or buttons
• Add trailing actions or clear buttons
• Style selected item tokens
• Handle "no results found" UI
• Set watermark/placeholder text

Advanced Features

📄 Read: references/advanced-features.md

When the user needs to:

• Group suggestions by category
• Highlight matched text in suggestions
• Implement keyboard shortcuts
• Ensure accessibility compliance
• Handle advanced user interactions

Quick Start Example

Basic Single-Selection AutoComplete

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfAutoComplete x:Name="autoComplete"
                                Width="250"
                                PlaceholderText="Search social media..."
                                ItemsSource="{Binding SocialMedias}"
                                DisplayMemberPath="Name"
                                TextMemberPath="Name"
                                TextSearchMode="Contains" />
    </Grid>
</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 = "Instagram", ID = 1 },
            new SocialMedia { Name = "Twitter", ID = 2 },
            new SocialMedia { Name = "LinkedIn", ID = 3 }
        };
    }
}

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

Multi-Selection with Tokens

<editors:SfAutoComplete x:Name="autoComplete"
                        Width="300"
                        SelectionMode="Multiple"
                        PlaceholderText="Select multiple items..."
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains" />

Common Patterns

Pattern 1: Search with Contains Filter

<editors:SfAutoComplete ItemsSource="{Binding Countries}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains"
                        PlaceholderText="Type to search..." />

Use when users need to find items by any part of the text, not just the beginning.

Pattern 2: Multi-Select Tags with Custom Display

<editors:SfAutoComplete SelectionMode="Multiple"
                        ItemsSource="{Binding Tags}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Padding="5">
                <TextBlock Text="{Binding Name}"
                          FontWeight="SemiBold"/>
            </StackPanel>
        </DataTemplate>
    </editors:SfAutoComplete.ItemTemplate>
</editors:SfAutoComplete>

Use for tagging systems where users select multiple items displayed as tokens.

Pattern 3: Autocomplete with Leading Icon

<editors:SfAutoComplete ItemsSource="{Binding Items}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.LeadingView>
        <Grid Padding="8">
            <Path Data="M15.5 14h-.79l-.28-.27C15.41..."
                  Fill="{ThemeResource SystemAccentColor}"/>
        </Grid>
    </editors:SfAutoComplete.LeadingView>
</editors:SfAutoComplete>

Use to provide visual context (e.g., search icon) for the autocomplete field.

Pattern 4: Custom "No Results" Message

<editors:SfAutoComplete ItemsSource="{Binding Products}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        NoResultsFoundContent="No products found. Try a different search." />

Use to provide helpful feedback when filtering returns no matches.

Key Properties

Common Use Cases

Email Recipient Selector

Multi-select autocomplete for selecting email recipients from a contact list, displaying selected contacts as removable tokens.

Product Search

Single-select autocomplete for finding products in an e-commerce app, with contains-based filtering for flexible searching.

Category Tagging

Multi-select autocomplete for assigning multiple categories or tags to items, with custom token display.

Location Search

Single-select autocomplete with grouped suggestions (Countries > Cities), using StartsWith filtering for quick navigation.

Skill Search

Multi-select autocomplete for selecting user skills from a predefined list, with "no results" message for unrecognized entries.

Related Components

• ComboBox - For simple dropdown selection without autocomplete filtering
• TextBox - For basic text input without suggestions (if documented)

Integration Tips

With MVVM:

• Bind ItemsSource to ViewModel's ObservableCollection
• Use SelectedItem or SelectedItems with two-way binding
• Handle selection changes in ViewModel via binding commands

Performance:

• Use virtualization for large datasets (>1000 items)
• Consider async loading for remote data sources
• Use TextSearchMode.StartsWith for better performance with very large lists

Accessibility:

• Always set PlaceholderText to guide users
• Use AutomationProperties.Name for screen readers
• Ensure keyboard navigation works (Tab, Enter, Esc)
• Test with high contrast themes

Troubleshooting Quick Fixes

Next Steps: For detailed implementation, navigate to the specific reference file matching your needs using the documentation guide above.