Caixa de sugestão automática

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

Será este o controlo correto?

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

Para saber mais sobre como escolher o controle de texto correto, veja o artigo Controles de texto .

Anatomia

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

A lista de resultados de sugestão automática é preenchida automaticamente assim 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" é exibido:

Recommendations

• Ao usar a caixa de sugestão automática para realizar pesquisas e não existirem resultados de pesquisa para o texto inserido, exiba uma mensagem de linha única "Sem resultados" como resultado para que os usuários saibam que sua solicitação de pesquisa foi executada:

  

Criar uma caixa de sugestão automática

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

Para usar uma AutoSuggestBox, você precisa responder a 3 ações do usuário.

• Texto alterado - Quando o usuário inserir texto, atualize a lista de sugestões.
• Sugestão escolhida - Quando o usuário escolher uma sugestão na lista de sugestões, atualize a caixa de texto.
• Consulta enviada - Quando o usuário envia uma consulta, mostre os resultados da consulta.

Texto alterado

O evento TextChanged ocorre sempre que o conteúdo da caixa de texto é atualizado. Use os argumentos de evento da propriedade Reason para determinar se a alteração foi devida à entrada do utilizador. Se o motivo da alteração for UserInput, filtre seus dados com base na entrada. Em seguida, defina os dados filtrados como 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 do item de dados, defina a propriedade DisplayMemberPath para escolher qual propriedade do objeto será exibida 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 definir a propriedade TextMemberPath para escolher qual propriedade do seu objeto de dados será exibida na caixa de texto. Se você especificar um TextMemberPath, a caixa de texto será atualizada automaticamente. Normalmente, 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ê precisar mostrar mais do que uma simples propriedade, 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 realizar uma ação de consulta adequada à sua aplicação e apresentar o resultado ao utilizador.

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

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

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

Aqui está um AutoSuggestBox simples com os manipuladores de eventos necessários.

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

Utilize a AutoSuggestBox para pesquisar

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

Por padrão, a caixa de entrada de texto não tem um botão de consulta mostrado. Você pode definir 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 pareça uma caixa de pesquisa típica, adicione um ícone 'localizar', como este.

<AutoSuggestBox QueryIcon="Find"/>

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

UWP e WinUI 2

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

Recomendamos usar a WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Consulte Raio de cantopara obter mais informações.

Artigos relacionados

• Controles de texto
• Verificação ortográfica
• Classe TextBox
• Classe PasswordBox do Windows.UI.Xaml.Controls
• Propriedade String.Length