Guia de início rápido: adicionando controles de caixa de seleção (HTML)

Artigo
03/04/2016

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente ]

Saiba como criar controles checkbox. Use caixas de seleção para apresentar aos usuários uma opção binária, uma ou mais opções que não são mutuamente exclusivas, ou uma opção mista.

Pré-requisitos

Guia de início rápido: adicionando controles HTML e manipulando eventos

Criar uma de caixa de seleção

Para criar uma checkbox, crie um elemento input e defina seu atributo type como "checkbox". Adicione o texto para checkbox após a marca de fechamento do elemento input.

Dica Ao adicionar uma checkbox, coloque-a em um elemento label para aumentar o tamanho da área que responde à interação do usuário. Fazendo isso, fica mais fácil usar a caixa de seleção em dispositivos de toque.

Por padrão, a caixa de seleção fica desmarcada, até que o usuário clique nela. Para fazer com que uma checkbox seja marcada, use o atributo checked. Este exemplo cria quatro controles de caixa de seleção e usa o atributo checked para que o segundo seja marcado.


.controlGroup
{
    margin: 0px 0px 20px 0px;
    padding: 0px;
    border: 0px;
}

.controlGroupName
{
    font:normal normal normal 11pt/15pt "Segoe UI Semilight";
    font-size: 11pt; 
    margin:0px 0px 10px 0px;
    padding:0px;
    border: 0px;
    position:relative;
    vertical-align:top;
    display:block;
}

.verticalStacking input[type="checkbox"]
{
    margin-bottom: 16px;
}

<div style="margin: 20px">
<fieldset class="controlGroup verticalStacking">
    <legend class="controlGroupName">Choose an option:</legend>
    <label>
        <input id="option1" type="checkbox" class="checkboxExample1"  />Option 1
    </label>
    <br />
    <label>
        <input id="option2" type="checkbox" class="checkboxExample1" checked />Option 2
    </label>
    <br />
    <label>
        <input id="option3" type="checkbox" class="checkboxExample1" />Option 3
    </label>
    <br />
    <label>
        <input id="option4" type="checkbox" class="checkboxExample1" />Option 4
    </label>
    </fieldset>
</div>

Quando você executa o código, as opções 1, 3 e 4 estão desmarcadas, mas a opção 2 está marcada.

Quatro caixas de seleção

Determinar se uma caixa de seleção está marcada

A checkbox dá suporte aos mesmo eventos que os outros elementos input, incluindo o evento click. Porém, a checkbox serve para informação de status e geralmente não dispara uma ação (exceto no caso de uma caixa de seleção indeterminada, sobre a qual falaremos na próxima seção). Em vez de manipular o evento click da caixa de seleção e realizar imediatamente uma ação baseada no estado checked da caixa de seleção, você geralmente lê o estado checkbox quando o usuário clica em algum tipo de botão "Enviar" para confirmar uma série de opções. (Se você quiser realizar uma ação, use um controle ToggleSwitch em vez disso.)

Para determinar se uma caixa de seleção está marcada, use sua propriedade checked. Este exemplo cria um button que exibe os valores checked dos controles da caixa de seleção criada no exemplo anterior.

function evaluateCheckboxState(eventInfo) {
    var outputDiv = document.getElementById("checkedStateOutput");
    var output = "<ul>";
    WinJS.Utilities.query(".checkboxExample1").forEach(function (checkbox) {
        output += "<li>" + checkbox.id + " checked: " + checkbox.checked + "</li>"; 
    }); 
    outputDiv.innerHTML = output + "</ul>"; 

}

WinJS.Namespace.define("CheckboxExamples",
    { evaluateCheckboxState: evaluateCheckboxState });

Veja como ela parece quando você executa o código e clica no botão:

Quatro caixas de seleção

Criar uma caixa de seleção indeterminada

Quando uma opção se aplica a mais de um objeto, você pode usar uma caixa de seleção para indicar se ela se aplica a todos, a alguns ou a nenhum desses objetos. Quando a opção se aplica a alguns, mas não a todos os objetos, use o estado indeterminate da caixa de seleção para representar uma escolha mista.

Você pode definir a propriedade indeterminate apenas em JavaScript—não há atributo "indeterminate" que possa ser definido em HTML.

Observação A alteração da propriedade indeterminate da caixa de seleção não altera automaticamente seu valor checked.

Este exemplo cria uma caixa de seleção "Selecionar Tudo" que marca ou desmarca um conjunto de controles filho da caixa de seleção (opções 1 a 4).

