Caixa de combinação e caixa de listagem

Use uma caixa de combinação (também conhecida como lista suspensa) para apresentar uma lista de itens que um usuário pode selecionar. Uma caixa de combinação começa num estado compacto e expande-se para exibir uma lista de itens que podem ser selecionados. Uma caixa de listagem é semelhante a uma caixa de combinação, mas não é dobrável/não tem um estado compacto. Você pode saber mais sobre caixas de listagem no final deste artigo.

Quando a caixa de combinação é fechada, ela exibe a seleção atual ou fica vazia se não houver nenhum item selecionado. Quando o usuário expande a caixa de combinação, ele exibe a lista de itens selecionáveis.

Será este o controlo correto?

• Use uma lista suspensa para permitir que os usuários selecionem um único valor de um conjunto de itens que podem ser representados adequadamente com linhas únicas de texto.
• Use um modo de exibição de lista ou grade em vez de uma caixa de combinação para exibir itens que contenham várias linhas de texto ou imagens.
• Quando houver menos de cinco itens, considere usar botões de opção (se apenas um item puder ser selecionado) ou caixas de seleção (se vários itens puderem ser selecionados).
• Use uma caixa de combinação quando os itens de seleção forem de importância secundária no fluxo do seu aplicativo. Se a opção padrão for recomendada para a maioria dos usuários na maioria das situações, mostrar todos os itens usando um modo de exibição de lista pode chamar mais atenção para as opções do que o necessário. Você pode economizar espaço e minimizar a distração usando uma caixa de combinação.

Examples

Uma caixa de combinação em seu estado compacto pode mostrar um cabeçalho.

Embora as caixas de combinação se expandam para suportar comprimentos de cadeia de caracteres mais longos, evite cadeias de caracteres excessivamente longas que são difíceis de ler.

Se a coleção em uma caixa de combinação for longa o suficiente, uma barra de rolagem aparecerá para acomodá-la. Agrupe itens logicamente na lista.

Recommendations

• Limite o conteúdo de texto dos itens da caixa de combinação a uma única linha.
• Classifique os itens em uma caixa de combinação na ordem mais lógica. Agrupe as opções relacionadas e coloque as opções mais comuns no topo. Classifique nomes em ordem alfabética, números em ordem numérica e datas em ordem cronológica.

Caixas de listagem

Uma caixa de listagem permite que o usuário escolha um único item ou vários itens de uma coleção. As caixas de listagem são semelhantes às listas desdobráveis, exceto que as caixas de listagem estão sempre abertas — não existe um estado compacto (não expandido) para uma caixa de listagem. Os itens na lista podem ser rolados se não houver espaço para mostrar tudo.

Uma caixa de listagem é o controle certo?

• Uma caixa de listagem pode ser útil quando os itens na lista são importantes o suficiente para serem exibidos com destaque, e quando há espaço suficiente na tela, para mostrar a lista completa.
• Uma caixa de listagem deve chamar a atenção do usuário para o conjunto completo de alternativas em uma escolha importante. Em contraste, uma lista suspensa inicialmente chama a atenção do utilizador para o item selecionado.
• Evite usar uma caixa de listagem se:
  • Há um número muito pequeno de itens na lista. Uma caixa de listagem de seleção única que tem sempre as mesmas 2 opções pode ser mais bem apresentada como botões de opção. Considere também o uso de botões de opção quando houver 3 ou 4 itens estáticos na lista.
  • A caixa de listagem é de seleção única e tem sempre as mesmas 2 opções, onde uma pode ser entendida como o oposto da outra, como "ligado" e "desligado". Use uma única caixa de seleção ou um interruptor.
  • Há um número muito grande de itens. A melhor opção para listas longas é a vista de grelha e a vista de lista. Para listas muito longas de dados agrupados, o zoom semântico é preferível.
  • Os itens são valores numéricos contíguos. Se for esse o caso, considere usar um controle deslizante .
  • Os itens de seleção são de importância secundária no fluxo do seu aplicativo ou a opção padrão é recomendada para a maioria dos usuários na maioria das situações. Em vez disso, use uma lista suspensa.

