Поле автоматического предложения

Используйте autoSuggestBox, чтобы предоставить список предложений для пользователя, чтобы выбрать из типа.

Выбор правильного элемента управления

Если вы хотите простой настраиваемый элемент управления, который позволяет выполнять поиск текста со списком предложений, выберите поле автоматического предложения.

Дополнительные сведения можно найти в статье об элементах управления текстом.

Структура

Точка входа для поля авторекомендирования состоит из необязательного заголовка и текстового поля с необязательным текстом подсказки:

Список результатов автоматического предложения заполняется автоматически после того, как пользователь начнет вводить текст. Список результатов может отображаться выше или ниже текстового поля записи. Появится кнопка "очистить все":

Рекомендации

• При использовании поля автоматического предложения для выполнения поиска и отсутствия результатов поиска для введенного текста отображается однострочного сообщения "Нет результатов", чтобы пользователи знали, что их поисковый запрос выполнен:

  

UWP и WinUI 2

Внимание

Сведения и примеры в этой статье оптимизированы для приложений, использующих пакет SDK для приложений Windows и WinUI 3, но обычно применимы к приложениям UWP, использующим WinUI 2. См. справочник по API UWP для конкретных сведений и примеров платформы.

В этом разделе содержатся сведения, необходимые для использования элемента управления в приложении UWP или WinUI 2.

API для этого элемента управления существуют в пространстве имен Windows.UI.Xaml.Controls .

• API UWP: класс AutoSuggestBox, событие TextChanged, событие SuggestionChose, событие QuerySubmitted
• Откройте приложение коллекции WinUI 2 и просмотрите autoSuggestBox в действии. Приложения из коллекции WinUI 2 включают интерактивные примеры большинства элементов управления, возможностей и функций WinUI 2. Получите приложение из Microsoft Store или получите исходный код в GitHub.

Мы рекомендуем использовать последнюю версию WinUI 2 , чтобы получить самые актуальные стили и шаблоны для всех элементов управления. WinUI 2.2 или более поздней версии содержит новый шаблон для этого элемента управления, использующего округленные углы. Дополнительные сведения см. в разделе о радиусе угла.

Создание поля автоматического предложения

• Важные API: класс AutoSuggestBox, событие TextChanged, событие SuggestionChose, событие QuerySubmitted

Откройте приложение коллекции WinUI 3 и просмотрите autoSuggestBox в действии.

Приложение коллекции WinUI 3 включает интерактивные примеры большинства элементов управления, функций и функций WinUI 3. Получение приложения из Microsoft Store или получение исходного кода на GitHub

Чтобы использовать AutoSuggestBox, необходимо ответить на 3 действия пользователя.

• Изменен текст. Когда пользователь вводит текст, обновите список предложений.
• Выбрано предложение. Когда пользователь выбирает предложение в списке предложений, обновите текстовое поле.
• Отправленный запрос. Когда пользователь отправляет запрос, отображаются результаты запроса.

Изменен текст

Событие TextChanged возникает, когда обновляется содержимое текстового поля. Используйте свойство event args Reason , чтобы определить, произошло ли изменение из-за ввода пользователем. Если причина изменения — UserInput, отфильтруйте данные на основе входных данных. Затем задайте отфильтрованные данные в качестве объекта ItemsSource autoSuggestBox, чтобы обновить список предложений.

Чтобы управлять отображением элементов в списке предложений, можно использовать DisplayMemberPath или ItemTemplate.

• Чтобы отобразить текст одного свойства элемента данных, задайте для свойства DisplayMemberPath выбор свойства из объекта, отображаемого в списке предложений.
• Чтобы определить пользовательский поиск каждого элемента в списке, используйте свойство ItemTemplate.

Выбранное предложение

Когда пользователь переходит по списку предложений с помощью клавиатуры, необходимо обновить текст в текстовом поле для сопоставления.

Свойство TextMemberPath можно задать для выбора свойства из объекта данных для отображения в текстовом поле. Если указать TextMemberPath, текстовое поле обновляется автоматически. Обычно следует указать то же значение для DisplayMemberPath и TextMemberPath, чтобы текст был одинаковым в списке предложений и текстовом поле.

Если вам нужно показать больше простого свойства, обработайте событие SuggestionChosen , чтобы заполнить текстовое поле настраиваемым текстом на основе выбранного элемента.

Отправленный запрос

Обработайте событие QuerySubmitted, чтобы выполнить действие запроса, соответствующее приложению, и показать результат пользователю.

Событие QuerySubmitted возникает, когда пользователь фиксирует строку запроса. Пользователь может зафиксировать запрос одним из следующих способов:

• Пока фокус находится в текстовом поле, нажмите клавишу ВВОД или щелкните значок запроса. Свойство event args ChosenSuggestion имеет значение NULL.
• Пока фокус находится в списке предложений, нажмите клавишу ВВОД, щелкните или коснитесь элемента. Свойство event args SelectedSuggestion содержит элемент, выбранный из списка.

Во всех случаях свойство event args 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
• Класс Windows.UI.Xaml.Controls PasswordBox
• Свойство String.Length