Casella di suggerimento automatico

  • Articolo

Usare un controllo AutoSuggestBox per fornire un elenco di suggerimenti che un utente può selezionare durante la digitazione.

An auto suggest box

È il controllo giusto?

Se vuoi un controllo semplice e personalizzabile che consenta la ricerca di testo con un elenco di suggerimenti, scegli una casella di suggerimento automatico.

Per altre informazioni su come scegliere il controllo di testo più appropriato, vedi l'articolo Controlli di testo.

Anatomia

Il punto di ingresso per la casella di suggerimento automatico è costituito da un'intestazione facoltativa e da una casella di testo con testo hint facoltativo:

Example of the entry point for auto-suggest control

L'elenco dei risultati di suggerimento automatico viene popolato automaticamente quando l'utente inizia a immettere testo. L'elenco dei risultati può essere visualizzato sopra o sotto la casella di testo. Viene visualizzato un pulsante "cancella tutto":

Example of the expanded auto-suggest control

Consigli

  • Quando si usa la casella di suggerimento automatico per eseguire ricerche e non esistono risultati di ricerca per il testo immesso, visualizzare un messaggio "Nessun risultato" a riga singola in modo che gli utenti sappiano che la richiesta di ricerca è stata eseguita:

    Example of an auto suggest box with no search results

Piattaforma UWP e WinUI 2

Importante

Le informazioni e gli esempi in questo articolo sono ottimizzati per le app che usano Windows App SDK e WinUI 3, ma sono generalmente applicabili alle app UWP che usano WinUI 2. Per informazioni ed esempi specifici della piattaforma, consultare le indicazioni di riferimento sulle API UWP.

Questa sezione contiene informazioni necessarie per usare il controllo in un'app UWP o WinUI 2.

Le API per questo controllo esistono nello spazio dei nomi Windows.UI.Xaml.Controls.

È consigliabile usare la versione più recente di WinUI 2 per ottenere gli stili e i modelli più recenti per tutti i controlli. WinUI 2.2 o versioni successive include un nuovo modello per questo controllo che usa angoli arrotondati. Per altre informazioni, vedere Raggio dell'angolo.

Creare una casella di suggerimento automatico

Aprire l'app Raccolta WinUI 3 e visualizzare AutoSuggestBox in azione.

L'app Raccolta WinUI 3 include esempi interattivi della maggior parte dei controlli e delle funzionalità di WinUI 3. Scaricare l'app da Microsoft Store od ottenere il codice sorgente su GitHub

Per usare un controllo AutoSuggestBox, è necessario rispondere a 3 azioni utente.

  • Testo modificato: quando l'utente immette testo, aggiornare l'elenco dei suggerimenti.
  • Suggerimento scelto: quando l'utente sceglie un suggerimento nell'elenco dei suggerimenti, aggiornare la casella di testo.
  • Query inviata: quando l'utente invia una query, visualizzare i risultati della query.

Testo modificato

L'evento TextChanged si verifica ogni volta che viene aggiornato il contenuto della casella di testo. Utilizzare la proprietà Reason degli argomenti dell'evento per determinare se la modifica è dovuta all'input dell'utente. Se il motivo della modifica è UserInput, filtrare i dati in base all'input. Impostare quindi i dati filtrati come ItemsSource di AutoSuggestBox per aggiornare l'elenco dei suggerimenti.

Per controllare la modalità di visualizzazione degli elementi nell'elenco di suggerimenti, è possibile usare DisplayMemberPath o ItemTemplate.

  • Per visualizzare il testo di una singola proprietà dell'elemento di dati, impostare la proprietà DisplayMemberPath per scegliere la proprietà dall'oggetto da visualizzare nell'elenco dei suggerimenti.
  • Per definire una ricerca personalizzata per ogni elemento nell'elenco, utilizzare la proprietà ItemTemplate.

Suggerimento scelto

Quando un utente passa attraverso l'elenco di suggerimenti usando la tastiera, è necessario aggiornare il testo nella casella di testo in modo che corrisponda.

È possibile impostare la proprietà TextMemberPath per scegliere la proprietà dell'oggetto dati da visualizzare nella casella di testo. Se si specifica un oggetto TextMemberPath, la casella di testo viene aggiornata automaticamente. In genere è necessario specificare lo stesso valore per DisplayMemberPath e TextMemberPath in modo che il testo sia lo stesso nell'elenco di suggerimenti e nella casella di testo.

Se è necessario visualizzare più di una proprietà semplice, gestire l'evento SuggestionChosen per popolare la casella di testo con testo personalizzato in base all'elemento selezionato.

Query inviata

Gestire l'evento QuerySubmitted per eseguire un'azione di query appropriata per l'app e visualizzare il risultato all'utente.

L'evento QuerySubmitted si verifica quando un utente esegue il commit di una stringa di query. L'utente può eseguire il commit di una query in uno dei modi seguenti:

  • Mentre lo stato attivo si trova nella casella di testo, premere INVIO o fare clic sull'icona della query. La proprietà degli argomenti dell'evento ChosenSuggestion è null.
  • Mentre lo stato attivo si trova nell'elenco dei suggerimenti, premere INVIO, fare clic o toccare un elemento. La proprietà SelectedSuggestion degli argomenti dell'evento contiene l'elemento selezionato dall'elenco.

In tutti i casi, la proprietà degli argomenti dell'evento QueryText contiene il testo della casella di testo.

Di seguito è riportato un semplice controllo AutoSuggestBox con i gestori eventi necessari.

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

Usare un controllo AutoSuggestBox per fornire un elenco di suggerimenti che un utente può selezionare durante la digitazione.

Per impostazione predefinita, nella casella di immissione testo non è visualizzato un pulsante di query. È possibile impostare la proprietà QueryIcon per aggiungere un pulsante con l'icona specificata sul lato destro della casella di testo. Ad esempio, per fare in modo che AutoSuggestBox abbia un aspetto simile a una normale casella di ricerca, aggiungi un'icona 'Find', come questa.

<AutoSuggestBox QueryIcon="Find"/>

Ecco un controllo AutoSuggestBox con un'icona 'find'.

Example of auto-suggest control with a find icon.

Scaricare il codice di esempio