Recomendações para caixas de listagem

• O intervalo ideal de itens em uma caixa de listagem é de 3 a 9.
• Uma caixa de listagem funciona bem quando seus itens podem variar dinamicamente.
• Se possível, defina o tamanho de uma caixa de listagem para que sua lista de itens não precise ser deslocada ou rolada.
• Verifique se a finalidade da caixa de listagem e quais itens estão selecionados no momento está clara.
• Reserve efeitos visuais e animações para feedback de toque e para o estado selecionado dos itens.
• Limite o conteúdo de texto do item da caixa de listagem a uma única linha. Se os itens forem visuais, você poderá personalizar o tamanho. Se um item contiver várias linhas de texto ou imagens, use um modo de exibição de grade ou de lista.
• Use a fonte padrão, a menos que as diretrizes da sua marca indiquem usar outra.
• Não use uma caixa de listagem para executar comandos ou para mostrar ou ocultar dinamicamente outros controles.

Criar uma caixa de combinação

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

Você preenche a caixa de combinação adicionando objetos diretamente à coleção Items ou ligando a propriedade ItemsSource a uma fonte de dados. Os itens adicionados à ComboBox são encapsulados em contêineres ComboBoxItem.

Aqui está uma caixa de combinação simples com itens adicionados em 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>

O exemplo a seguir demonstra a vinculação de uma caixa de combinação a uma coleção de objetos 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"));
};

Seleção de itens

Assim como o ListView e o GridView, o ComboBox é derivado do Seletor, para que se possa obter a seleção do utilizador da mesma forma padrão.

Você pode obter ou definir o item selecionado da caixa de combinação usando a propriedade SelectedItem e obter ou definir o índice do item selecionado usando a propriedade SelectedIndex.

Para obter o valor de uma propriedade específica no item de dados selecionado, você pode usar a propriedade SelectedValue . Nesse caso, defina o SelectedValuePath para especificar de qual propriedade no item selecionado obter o valor.

Você pode vincular a essas propriedades em XAML ou lidar com o evento SelectionChanged para reagir a alterações de seleção.

No código do manipulador de eventos, pode-se obter o item selecionado da propriedade SelectionChangedEventArgs.AddedItems. Você pode obter o item selecionado anteriormente (se houver) da propriedade SelectionChangedEventArgs.RemovedItems. As coleções AddedItems e RemovedItems contêm apenas 1 item porque a caixa de combinação não oferece suporte a várias seleções.

Este exemplo mostra como manipular o evento SelectionChanged e também como vincular ao item selecionado.

<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 a navegação pelo teclado

Por padrão, o evento SelectionChanged ocorre quando um usuário clica, toca ou pressiona Enter em um item na lista para confirmar sua seleção e a caixa de combinação é fechada. A seleção não muda quando o usuário navega na lista de caixas de combinação abertas com as teclas de seta do teclado.

Para criar uma caixa de combinação que "atualiza em tempo real" enquanto o usuário está a navegar pela lista aberta com as teclas de seta (como uma lista suspensa de seleção de fonte), defina SelectionChangedTrigger como Always. Isso faz com que o evento SelectionChanged ocorra quando o foco muda para outro item na lista aberta.

Alteração de comportamento do item selecionado

No Windows 10, versão 1809 (SDK 17763) ou posterior, o comportamento dos itens selecionados é atualizado para oferecer suporte a caixas de combinação editáveis.

Antes do SDK 17763, o valor da propriedade SelectedItem (e, portanto, SelectedValue e SelectedIndex) devia constar na coleção Items da caixa de combinação. Usando o exemplo anterior, a configuração colorComboBox.SelectedItem = "Pink" resulta em:

• SelectedItem = nulo
• SelectedValue = nulo
• ÍndiceSelecionado = -1

No SDK 17763 e em versões posteriores, o valor da propriedade SelectedItem (e, portanto, SelectedValue e SelectedIndex) não precisa estar presente na coleção Items da caixa de combinação. Usando o exemplo anterior, a configuração colorComboBox.SelectedItem = "Pink" resulta em:

