Caixas de seleção

Artigo
2025-03-20

Uma caixa de seleção é usada para selecionar ou cancelar a seleção de itens de ação. Ele pode ser usado para um único item ou para uma lista de vários itens que um usuário pode escolher. O controle tem três estados de seleção: não selecionado, selecionado e indeterminado. Use o estado indeterminado quando uma coleção de subopções tiver estados não selecionados e selecionados.

Exemplo de estados de caixa de seleção

Será este o controlo correto?

Use uma única caixa de seleção para uma opção binária sim/não, como com um cenário de login "Lembrar de mim?" ou com um contrato de termos de serviço.

Uma única caixa de seleção usada para uma escolha individual

Para uma escolha binária, a principal diferença entre uma caixa de seleção e um interruptor é que a caixa de seleção é para status e o interruptor é para ação. Você pode atrasar a realização de uma interação de caixa de seleção (como parte de um envio de formulário, por exemplo), enquanto deve realizar imediatamente uma interação de interruptor. Além disso, apenas as caixas de seleção permitem a seleção múltipla.

Use várias caixas de seleção para cenários de seleção múltipla nos quais um usuário escolhe um ou mais itens de um grupo de opções que não são mutuamente exclusivas.

Crie um grupo de caixas de seleção quando os usuários puderem selecionar qualquer combinação de opções.

Seleção de várias opções com caixas de seleção

Quando as opções podem ser agrupadas, você pode usar uma caixa de seleção indeterminada para representar todo o grupo. Use o estado indeterminado da caixa de seleção quando um usuário seleciona alguns, mas não todos, subitens no grupo.

Caixas de seleção usadas para mostrar uma escolha mista

Tanto caixa de seleção quanto botão de opção controles permitem que o usuário selecione a partir de uma lista de opções. As caixas de seleção permitem que o usuário selecione uma combinação de opções. Por contraste, os botões de opção permitem que o utilizador faça uma única escolha entre opções mutuamente exclusivas. Quando houver mais de uma opção, mas apenas uma puder ser selecionada, use um botão de rádio.

Recomendações

Verifique se a finalidade e o estado atual da caixa de verificação estão claros.
Limite o conteúdo de texto da caixa de seleção a não mais do que duas linhas.
Escreva o rótulo da caixa de seleção como uma declaração em que a marca de seleção se torna verdadeira e a ausência de uma marca de seleção se torna falsa.
Use a fonte padrão, a menos que as diretrizes da sua marca digam para usar outra.
Se o conteúdo do texto for dinâmico, considere como o controle será redimensionado e o que acontecerá com os elementos visuais ao seu redor.
Se houver duas ou mais opções mutuamente exclusivas, considere usar botões rádio.
Não coloque dois grupos de caixas de seleção um ao lado do outro. Use rótulos de grupo para separar os grupos.
Não use uma caixa de seleção como um controle de ligar/desligar ou para executar um comando; em vez disso, use um interruptor de ligar/desligar .
Não use uma caixa de seleção para exibir outros controles, como uma caixa de diálogo.
Use o estado indeterminado para indicar que uma opção está definida para algumas, mas não todas, subopções.
Ao usar o estado indeterminado, use caixas de seleção subordinadas para mostrar quais opções estão selecionadas e quais não estão. Projete a interface do usuário para que o usuário possa ver as subopções.
Não use o estado indeterminado para representar um terceiro estado. O estado indeterminado é usado para indicar que uma opção está definida para algumas, mas não todas, subescolhas. Portanto, não permita que os usuários definam um estado indeterminado diretamente. Para obter um exemplo do que não fazer, esta caixa de seleção usa o estado indeterminado para indicar picância média:

Em vez disso, use um conjunto de botões de rádio que tenha três opções.

Criar uma caixa de seleção

APIs importantes: classe CheckBox, evento Checked, propriedade IsChecked, propriedade Content

Abra o aplicativo WinUI 3 Gallery e veja a CheckBox em açã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

Criar uma caixa de seleção simples

Para atribuir um rótulo à caixa de seleção, defina a propriedade Content. O rótulo é exibido ao lado da caixa de seleção.

Esse XAML cria uma única caixa de seleção que é usada para concordar com os termos de serviço antes que um formulário possa ser enviado.

<CheckBox x:Name="termsOfServiceCheckBox"
          Content="I agree to the terms of service."/>

Aqui está a mesma caixa de seleção criada no código.

CheckBox termsOfServiceCheckBox = new CheckBox();
termsOfServiceCheckBox.Content = "I agree to the terms of service.";

Vincular a IsChecked

Utilize a propriedade IsChecked para determinar se a caixa de seleção está marcada ou desmarcada. Você pode vincular o valor da propriedade IsChecked a outro valor binário. No entanto, como IsChecked é um valor booleano anulável, você deve usar um conversor de cast ou value para vinculá-lo a uma propriedade booleana. Isso depende do tipo de vinculação real que você está usando e você encontrará exemplos abaixo para cada tipo possível.

