Caixa de sugestão automática

  • Artigo

Use uma AutoSuggestBox para fornecer uma lista de sugestões para um usuário selecionar conforme digita.

Uma caixa de sugestão automática

Esse é o controle correto?

Se você quer um controle simples e personalizável que permita a pesquisa de texto com uma lista de sugestões, então escolha uma caixa de sugestão automática.

Para obter mais informações sobre como escolher o controle de texto certo, consulte o artigo Controles de texto.

Anatomia

O ponto de entrada para a caixa de sugestão automática consiste de um cabeçalho opcional e uma caixa de texto com texto de dica opcional:

Exemplo do ponto de entrada para o controle de sugestão automática

A lista de resultados da sugestão automática é preenchida automaticamente depois que o usuário começa a inserir texto. A lista de resultados pode aparecer acima ou abaixo da caixa de entrada de texto. Um botão "limpar tudo" aparece:

Exemplo do controle de sugestão automática expandido

Recomendações

  • Quando a caixa de sugestão automática for usada para realizar pesquisas e não houver nenhum resultado para o texto inserido, exiba a mensagem de uma linha "Nenhum resultado" para que os usuários saibam que a solicitação de pesquisa foi executada:

    Exemplo de uma caixa de sugestão automática com nenhum resultado de pesquisa

UWP e WinUI 2

Importante

As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência da API da UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .

Recomendamos usar o WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. O WinUI 2.2 ou posterior inclui um novo modelo para esse controle que usa cantos arredondados. Para obter mais informações, confira Raio de canto.

Criar uma caixa de sugestão automática

Abra o aplicativo Galeria do WinUI 3 e veja a AutoSuggestBox em ação.

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub

Para usar uma AutoSuggestBox, você precisa responder a três ações de usuário.

  • Texto alterado - quando o usuário insere texto, atualiza a lista de sugestões.
  • Sugestão escolhida – quando o usuário selecionar uma sugestão da lista, atualize a caixa de texto.
  • Consulta enviada - quando o usuário envia uma consulta, mostra os resultados da consulta.

Texto alterado

O evento TextChanged ocorre sempre que o conteúdo da caixa de texto é atualizado. Use a propriedade Reason de argumentos de evento para determinar se a alteração foi causada por entrada de usuário. Se a razão da alteração for UserInput, filtre seus dados de acordo com a entrada. Depois, configure os dados filtrados como o ItemsSource da AutoSuggestBox, para atualizar a lista de sugestões.

Para controlar como os itens são exibidos na lista de sugestões, você pode usar DisplayMemberPath ou ItemTemplate.

  • Para exibir o texto de uma única propriedade de seu item de dados, configure a propriedade DisplayMemberPath para escolher qual propriedade de seu objeto exibir na lista de sugestões.
  • Para definir uma aparência personalizada para cada item na lista, use a propriedade ItemTemplate.

Sugestão escolhida

Quando um usuário navega pela lista de sugestões usando o teclado, você precisa atualizar o texto na caixa de texto para corresponder.

Você pode configurar a propriedade TextMemberPath para escolher qual propriedade de seu objeto de dados exibir na caixa de texto. Se você especificar um TextMemberPath, a caixa de texto será atualizada automaticamente. Geralmente, você deve especificar o mesmo valor para DisplayMemberPath e TextMemberPath, para que o texto seja o mesmo na lista de sugestões e na caixa de texto.

Se você precisa mostrar mais do que uma propriedade simples, manipule o evento SuggestionChosen para preencher a caixa de texto com texto personalizado com base no item selecionado.

Consulta enviada

Manipule o evento QuerySubmitted para executar uma ação de consulta adequada para seu aplicativo e mostre o resultado para o usuário.

O evento QuerySubmitted ocorre quando um usuário confirma uma cadeia de caracteres de consulta. O usuário pode confirmar uma consulta de uma das seguintes maneiras:

  • Com o foco na caixa de texto, pressione Enter ou clique no ícone de consulta. A propriedade ChosenSuggestion de argumentos de evento é null.
  • Com o foco na lista de sugestões, pressione Enter, clique ou toque em um item. A propriedade ChosenSuggestion de argumentos de evento contém o item que foi selecionado da lista.

Em todos os casos, a propriedade QueryText de argumentos de evento contém o texto da caixa de texto.

Aqui está uma AutoSuggestBox simples com os manipuladores de eventos exigidos.

<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.
    }
}

Use uma AutoSuggestBox para fornecer uma lista de sugestões para um usuário selecionar conforme digita.

Por padrão, a caixa de entrada de texto não tem um botão de consulta aparente. Você pode configurar a propriedade QueryIcon para adicionar um botão com o ícone especificado no lado direito da caixa de texto. Por exemplo, para fazer com que a AutoSuggestBox se pareça com uma caixa de pesquisa típica, adicione um ícone de 'pesquisar' como este.

<AutoSuggestBox QueryIcon="Find"/>

Aqui está uma AutoSuggestBox com um ícone de 'pesquisar'.

Exemplo de controle de sugestão automática com um ícone de localização.

Obter o código de exemplo