• SelectedItem = Rosa
• SelectedValue = Rosa
• SelectedIndex = -1

Pesquisa de texto

As caixas de combinação suportam automaticamente a pesquisa dentro das suas coleções. À medida que os usuários digitam caracteres em um teclado físico enquanto se concentram em uma caixa de combinação aberta ou fechada, os candidatos que correspondem à cadeia de caracteres do usuário são exibidos. Essa funcionalidade é especialmente útil ao navegar em uma longa lista. Por exemplo, ao interagir com uma lista suspensa contendo uma lista de estados, os usuários podem pressionar a tecla "w" para exibir "Washington" para uma seleção rápida. A pesquisa de texto não diferencia maiúsculas de minúsculas.

Você pode definir a propriedade IsTextSearchEnabled como false para desabilitar essa funcionalidade.

Tornar uma caixa de combinação editável

Por padrão, uma caixa de combinação permite que o usuário selecione a partir de uma lista predefinida de opções. No entanto, há casos em que a lista contém apenas um subconjunto de valores válidos, e o usuário deve ser capaz de inserir outros valores que não estão listados. Para suportar isso, você pode tornar a caixa de combinação editável.

Para tornar uma caixa de combinação editável, defina a propriedade IsEditable como true. Em seguida, manipule o evento TextSubmitted para trabalhar com o valor inserido pelo usuário.

Por padrão, o valor SelectedItem é atualizado quando o usuário confirma texto personalizado. Você pode substituir este comportamento definindo Handled como true nos argumentos do evento TextSubmitted. Quando o evento é marcado como manipulado, a caixa de combinação não realizará mais nenhuma ação após o evento e permanecerá no estado de edição. SelectedItem não será atualizado.

Este exemplo mostra uma caixa de combinação editável simples. A lista contém cadeias de caracteres simples, e qualquer valor inserido pelo usuário é usado como inserido.

Um seletor de "nomes usados recentemente" permite que o usuário insira cadeias de caracteres personalizadas. A lista 'RecentlyUsedNames' contém alguns valores que o usuário pode escolher, mas o usuário também pode adicionar um novo valor personalizado. A propriedade 'CurrentName' representa o nome inserido no momento.

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

Texto enviado

Você pode lidar com o evento TextSubmitted para trabalhar com o valor inserido pelo usuário. No manipulador de eventos, você normalmente validará se o valor inserido pelo usuário é válido e, em seguida, usará o valor em seu aplicativo. Dependendo da situação, poderás também adicionar o valor à lista de opções da caixa de combo para uso futuro.

O evento TextSubmitted ocorre quando estas condições são atendidas:

• A propriedade IsEditable é verdadeira
• O usuário insere texto que não corresponde a uma entrada existente na lista de caixas de combinação
• O utilizador pressiona Enter ou afasta o foco da caixa de combinação.

O evento TextSubmitted não ocorre se o utilizador inserir texto e, em seguida, navegar para cima ou para baixo na lista.

Exemplo - Validar entrada e usar localmente

Neste exemplo, um seletor de tamanho de fonte contém um conjunto de valores correspondentes à rampa de tamanho de fonte, mas o usuário pode inserir tamanhos de fonte que não estão na lista.

Quando o usuário adiciona um valor que não está na lista, o tamanho da fonte é atualizado, mas o valor não é adicionado à lista de tamanhos de fonte.

Se o valor recém-inserido não for válido, use o SelectedValue para reverter a propriedade Text para o último valor válido.

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

Exemplo - Validar entrada e adicionar à lista

Aqui, um "seletor de cores favorito" contém as cores favoritas mais comuns (Vermelho, Azul, Verde, Laranja), mas o usuário pode inserir uma cor favorita que não está na lista. Quando o usuário adiciona uma cor válida (como rosa), a cor recém-inserida é adicionada à lista e definida como a "cor favorita" ativa.

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

UWP e WinUI 2

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

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
• Diretrizes para verificação ortográfica
• Classe TextBox
• Classe PasswordBox
• Propriedade String.Length