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 o usuário pode selecionar. Uma caixa de combinação começa em um estado compacto e se expande para mostrar uma lista de itens selecionáveis. Uma caixa de listagem é semelhante a uma caixa de combinação, mas não é recolhí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 há nenhum item selecionado. Quando o usuário expande a caixa de combinação, ela exibe a lista de itens selecionáveis.
Esse é o controle correto?
- Use um controle de lista suspensa para permitir aos usuários selecionar um ou mais valores de um conjunto de itens que podem ser representados adequadamente com linhas de texto únicas.
- Use um modo de exibição de lista ou de 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 a possibilidade de usar botões de opção (se somente um item puder ser selecionado) ou caixas de seleção (se vários itens puderem ser selecionados).
- Use a 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 em grande parte das situações, mostrar todos os itens usando uma 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.
Exemplos
Uma caixa de combinação no estado compacto pode mostrar um cabeçalho.
Embora caixas de combinação se expandam para dar suporte a tamanhos maiores de cadeia de caracteres, evite cadeias de caracteres excessivamente longas que são difíceis de ler.
Se a coleção em uma caixa de combinação for grande o suficiente, será exibida uma barra de rolagem para acomodá-la. Agrupe itens logicamente na lista.
Recomendações
- 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 opções relacionadas e coloque as opções mais comuns na parte superior. Classifique os nomes em ordem alfabética, os números em ordem numérica e as 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. Caixas de listagem são semelhantes a listas suspensas, exceto que as caixas de listagem ficam sempre abertas: não há estado compacto (não expandido) para uma caixa de listagem. Pode-se fazer a rolagem pelos itens em uma lista se não houver espaço para mostrar tudo.
Uma caixa de listagem é o controle certo?
- Uma caixa de listagem pode ser útil quando itens da lista são importantes o suficiente para serem exibidos em 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 todo o conjunto de alternativas em uma escolha importante. Por outro lado, uma lista suspensa inicialmente atrai a atenção do usuário para o item selecionado.
- Evite usar uma caixa de listagem se:
- Houver um número muito pequeno de itens para a lista. Uma caixa de listagem que tem sempre as mesmas duas opções pode ser melhor apresentada como botões de opção. Considere também a possibilidade de usar botões de opção quando há três ou quatro itens estáticos na lista.
- A caixa de listagem é de seleção única e sempre tem as mesmas duas opções em que uma pode ser implícita como não a outra, como "ativado" e "desativado". Use uma única caixa de marcar ou um botão de alternância.
- Há um número muito grande de itens. Exibição de grade e exibição de lista são escolhas melhores para listas longas. Para listas muito longas de dados agrupados, prefere-se a aplicação de zoom semântico.
- Os itens são valores numéricos contíguos. Se esse for o caso, considere usar um controle deslizante.
- Os itens de seleção são de importância secundária no fluxo de seu aplicativo, ou a opção padrão é recomendada para a maioria dos usuários na maioria das situações. Utilize uma lista suspensa em vez disso.
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 de modo que a lista de itens presente nela não precise de rolagem nem de aplicação de movimento panorâmico.
- Verifique se está claro o propósito da caixa de listagem e quais itens estão selecionados atualmente.
- Reserve efeitos visuais e animações para feedback referente a 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 elementos visuais, você poderá personalizar o tamanho. Se um item contém diversas linhas de texto ou imagens, utilize um modo de exibição de grade ou de lista em vez disso.
- Use fonte padrão, a menos que as diretrizes da marca indiquem o contrário.
- Não utilize uma caixa de listagem para executar comandos ou exibir ou ocultar dinamicamente outros controles.
UWP e WinUI 2
Importante
As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência da API da UWP para obter informações e exemplos específicos da plataforma.
Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.
As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .
- Classe UWP APIs:ComboBox, propriedade IsEditable, propriedade Text, evento TextSubmitted, classe ListBox
- Abra o aplicativo Galeria do WinUI 2 e consulte o ComboBox em ação. Os aplicativos da Galeria do WinUI 2 incluem exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 2. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub.
A Biblioteca de Interface do Usuário do Windows 2.2 ou posterior inclui um novo modelo para esse controle que usa cantos arredondados. Para obter mais informações, confira Raio de canto.
Criar uma caixa de combinação
- APIs importantes: classe ComboBox, propriedade IsEditable, propriedade Text, evento TextSubmitted, classe ListBox
O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub
Popule a caixa de combinação adicionando objetos diretamente à coleção Items ou associando a propriedade ItemsSource a uma fonte de dados. Itens adicionados a ComboBox são encapsulados em contêineres ComboBoxItem.
Esta é 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 associaçã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 item
Assim como ListView e GridView, ComboBox deriva de Selector, portanto, você pode obter a seleção do usuário da mesma maneira padrão.
Você pode obter ou definir o item selecionado de uma caixa de combinação usando a propriedade SelectedItem e pode 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 do item selecionado obter o valor.
Dica
Se você definir SelectedItem ou SelectedIndex para indicar a seleção padrão, ocorrerá uma exceção se a propriedade for definida antes que a coleção de Itens da caixa de combinação seja populada. A menos que você defina seus Itens em XAML, é melhor manipular o evento Loaded da caixa de combinação e definir SelectedItem ou SelectedIndex no manipulador de eventos Loaded.
Você pode associar a essas propriedades em XAML ou manipular o evento SelectionChanged para responder a alterações de seleção.
No código do manipulador de eventos, você pode o item selecionado na propriedade SelectionChangedEventArgs.AddedItems. Você poderá obter o item selecionado anteriormente (se houver) na propriedade SelectionChangedEventArgs.RemovedItems. As coleções AddedItems e RemovedItems contêm, cada uma, apenas um item porque a caixa de combinação não dá suporte à seleção múltipla.
Este exemplo mostra como manipular o evento SelectionChanged e como associar 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 navegação com 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 da caixa de combinação aberta com as teclas de direção do teclado.
Para fazer uma caixa de combinação com “atualizações ao vivo” enquanto o usuário está navegando na lista aberta usando as teclas de seta (como um menu suspenso de seleção de fonte), defina SelectionChangedTrigger como Always. Isso faz com que o evento SelectionChanged ocorra quando o foco mudar 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 dar suporte a caixas de combinação editáveis.
Antes do SDK 17763, o valor da propriedade SelectedItem (e, portanto, SelectedValue e SelectedIndex) precisava estar na coleção de Itens da caixa de combinação. Usando o exemplo anterior, definir colorComboBox.SelectedItem = "Pink" resulta em:
- SelectedItem = null
- SelectedValue = null
- SelectedIndex = -1
No SDK 17763 e posteriores, o valor da propriedade SelectedItem (e, portanto, SelectedValue e SelectedIndex) não precisa estar na coleção de Itens da caixa de combinação. Usando o exemplo anterior, definir colorComboBox.SelectedItem = "Pink" resulta em:
- SelectedItem = Pink
- SelectedValue = Pink
- SelectedIndex = -1
Pesquisa de texto
As caixas de combinação suportam automaticamente pesquisas dentro de suas coleções. Como os usuários digitam caracteres em um teclado físico enquanto enfocam uma caixa de combinação aberta ou fechada, os candidatos que correspondem à cadeia do usuário são inseridos na exibição. Essa funcionalidade é especialmente útil quando estiver navegando uma longa lista. Por exemplo, quando interage com uma lista suspensa contendo uma lista de estados, os usuários podem pressionar a tecla "w" para trazer "Washington" até a exibição para que haja 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
Importante
Este recurso requer o Windows 10, versão 1809 (SDK 17763) ou posterior.
Por padrão, uma caixa de combinação permite que o usuário selecione em 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 dar suporte a 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 de SelectedItem é atualizado quando o usuário confirma texto personalizado. Você pode substituir esse comportamento definindo Handled como true nos argumentos do evento TextSubmitted. Quando o evento for marcado como manipulado, a caixa de combinação não executará 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 digitado.
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 também é possível adicionar um novo valor personalizado. A propriedade 'CurrentName' representa o nome digitado no momento.
<ComboBox IsEditable="true"
ItemsSource="{x:Bind RecentlyUsedNames}"
SelectedItem="{x:Bind CurrentName, Mode=TwoWay}"/>
Texto enviado
Você pode manipular o evento TextSubmitted para trabalhar com o valor inserido pelo usuário. No caso de manipulador de eventos, normalmente você validará que o valor inserido pelo usuário é válido e, em seguida, usará o valor em seu aplicativo. Dependendo da situação, você também pode adicionar o valor à lista de opções da caixa de combinação para uso futuro.
O evento TextSubmitted ocorre quando essas condições são atendidas:
- A propriedade IsEditable é true
- O usuário insere texto que não corresponde a uma entrada existente na lista da caixa de combinação
- O usuário pressiona Enter ou tira o foco da caixa de combinação.
O evento TextSubmitted não ocorrerá se o usuário inserir o texto e, em seguida, navegar para cima ou para baixo na lista.
Exemplo – Validar a entrada e usar localmente
Neste exemplo, um seletor de tamanho da fonte contém um conjunto de valores correspondentes ao crescimento do tamanho da 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 inserido recentemente não for válido, use SelectedValue para reverter a propriedade Text para o último valor válido conhecido.
<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 a entrada e adicionar à lista
Aqui, um "seletor de cor favorita" contém as cores favoritas mais comuns (vermelho, azul, verde e 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 "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.
}
Obter o código de exemplo
- Exemplo da Galeria do WinUI – confira todos os controles XAML em um formato interativo.
Artigos relacionados
Windows developer
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de