Casella combinata e casella di riepilogo

Usa una casella combinata (denominata anche elenco a discesa) per presentare un elenco di elementi che l'utente può selezionare. Una casella combinata viene inizialmente visualizzata nello stato compatto e quindi espansa per mostrare un elenco degli elementi selezionabili. Una casella di riepilogo è simile a una casella combinata, ma non è comprimibile, ovvero non viene visualizzata in stato compatto. Puoi ottenere altre informazioni sulle caselle di riepilogo alla fine di questo articolo.

Quando la casella combinata viene chiusa, mostra la selezione corrente oppure è vuota se non è selezionato alcun elemento. Quando l'utente espande la casella combinata, viene visualizzato l'elenco degli elementi selezionabili.

È il controllo giusto?

• Usare un elenco a discesa per consentire agli utenti di selezionare un singolo valore da un set di elementi che possono essere adeguatamente rappresentati con singole righe di testo.
• Usare una visualizzazione elenco o griglia anziché una casella combinata per visualizzare elementi che contengono più righe di testo o immagini.
• Quando sono presenti meno di cinque elementi, è consigliabile usare pulsanti di opzione (se è possibile selezionare un solo elemento) o caselle di controllo (se è possibile selezionare più elementi).
• Usa una casella combinata quando gli elementi di selezione sono di importanza secondaria nel flusso dell'app. Se l'opzione predefinita è consigliata per la maggior parte degli utenti nella maggior parte delle situazioni, la visualizzazione di tutti gli elementi tramite una visualizzazione elenco potrebbe attirare più attenzione sulle opzioni del necessario. È possibile risparmiare spazio e ridurre al minimo la distrazione usando una casella combinata.

Esempi

Casella combinata nello stato compatto può mostrare un'intestazione.

Anche se le caselle combinate si espandono per supportare lunghezze di stringa più lunghe, evitare stringhe eccessivamente lunghe che sono difficili da leggere.

Se la raccolta in una casella combinata è sufficientemente lunga, verrà visualizzata una barra di scorrimento per adattarla. Raggruppare gli elementi in modo logico nell'elenco.

Consigli

• Limitare il contenuto di testo degli elementi della casella combinata a una singola riga.
• Ordinare gli elementi in una casella combinata nell'ordine più logico. Raggruppare le opzioni correlate e posizionare le opzioni più comuni nella parte superiore. Ordina i nomi in ordine alfabetico, numeri in ordine numerico e date in ordine cronologico.

Caselle di riepilogo

Una casella di riepilogo consente all'utente di scegliere un singolo elemento o più elementi di una raccolta. Le caselle di riepilogo sono simili agli elenchi a discesa, ad eccezione del fatto che le caselle di riepilogo sono sempre aperte. Non esiste uno stato compatto (non espanso) per una casella di riepilogo. È possibile scorrere gli elementi nell'elenco se non è presente spazio per visualizzare tutti gli elementi.

Una casella di riepilogo è il controllo corretto?

• Una casella di riepilogo può essere utile quando gli elementi nell'elenco sono abbastanza importanti da visualizzare in modo sufficientemente evidente e quando è disponibile spazio sullo schermo sufficiente per visualizzare l'elenco completo.
• Una casella di riepilogo dovrebbe attirare l'attenzione dell'utente sul set completo di alternative in una scelta importante. Al contrario, un elenco a discesa attira inizialmente l'attenzione dell'utente sull'elemento selezionato.
• Evitare di usare una casella di riepilogo se:
  • Esiste un numero molto ridotto di elementi per l'elenco. Una casella di riepilogo a selezione singola con le stesse 2 opzioni potrebbe essere presentata meglio come pulsanti di opzione. Prendere in considerazione anche l'uso di pulsanti di opzione quando sono presenti 3 o 4 elementi statici nell'elenco.
  • La casella di riepilogo è a selezione singola e ha sempre le stesse 2 opzioni in cui una può essere implicita come non l'altra, ad esempio "on" e "off". Usare una singola casella di controllo o un interruttore attiva/disattiva.
  • C'è un numero molto elevato di elementi. Una scelta migliore per gli elenchi lunghi è la visualizzazione griglia e la visualizzazione elenco. Per elenchi molto lunghi di dati raggruppati, è preferibile lo zoom semantico.
  • Gli elementi sono valori numerici contigui. In questo caso, è consigliabile usare un dispositivo di scorrimento.
  • Gli elementi di selezione sono di importanza secondaria nel flusso dell'app o l'opzione predefinita è consigliata per la maggior parte degli utenti nella maggior parte delle situazioni. Usare invece un elenco a discesa.