Neste exemplo, a propriedade IsChecked da caixa de seleção para concordar com os termos de serviço está vinculada à propriedade IsEnabled de um botão Enviar. O botão Enviar só será ativado se os termos de serviço forem acordados.

Usando x:Bind

Observação

Apenas mostramos o código relevante aqui. Para obter mais informações sobre vinculação de dados, consulte Visão geral da vinculação de dados. Informações específicas de {x:Bind} (como conversão) são detalhadas na extensão de marcação {x:Bind}.

<StackPanel Grid.Column="2" Margin="40">
    <CheckBox x:Name="termsOfServiceCheckBox" Content="I agree to the terms of service."/>
    <Button Content="Submit"
            IsEnabled="{x:Bind (x:Boolean)termsOfServiceCheckBox.IsChecked, Mode=OneWay}"/>
</StackPanel>

Se a caixa de seleção também puder estar no estado indeterminado, usaremos a propriedade FallbackValue da ligação (binding) para especificar o valor booleano que representa esse estado. Nesse caso, não queremos ter o botão Enviar habilitado também:

<Button Content="Submit"
        IsEnabled="{x:Bind (x:Boolean)termsOfServiceCheckBox.IsChecked, Mode=OneWay, FallbackValue=False}"/>

Usando x:Bind ou Binding

Observação

Apenas mostramos o código relevante aqui usando {x:Bind}. No exemplo {Binding}, substituiríamos {x:Bind} por {Binding}. Para obter mais informações sobre vinculação de dados, conversores de valor e diferenças entre as extensões de marcação {x:Bind} e {Binding}, consulte Visão geral da vinculação de dados.

...
<Page.Resources>
    <local:NullableBooleanToBooleanConverter x:Key="NullableBooleanToBooleanConverter"/>
</Page.Resources>

...

<StackPanel Grid.Column="2" Margin="40">
    <CheckBox x:Name="termsOfServiceCheckBox" Content="I agree to the terms of service."/>
    <Button Content="Submit"
            IsEnabled="{x:Bind termsOfServiceCheckBox.IsChecked,
                        Converter={StaticResource NullableBooleanToBooleanConverter}, Mode=OneWay}"/>
</StackPanel>

public class NullableBooleanToBooleanConverter : IValueConverter
{
    public object Convert(object value, Type targetType, object parameter, string language)
    {
        if (value is bool?)
        {
            return (bool)value;
        }
        return false;
    }

    public object ConvertBack(object value, Type targetType, object parameter, string language)
    {
        if (value is bool)
            return (bool)value;
        return false;
    }
}

Manipular eventos de Clique e Selecionado

Para executar uma ação quando o estado da caixa de seleção for alterado, você pode manipular o evento Clique ou os eventos Marcado e Não Marcado.

O evento Click ocorre sempre que o estado verificado é alterado. Se você manipular o evento Click, use a propriedade IsChecked para determinar o estado da caixa de seleção.

Os eventos Checked e Unchecked ocorrem de forma independente. Se você manipular esses eventos, deverá manipular ambos para responder às alterações de estado na caixa de seleção.

Nos exemplos a seguir, mostramos a manipulação do evento Click e os eventos Checked e Unchecked.

Várias caixas de seleção podem compartilhar o mesmo manipulador de eventos. Este exemplo cria quatro caixas de seleção para selecionar coberturas de pizza. As quatro caixas de seleção partilham o mesmo controlador de eventos Click para atualizar a lista de coberturas selecionadas.

<StackPanel Margin="40">
    <TextBlock Text="Pizza Toppings"/>
    <CheckBox Content="Pepperoni" x:Name="pepperoniCheckbox"
              Click="toppingsCheckbox_Click"/>
    <CheckBox Content="Beef" x:Name="beefCheckbox"
              Click="toppingsCheckbox_Click"/>
    <CheckBox Content="Mushrooms" x:Name="mushroomsCheckbox"
              Click="toppingsCheckbox_Click"/>
    <CheckBox Content="Onions" x:Name="onionsCheckbox"
              Click="toppingsCheckbox_Click"/>

    <!-- Display the selected toppings. -->
    <TextBlock Text="Toppings selected:"/>
    <TextBlock x:Name="toppingsList"/>
</StackPanel>

Aqui está o manipulador de eventos para o evento Click. Sempre que uma caixa de seleção é clicada, o sistema examina as caixas de seleção para ver quais estão marcadas e atualiza a lista de toppings selecionados.

