自动建议框
使用 AutoSuggestBox 提供用户键入时从中进行选择的建议列表。
这是正确的控件吗？
如果想要一个简单的可自定义控件，该控件允许使用建议列表进行文本搜索，请选择自动建议框。
有关选择正确的文本控件的详细信息，请参阅文本控件文章。
结构
自动建议框的入口点由可选标头和包含可选提示文本的文本框组成：
用户开始输入文本后，自动建议结果列表会自动填充。 结果列表可以显示在文本输入框的上方或下方。 此时会显示“全部清除”按钮：
建议
使用自动建议框执行搜索，并且输入的文本不存在搜索结果时，将单行“无结果”消息显示为结果，以便用户知道其搜索请求已执行：
UWP 和 WinUI 2
重要
本文中的信息和示例是针对使用 Windows App SDK 和 WinUI 3 的应用优化的，但通常适用于使用 WinUI 2 的 UWP 应用。 有关特定于平台的信息和示例，请查看 UWP API 参考。
本部分包含在 UWP 或 WinUI 2 应用中使用该控件所需的信息。
此控件的 API 存在于 Windows.UI.Xaml.Controls 命名空间中。
- UWP API：AutoSuggestBox 类、TextChanged 事件、SuggestionChose 事件、QuerySubmitted 事件
- 打开 WinUI 2 库应用并查看 AutoSuggestBox 的操作。 WinUI 2 库应用包括大多数 WinUI 2 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。
建议使用最新的 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 示例
