Casella di suggerimento automatico
Usare un controllo AutoSuggestBox per fornire un elenco di suggerimenti che un utente può selezionare durante la digitazione.
È 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:
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":
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:
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 sono presenti nello spazio dei nomi Windows.UI.Xaml.Controls.
- API UWP: classe AutoSuggestBox, evento TextChanged, evento SuggestionChose, evento QuerySubmitted
- Aprire l'app Raccolta WinUI 2 e visualizzare AutoSuggestBox in azione. L'app Raccolta WinUI 2 include esempi interattivi della maggior parte dei controlli e delle funzionalità di WinUI 2. Ottenere l'app da Microsoft Store o visualizzare il codice sorgente in GitHub.
È 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
- API importanti: classe AutoSuggestBox, evento TextChanged, evento SuggestionChose, evento QuerySubmitted
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 AutoSuggestBox per la ricerca
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'.
Scaricare il codice di esempio
- Esempio di Raccolta WinUI: visualizza tutti i controlli XAML in un formato interattivo.
- Esempio di AutoSuggestBox