private void toppingsCheckbox_Click(object sender, RoutedEventArgs e)
{
    string selectedToppingsText = string.Empty;
    CheckBox[] checkboxes = new CheckBox[] { pepperoniCheckbox, beefCheckbox,
                                             mushroomsCheckbox, onionsCheckbox };
    foreach (CheckBox c in checkboxes)
    {
        if (c.IsChecked == true)
        {
            if (selectedToppingsText.Length > 1)
            {
                selectedToppingsText += ", ";
            }
            selectedToppingsText += c.Content;
        }
    }
    toppingsList.Text = selectedToppingsText;
}

Usar o estado indeterminado

O controle CheckBox herda de ToggleButton e pode ter três estados:

Estado	Propriedade	Valor
verificada	EstáMarcado	verdadeiro
não verificado	Está Marcado	falso
indeterminado	EstáSelecionado	nulo

Para que a caixa de seleção relate o estado indeterminado, você deve definir a propriedade IsThreeState como true.

No exemplo a seguir, a caixa de seleção "Selecionar tudo" tem sua propriedade IsThreeState definida como true. A caixa de seleção "Selecionar tudo" será marcada se todos os elementos filho estiverem marcados, desmarcada se todos os elementos filho estiverem desmarcados e indeterminada caso contrário.

<StackPanel>
    <CheckBox x:Name="OptionsAllCheckBox" Content="Select all" IsThreeState="True"
              Checked="SelectAll_Checked" Unchecked="SelectAll_Unchecked"
              Indeterminate="SelectAll_Indeterminate"/>
    <CheckBox x:Name="Option1CheckBox" Content="Option 1" Margin="24,0,0,0"
              Checked="Option_Checked" Unchecked="Option_Unchecked" />
    <CheckBox x:Name="Option2CheckBox" Content="Option 2" Margin="24,0,0,0"
              Checked="Option_Checked" Unchecked="Option_Unchecked" IsChecked="True"/>
    <CheckBox x:Name="Option3CheckBox" Content="Option 3" Margin="24,0,0,0"
              Checked="Option_Checked" Unchecked="Option_Unchecked" />
</StackPanel>

private void Option_Checked(object sender, RoutedEventArgs e)
{
    SetCheckedState();
}

private void Option_Unchecked(object sender, RoutedEventArgs e)
{
    SetCheckedState();
}

private void SelectAll_Checked(object sender, RoutedEventArgs e)
{
    Option1CheckBox.IsChecked = Option2CheckBox.IsChecked = Option3CheckBox.IsChecked = true;
}

private void SelectAll_Unchecked(object sender, RoutedEventArgs e)
{
    Option1CheckBox.IsChecked = Option2CheckBox.IsChecked = Option3CheckBox.IsChecked = false;
}

private void SelectAll_Indeterminate(object sender, RoutedEventArgs e)
{
    // If the SelectAll box is checked (all options are selected),
    // clicking the box will change it to its indeterminate state.
    // Instead, we want to uncheck all the boxes,
    // so we do this programmatically. The indeterminate state should
    // only be set programmatically, not by the user.

    if (Option1CheckBox.IsChecked == true &&
        Option2CheckBox.IsChecked == true &&
        Option3CheckBox.IsChecked == true)
    {
        // This will cause SelectAll_Unchecked to be executed, so
        // we don't need to uncheck the other boxes here.
        OptionsAllCheckBox.IsChecked = false;
    }
}

private void SetCheckedState()
{
    // Controls are null the first time this is called, so we just
    // need to perform a null check on any one of the controls.
    if (Option1CheckBox != null)
    {
        if (Option1CheckBox.IsChecked == true &&
            Option2CheckBox.IsChecked == true &&
            Option3CheckBox.IsChecked == true)
        {
            OptionsAllCheckBox.IsChecked = true;
        }
        else if (Option1CheckBox.IsChecked == false &&
            Option2CheckBox.IsChecked == false &&
            Option3CheckBox.IsChecked == false)
        {
            OptionsAllCheckBox.IsChecked = false;
        }
        else
        {
            // Set third state (indeterminate) by setting IsChecked to null.
            OptionsAllCheckBox.IsChecked = null;
        }
    }
}

UWP e WinUI 2

Importante

As informações e os exemplos neste artigo são otimizados para aplicativos que usam o SDK de Aplicativo Windows e WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam WinUI 2. Consulte a referência da API UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações que você precisa para usar o controle em um aplicativo UWP ou WinUI 2.

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

APIs UWP:classe CheckBox, evento Checked, propriedade IsChecked, propriedade Content
Abra o aplicativo WinUI 2 Gallery e veja a CheckBox em ação. O aplicativo WinUI 2 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 2. Obtenha o aplicativo no Microsoft Store ou obtenha o código-fonte em GitHub.

Recomendamos usar a WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controlos. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Para obter mais informações, consulte Raio de canto.

Partilhar via