<fieldset class="controlGroup verticalStacking">
    <legend class="controlGroupName">Choose an option:</legend>

    <label>
        <input type="checkbox" id="selectAll" onclick="CheckboxExamples.checkAll(event)" />Select all
    </label>
    <div style="margin-left: 29px" onclick="CheckboxExamples.updateCheckboxes(event)">
        <label>
            <input id="Checkbox1" type="checkbox" class="checkboxExample2"  />Option 1
        </label>
        <br />
        <label>
            <input id="Checkbox2" type="checkbox" class="checkboxExample2" checked />Option 2
        </label>
        <br />
        <label>
            <input id="Checkbox3" type="checkbox" class="checkboxExample2" />Option 3
        </label>
        <br />
        <label>
            <input id="Checkbox4" type="checkbox" class="checkboxExample2" />Option 4
        </label>
    </div>

</fieldset>

Veja a aparência dos controles da caixa de seleção:

Uma caixa de seleção no estado indeterminado

O exemplo manipula o evento click para a caixa de seleção selectAll, para que o clique dispare a função checkAll.

<input type="checkbox" id="selectAll" onclick="CheckboxExamples.checkAll(event)" />Select all

A função checkAll marca ou desmarca os demais controles da caixa de seleção quando você marca ou desmarca a caixa de seleção selectAll.

function checkAll(eventInfo) {

    var options = document.getElementsByClassName("checkboxExample2");
    for (var i = 0; i < options.length; i++) {
        options[i].checked = event.srcElement.checked;
    }
}

A função updateCheckboxes é chamada quando um dos controles da caixa de seleção filho está marcado.

<div style="margin-left: 29px" onclick="CheckboxExamples.updateCheckboxes(event)">

Ela identifica o estado marcado de cada caixa de seleção e atualiza a caixa de seleção selectAll.

Se cada caixa de seleção filho for marcada, o estado indeterminate da caixa de seleção selectAll será definido como false e seu valor checked será definido como true.
Se cada caixa de seleção filho for desmarcada, o estado indeterminate da caixa de seleção selectAll será definido como false e seu valor checked será definido como false.
Se alguns controles da caixa de seleção filho forem desmarcados, o estado indeterminate da caixa de seleção selectAll será definido como true e seu valor checked será definido como false.

function updateCheckboxes(eventInfo) {
    var options = document.getElementsByClassName("checkboxExample2");
    var selectedCount = 0;
    for (var i = 0; i < options.length; i++) {
        if (options[i].checked) {
            selectedCount++;
        }
    }

    // Update the selectAll checkbox
    // to reflect the state of the child checkboxes.
    var selectAll = document.getElementById("selectAll"); 
    if (options.length === selectedCount) {
        selectAll.indeterminate = false;
        selectAll.checked = true;
    } else if (0 === selectedCount) {
        selectAll.indeterminate = false;
        selectAll.checked = false;
    } else {
        selectAll.indeterminate = true;
        //selectAll.checked = false;
    }
}

A próxima parte do exemplo usa WinJS.Namespace.define para tornar checkAll e updateCheckboxes públicos.

WinJS.Namespace.define("CheckboxExamples",
    {
        checkAll: checkAll,
        updateCheckboxes: updateCheckboxes
    });

Há mais uma coisa a ser feita aqui. A segunda opção aparece no estado checked:

<label>
    <input id="Checkbox2" type="checkbox" class="checkboxExample2" checked />Option 2
</label>

A caixa de seleção selectAll aparece no estado "desmarcado" e o método updateCheckboxes não é chamado até o usuário clicar em uma caixa de seleção. Sendo assim, quando o código do exemplo é executado, a caixa de seleção selectAll é desmarcada quando ela deveria estar no estado indeterminado:

A caixa de seleção Selecionar Tudo deve estar no estado indeterminado

Para corrigir o problema, adicione uma chamada para updateCheckboxes quando a página for carregada.

Se o seu código estiver em um PageControl, use o método ready para chamar updateCheckboxes.
Se o seu código estiver no arquivo default.js do seu aplicativo, use o manipulador de eventos activated para chamar updateCheckboxes.
Em qualquer um desses casos, você também pode manipular o evento DOMContentLoaded e usar o manipulador para chamar updateCheckboxes.

Este exemplo usa um PageControl, então ele chama updateCheckboxes do método ready.

WinJS.UI.Pages.define("/pages/checkbox/checkbox.html", {
    // This function is called whenever a user navigates to this page. It
    // populates the page elements with the app's data.
    ready: function (element, options) {
        // TODO: Initialize the page here.

        CheckboxExamples.updateCheckboxes(); 
    },

    unload: function () {
        // TODO: Respond to navigations away from this page.
    },

    updateLayout: function (element, viewState, lastViewState) {
        /// <param name="element" domElement="true" />

        // TODO: Respond to changes in viewState.
    }
});

Resumo e próximas etapas

Você aprendeu como criar controles de checkbox, como descobrir seus estados e como usar a propriedade indeterminate para indicar um estado no ínterim.

Agora, veja Como definir o estilo de controles de caixa de seleção.

Tópicos relacionados

Como definir o estilo de controles de caixa de seleção

Diretrizes e lista de verificação de controles de caixa de seleção