Поле автозаполнения

  • Статья

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

Поле автозаполнения

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

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

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

Структура

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

Пример точки входа для элемента управления автозаполнения

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

Пример развернутого элемента управления автозаполнения

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

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

    Пример поля автозаполнения без результатов поиска

UWP и WinUI 2

Важно!

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

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

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

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

Создайте поле автозаполнения

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

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

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

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

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

Событие TextChanged возникает, когда обновляется содержимое текстового поля. Используйте свойство Причина аргументов события, чтобы определить, было ли изменение внесено пользователем. Если причиной изменения является UserInput, отфильтруйте данные на основе введенных данных. После этого установите отфильтрованные данные как свойство ItemsSource элемента AutoSuggestBox для обновления списка предложений.

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

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

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

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

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

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

Отправка запроса

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

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

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

Во всех случаях свойство аргумента 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, чтобы предоставить список предложений, из которых пользователь по мере ввода текста может выбрать нужное.

По умолчанию у поля ввода текста нет кнопки запроса. Вы можете настроить свойство QueryIcon, чтобы добавить кнопку с выбранным значком справа от текстового поля. Например, чтобы поле AutoSuggestBox выглядело как типичное поле поиска, добавьте значок поиска.

<AutoSuggestBox QueryIcon="Find"/>

Вот пример AutoSuggestBox со значком поиска.

Пример элемента управления автозаполнения со значком поиска.

Получение примера кода