Consigli per le caselle di riepilogo

• L'intervallo ideale di elementi in una casella di riepilogo è compreso tra 3 e 9.
• Una casella di riepilogo funziona correttamente quando gli elementi possono variare dinamicamente.
• Se possibile, impostare le dimensioni di una casella di riepilogo in modo che non sia necessario eseguire la panoramica o lo scorrimento dell'elenco di elementi.
• Verificare che lo scopo della casella di riepilogo e gli elementi attualmente selezionati sia deselezionata.
• Riservare effetti visivi e animazioni per il feedback tocco e per lo stato selezionato degli elementi.
• Limitare il contenuto di testo dell'elemento della casella di riepilogo a una singola riga. Se gli elementi sono oggetti visivi, è possibile personalizzare le dimensioni. Se un elemento contiene più righe di testo o immagini, usare invece una visualizzazione griglia o una visualizzazione elenco.
• Usa il tipo di carattere predefinito a meno che le linee guida del marchio non indichino l'uso di un altro tipo di carattere.
• Non usare una casella di riepilogo per eseguire comandi o per visualizzare o nascondere in modo dinamico altri controlli.

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 ComboBox, proprietà IsEditable, proprietà Text, evento TextSubmitted, classe ListBox
• Aprire l'app Raccolta WinUI 2 e visualizzare ComboBox 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.

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 combinata

• API importanti: Classe ComboBox, Proprietà IsEditable, Proprietà Text, Evento TextSubmitted, Classe ListBox

Aprire l'app Raccolta WinUI 3 e visualizzare ComboBox 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 popolare la casella combinata, aggiungi oggetti direttamente alla raccolta Items oppure associa la proprietà ItemsSource a un'origine dati. Gli elementi aggiunti a ComboBox vengono incapsulati in contenitori ComboBoxItem.

Ecco una casella combinata semplice con elementi aggiunti in XAML.

<ComboBox Header="Colors" PlaceholderText="Pick a color" Width="200">
    <x:String>Blue</x:String>
    <x:String>Green</x:String>
    <x:String>Red</x:String>
    <x:String>Yellow</x:String>
</ComboBox>

L'esempio seguente illustra l'associazione di una casella combinata a una raccolta di oggetti FontFamily.

<ComboBox x:Name="FontsCombo" Header="Fonts" Height="44" Width="296"
          ItemsSource="{x:Bind fonts}" DisplayMemberPath="Source"/>

ObservableCollection<FontFamily> fonts = new ObservableCollection<FontFamily>()
{
    fonts.Add(new FontFamily("Arial"));
    fonts.Add(new FontFamily("Courier New"));
    fonts.Add(new FontFamily("Times New Roman"));
};

Selezione degli elementi

Analogamente a ListView e GridView, il controllo ComboBox deriva da Selector, pertanto la selezione dell'utente può essere ottenuta nello stesso modo standard.

Puoi ottenere o impostare l'elemento selezionato della casella combinata con la proprietà SelectedItem, nonché ottenere o impostare l'indice dell'elemento selezionato usando la proprietà SelectedIndex.

Per ottenere il valore di una determinata proprietà dell'elemento di dati selezionato, puoi usare la proprietà SelectedValue. In questo caso, imposta SelectedValuePath in modo da specificare la proprietà dell'elemento selezionato di cui ottenere il valore.

Suggerimento

Se imposti SelectedItem o SelectedIndex per indicare la selezione predefinita e la proprietà viene impostata prima del popolamento della raccolta Items della casella combinata, si verifica un'eccezione. Se non definisci Items in XAML, è preferibile gestire l'evento Loaded della casella combinata e impostare SelectedItem o SelectedIndex nel gestore dell'evento Loaded.

Puoi eseguire l'associazione a queste proprietà in XAML oppure gestire l'evento SelectionChanged per rispondere alle modifiche della selezione.

Nel codice del gestore dell'evento puoi ottenere l'elemento selezionato dalla proprietà SelectionChangedEventArgs.AddedItems e l'elemento eventualmente selezionato in precedenza dalla proprietà SelectionChangedEventArgs.RemovedItems. Le raccolte AddedItems e RemovedItems contengono un solo elemento ognuna perché la casella combinata non supporta la selezione multipla.

Questo esempio mostra come gestire l'evento SelectionChanged e come eseguire l'associazione all'elemento selezionato.

