自动建议框

使用 AutoSuggestBox 提供用户键入时从中进行选择的建议列表。

这是正确的控件吗？

如果想要一个简单的可自定义控件，该控件允许使用建议列表进行文本搜索，请选择自动建议框。

有关选择正确的文本控件的详细信息，请参阅文本控件文章。

结构

自动建议框的入口点由可选标头和包含可选提示文本的文本框组成：

用户开始输入文本后，自动建议结果列表会自动填充。 结果列表可以显示在文本输入框的上方或下方。 此时会显示“全部清除”按钮：

建议

• 使用自动建议框执行搜索，并且输入的文本不存在搜索结果时，将单行“无结果”消息显示为结果，以便用户知道其搜索请求已执行：

  

UWP 和 WinUI 2

此控件的 API 存在于 Windows.UI.Xaml.Controls 命名空间中。

建议使用最新的 WinUI 2 来获取所有控件的最新样式和模板。 WinUI 2.2 或更高版本包含此控件的使用圆角的新模板。 有关详细信息，请参阅圆角半径。

创建自动建议框

WinUI 3 库应用包括大多数 WinUI 3 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码

若要使用 AutoSuggestBox，需要响应 3 个用户操作。

• 文本更改 - 当用户输入文本时，更新建议列表。
• 选择的建议 - 当用户在建议列表中选择建议时，请更新文本框。
• 提交的查询 - 当用户提交查询时，显示查询结果。

文本已更改

每当更新文本框的内容时，TextChanged 事件发生。 使用事件参数 Reason 属性来确定更改是否是由于用户输入造成的。 如果更改原因为 UserInput，请根据输入筛选数据。 然后，将筛选的数据设置为 AutoSuggestBox 的 ItemsSource 以更新建议列表。

若要控制在建议列表中显示项的方式，可以使用 DisplayMemberPath 或 ItemTemplate。

• 若要显示数据项的单个属性的文本，请将 DisplayMemberPath 属性设置为从对象中选择要在建议列表中显示的属性。
• 若要定义列表中的每个项的自定义查找，请使用 ItemTemplate 属性。

选择的建议

当用户使用键盘浏览建议列表时，需要更新文本框中的文本才能匹配。

可以将 TextMemberPath 属性设置为从数据对象中选择要在文本框中显示的属性。 如果指定 TextMemberPath，则文本框会自动更新。 通常应为 DisplayMemberPath 和 TextMemberPath 指定相同的值，以便建议列表和文本框中的文本相同。

如果需要显示多个简单属性，请处理 Suggestion Selected 事件，以基于所选项使用自定义文本填充文本框。

提交的查询

处理 QuerySubmitted 事件以执行适用于应用的查询操作，并向用户显示结果。

当用户提交查询字符串时发生 QuerySubmitted 事件。 用户可以通过以下方式之一提交查询：

• 焦点位于文本框中时，按 Enter 或单击查询图标。 事件参数 ChosenSuggestion 属性为 null。
• 焦点位于建议列表中时，按 Enter、单击或点击某个项目。 事件参数 SelectedSuggestion 属性包含从列表中选择的项。

在所有情况下，事件参数 QueryText 属性包含文本框中的文本。

下面是具有所需事件处理程序的简单 AutoSuggestBox。

<AutoSuggestBox PlaceholderText="Search" QueryIcon="Find" Width="200"
                TextChanged="AutoSuggestBox_TextChanged"
                QuerySubmitted="AutoSuggestBox_QuerySubmitted"
                SuggestionChosen="AutoSuggestBox_SuggestionChosen"/>

private void AutoSuggestBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
{
    // Only get results when it was a user typing,
    // otherwise assume the value got filled in by TextMemberPath
    // or the handler for SuggestionChosen.
    if (args.Reason == AutoSuggestionBoxTextChangeReason.UserInput)
    {
        //Set the ItemsSource to be your filtered dataset
        //sender.ItemsSource = dataset;
    }
}


private void AutoSuggestBox_SuggestionChosen(AutoSuggestBox sender, AutoSuggestBoxSuggestionChosenEventArgs args)
{
    // Set sender.Text. You can use args.SelectedItem to build your text string.
}


private void AutoSuggestBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
{
    if (args.ChosenSuggestion != null)
    {
        // User selected an item from the suggestion list, take an action on it here.
    }
    else
    {
        // Use args.QueryText to determine what to do.
    }
}

使用 AutoSuggestBox 进行搜索

使用 AutoSuggestBox 提供用户键入时从中进行选择的建议列表。

默认情况下，文本输入框中不会显示查询按钮。 可以设置 QueryIcon 属性，以在文本框右侧添加具有指定图标的按钮。 例如，若要使 AutoSuggestBox 看起来像一个典型的搜索框，可添加一个“查找”图标，如下所示。

<AutoSuggestBox QueryIcon="Find"/>

下面是带有“查找”图标的 AutoSuggestBox。

获取示例代码

• WinUI 库示例 - 以交互式格式查看所有 XAML 控件。
• AutoSuggestBox 示例

相关文章

• 文本控件
• 拼写检查
• TextBox class（TextBox 类）
• Windows.UI.Xaml.Controls PasswordBox 类
• String.Length 属性