<StackPanel>
    <ComboBox x:Name="colorComboBox" Width="200"
              Header="Colors" PlaceholderText="Pick a color"
              SelectionChanged="ColorComboBox_SelectionChanged">
        <x:String>Blue</x:String>
        <x:String>Green</x:String>
        <x:String>Red</x:String>
        <x:String>Yellow</x:String>
    </ComboBox>

    <Rectangle x:Name="colorRectangle" Height="30" Width="100"
               Margin="0,8,0,0" HorizontalAlignment="Left"/>

    <TextBlock Text="{x:Bind colorComboBox.SelectedIndex, Mode=OneWay}"/>
    <TextBlock Text="{x:Bind colorComboBox.SelectedItem, Mode=OneWay}"/>
</StackPanel>

private void ColorComboBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    string colorName = e.AddedItems[0].ToString();
    Color color;
    switch (colorName)
    {
        case "Yellow":
            color = Colors.Yellow;
            break;
        case "Green":
            color = Colors.Green;
            break;
        case "Blue":
            color = Colors.Blue;
            break;
        case "Red":
            color = Colors.Red;
            break;
    }
    colorRectangle.Fill = new SolidColorBrush(color);
}

SelectionChanged e spostamento tramite tastiera

Per impostazione predefinita, l'evento SelectionChanged si verifica quando un utente fa clic, tocca o preme INVIO su un elemento nell'elenco per confermare la selezione e la casella combinata viene chiusa. La selezione non viene modificata quando l'utente scorre l'elenco della casella combinata aperta con i tasti di direzione della tastiera.

Per creare una casella combinata che si aggiorni in tempo reale mentre l'utente si sposta con i tasti di direzione nell'elenco aperto (ad esempio un elenco a discesa per la selezione del tipo di carattere), imposta SelectionChangedTrigger su Always. In questo modo, l'evento SelectionChanged si verifica quando lo stato attivo passa a un altro elemento nell'elenco aperto.

Modifica del comportamento degli elementi selezionati

In Windows 10 versione 1809 (SDK 17763) o successiva, il comportamento degli elementi selezionati è stato aggiornato per supportare caselle combinate modificabili.

Nelle versioni precedenti a SDK 17763, il valore della proprietà SelectedItem e di conseguenza i valori di SelectedValue e SelectedIndex devono essere inclusi nella raccolta Items della casella combinata. Usando l'esempio precedente, l'impostazione colorComboBox.SelectedItem = "Pink" determina quanto segue:

• SelectedItem = null
• SelectedValue = null
• SelectedIndex = -1

In SDK 17763 e versioni successive non è necessario che il valore della proprietà SelectedItem e di conseguenza i valori di SelectedValue e SelectedIndex siano inclusi nella raccolta Items della casella combinata. Usando l'esempio precedente, l'impostazione colorComboBox.SelectedItem = "Pink" determina quanto segue:

• SelectedItem = Pink
• SelectedValue = Pink
• SelectedIndex = -1

Ricerca testuale

Le caselle combinate supportano automaticamente la ricerca all'interno delle raccolte. Man mano che gli utenti digitano caratteri su una tastiera fisica mentre si concentrano su una casella combinata aperta o chiusa, i candidati corrispondenti alla stringa dell'utente vengono visualizzati. Questa funzionalità è particolarmente utile quando si naviga in un lungo elenco. Quando interagiscono con un elenco a discesa contenente un elenco di stati, ad esempio, gli utenti possono premere il tasto "w" per visualizzare "Washington" e selezionarlo rapidamente. La ricerca di testo non fa distinzione tra maiuscole e minuscole.

Puoi disabilitare questa funzionalità impostando la proprietà IsTextSearchEnabled su false.

Rendere modificabile una casella combinata

Importante

Questa funzionalità richiede Windows 10 versione 1809 (SDK 17763) o successiva.

Per impostazione predefinita, una casella combinata consente all'utente di effettuare una selezione in un elenco predefinito di opzioni. In alcuni casi, tuttavia, l'elenco contiene solo un sottoinsieme dei valori validi e l'utente deve poter immettere altri valori non inclusi nell'elenco. A tale scopo, è possibile rendere la casella combinata modificabile.

Per rendere modificabile una casella combinata, imposta la proprietà IsEditable su true. Gestisci quindi l'evento TextSubmitted per usare il valore immesso dall'utente.

Per impostazione predefinita, il valore di SelectedItem viene aggiornato quando l'utente conferma il testo personalizzato. Puoi eseguire l'override di questo comportamento impostando Handled su true negli argomenti dell'evento TextSubmitted. Quando l'evento viene contrassegnato come gestito, la casella combinata non esegue altre azioni dopo l'evento e viene mantenuta nello stato di modifica. La proprietà SelectedItem non verrà aggiornata.

Questo esempio mostra una semplice casella combinata modificabile. L'elenco contiene stringhe semplici e qualsiasi valore immesso dall'utente viene usato così come immesso.

Un selettore dei nomi usati di recente consente all'utente di immettere stringhe personalizzate. L'elenco "RecentlyUsedNames" contiene alcuni valori che l'utente può scegliere, ma l'utente può anche aggiungere un nuovo valore personalizzato. La proprietà "CurrentName" rappresenta il nome attualmente immesso.

<ComboBox IsEditable="true"
          ItemsSource="{x:Bind RecentlyUsedNames}"
          SelectedItem="{x:Bind CurrentName, Mode=TwoWay}"/>

Testo inviato

Puoi gestire l'evento TextSubmitted per usare il valore immesso dall'utente. Nel gestore dell'evento convaliderai in genere la validità del valore immesso dall'utente, quindi userai tale valore nell'app. A seconda dei casi, potresti anche aggiungere il valore all'elenco delle opzioni della casella combinata per uso futuro.

L'evento TextSubmitted si verifica quando vengono soddisfatte queste condizioni:

• La proprietà IsEditable è true.
• L'utente immette testo non corrispondente a una voce esistente nell'elenco della casella combinata.
• L'utente preme INVIO oppure sposta lo stato attivo dalla casella combinata.

L'evento TextSubmitted non si verifica se l'utente immette testo e quindi si sposta verso l'alto o verso il basso nell'elenco.

Esempio: convalidare l'input e usarlo in locale

In questo esempio, un selettore delle dimensioni del carattere contiene un set di valori corrispondenti a diverse dimensioni, ma l'utente può immettere dimensioni del carattere non incluse nell'elenco.

Quando l'utente aggiunge un valore non presente nell'elenco, le dimensioni del carattere vengono aggiornate, ma il valore non viene aggiunto all'elenco.

Se il nuovo valore immesso non è valido, userai SelectedValue per ripristinare l'ultimo valore valido noto della proprietà Text.

<ComboBox x:Name="fontSizeComboBox"
          IsEditable="true"
          ItemsSource="{x:Bind ListOfFontSizes}"
          TextSubmitted="FontSizeComboBox_TextSubmitted"/>

private void FontSizeComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSubmittedEventArgs e)
{
    if (byte.TryParse(e.Text, out double newValue))
    {
        // Update the app's font size.
        _fontSize = newValue;
    }
    else
    {
        // If the item is invalid, reject it and revert the text.
        // Mark the event as handled so the framework doesn't update the selected item.
        sender.Text = sender.SelectedValue.ToString();
        e.Handled = true;
    }
}

Esempio: convalidare l'input e aggiungerlo all'elenco

In questo caso, un selettore del colore preferito contiene i colori preferiti più comuni (Red, Blue, Green, Orange), ma l'utente può immettere un colore preferito non incluso nell'elenco. Quando l'utente aggiunge un colore valido (come Pink), il nuovo colore immesso viene aggiunto all'elenco e impostato come colore preferito attivo.

<ComboBox x:Name="favoriteColorComboBox"
          IsEditable="true"
          ItemsSource="{x:Bind ListOfColors}"
          TextSubmitted="FavoriteColorComboBox_TextSubmitted"/>

private void FavoriteColorComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSubmittedEventArgs e)
{
    if (IsValid(e.Text))
    {
        FavoriteColor newColor = new FavoriteColor()
        {
            ColorName = e.Text,
            Color = ColorFromStringConverter(e.Text)
        }
        ListOfColors.Add(newColor);
    }
    else
    {
        // If the item is invalid, reject it but do not revert the text.
        // Mark the event as handled so the framework doesn't update the selected item.
        e.Handled = true;
    }
}

bool IsValid(string Text)
{
    // Validate that the string is: not empty; a color.
}

Scaricare il codice di esempio

• Esempio di Raccolta WinUI: visualizza tutti i controlli XAML in un formato interattivo.

Articoli correlati

• Controlli di testo
• Linee guida per il controllo ortografia
• Classe TextBox
• Classe PasswordBox
• Proprietà String.Length