Eventos e páginas interativas

Uma página pode esperar que uma pessoa aja. Um evento informa algo que aconteceu, e um ouvinte de evento é a função chamada em resposta. Registrar um ouvinte configura essa resposta; não executa a ação imediatamente.

Adicione a função ao elemento

Selecione um elemento que já exista, escolha o nome exato do evento e passe uma função:

const button = document.querySelector("#like");
let likes = 0;
button.addEventListener("click", function () {
  likes = likes + 1;
  button.textContent = "Likes: " + likes;
});

A seleção, a configuração da variável e o registro são executados quando o script é executado. Cada clique posterior executa o corpo da função. Após três cliques, o botão mostra “Likes: 3”. Manter likes fora da função preserva o total entre cliques; colocar let likes = 0 dentro dela o reiniciaria a cada vez.

Passe uma referência à função, como showMenu, sem parênteses. Em button.addEventListener("click", showMenu()), o JavaScript chama showMenu imediatamente e passa seu valor de retorno como ouvinte. Para fornecer um argumento mais tarde, envolva a chamada: button.addEventListener("click", () => showMenu("main"));.

Escolha um evento que realmente ocorra

Nomes são cadeias de caracteres que diferenciam maiúsculas de minúsculas e não têm o prefixo “on”. Use "click", não "Click" ou "onclick". Um nome inventado é aceito sem erro, mas o navegador não o emitirá para um clique. Famílias comuns incluem eventos de ponteiro, como pointerdown e pointerup, eventos de teclado, como keydown, eventos de formulário, como input e submit, e eventos de foco, como focusin. DOMContentLoaded tem sua própria grafia exata de maiúsculas e minúsculas.

Configure o elemento certo no momento certo

Um script no cabeçalho pode ser executado antes de um botão existir. Nesse caso, a seleção retorna null, e chamar addEventListener nele lança um erro. Carregue um script externo com defer, coloque-o após a marcação ou registre a configuração no evento DOMContentLoaded do documento. Um elemento criado posteriormente precisa de configuração após a criação ou de um ouvinte em um ancestral.

querySelectorAll retorna uma NodeList, não um único alvo de evento. Registre ouvintes em seus elementos:

document.querySelectorAll(".tab").forEach((tab) => {
  tab.addEventListener("click", selectTab);
});

Permita que ouvintes coexistam

Ouvintes com a mesma configuração de captura são executados na ordem de registro. No alvo do evento, ouvintes de captura são executados antes dos ouvintes que não usam captura. Adicionar novamente o mesmo objeto de função com o mesmo tipo e configuração de captura não adiciona uma segunda cópia.

O navegador passa um objeto de evento ao seu ouvinte. Suas propriedades explicam o evento que acionou essa chamada específica. Nomeie o parâmetro event ou e; a escolha é sua.

button.addEventListener("click", (event) => {
  console.log(event.type);
  console.log(event.currentTarget);
});

Isso registra "click" e o botão durante a chamada do ouvinte. Registrar o objeto inteiro pode ajudar você a descobrir suas outras propriedades.

Distinga a origem do ouvinte

Imagine um botão que contém uma imagem:

<button id="save" data-id="7">
  <img src="disk.svg" alt=""> Save
</button>

Clicar no texto “Save” também torna o botão o alvo. O texto é parte do botão; ele não se torna um elemento alvo separado.

Essa diferença importa ao ler dados. A imagem não tem o data-id do botão, então event.target.dataset.id é undefined em um clique na imagem. Um ouvinte registrado diretamente no botão pode ler event.currentTarget.dataset.id. Um ouvinte em um contêiner maior pode encontrar o botão desejado com event.target.closest("button") e verificar se há uma correspondência.

Leia os detalhes deste evento

Todo evento tem um type, um target e um currentTarget. O booleano bubbles informa se ele volta a subir pelos ancestrais. cancelable informa se o código pode cancelar sua ação padrão, e defaultPrevented registra se esse cancelamento ocorreu. timeStamp registra o momento de criação do evento em milissegundos em relação à origem de tempo da página.

Diferentes famílias de eventos acrescentam detalhes úteis. Um click moderno fornece um PointerEvent, que herda propriedades de eventos de mouse, como clientX, clientY e button. Um KeyboardEvent acrescenta key, code e indicadores de teclas modificadoras. Um ouvinte de input pode usar event.target.value para ler o novo texto do campo.

Para um ouvinte em uma galeria, event.target.tagName pode ser "IMG" quando uma foto é clicada ou "DIV" quando o espaço entre fotos é clicado. Trate o caso efetivamente informado. Não suponha que todo evento dentro de um contêiner veio do mesmo tipo de filho.

Use o valor enquanto o ouvinte é executado

Em um ouvinte definido com uma função comum, this é igual a event.currentTarget. Uma função de seta obtém this do código ao redor; ela não recebe o elemento como this. Usar event.currentTarget funciona com ambos os estilos de função.

Após o disparo, currentTarget é redefinido para null. Um console pode mostrar esse valor posterior quando você expande um evento registrado anteriormente. Registre event.currentTarget diretamente dentro do ouvinte para inspecionar o elemento durante a chamada.

Um ouvinte deve permanecer ativo enquanto seu recurso precisar dele. Para uma interação temporária com o teclado, mantenha a referência à função para que ela possa ser removida quando a interação for encerrada.

Remova a mesma função

function onKey(event) {
  console.log(event.key);
}
document.addEventListener("keydown", onKey);
// When the feature closes:
document.removeEventListener("keydown", onKey);

A remoção compara o tipo de evento, o objeto de função e a configuração de captura. Uma função anônima também pode ser removida quando sua referência é salva, como em const handler = () => save();. Escrever uma nova () => save() na chamada de remoção cria uma função diferente, mesmo que o código pareça idêntico.

Escolha as opções de registro

Um banner de boas-vindas exibido uma única vez pode usar { once: true }. Um recurso com vários ouvintes pode atribuir a eles um único sinal:

const controller = new AbortController();
window.addEventListener("pointermove", moveCursor, {
  signal: controller.signal
});
window.addEventListener("keydown", onKey, {
  signal: controller.signal
});
// Close the feature:
controller.abort();

O cancelamento remove os dois registros. Um controlador cancelado não pode ser redefinido; crie um novo controlador para um novo período de uso. Para remoção com removeEventListener, repita capture: true se ele tiver sido usado no registro. once, signal e passive não fazem parte dos critérios de correspondência para remoção.

Uma chamada a preventDefault() em um ouvinte passivo é ignorada. Os navegadores costumam tornar passivos por padrão certos ouvintes relacionados à rolagem em alvos no nível do documento, incluindo wheel, touchstart e touchmove; use explicitamente { passive: false } nesses casos quando for necessário cancelar.

Evite acumular funções de retorno

Se cada clique em “Iniciar” adicionar um novo ouvinte anônimo ao tabuleiro, iniciar duas vezes fará um clique no tabuleiro executar duas funções de retorno. Registre o ouvinte do tabuleiro uma vez, reutilize o mesmo objeto de função ou cancele o grupo anterior antes de substituí-lo. Funções de retorno once distintas ainda podem se acumular antes de serem executadas.

Desconectar um elemento preserva seus ouvintes. Eles funcionam se o elemento for reinserido, e dispatchEvent() pode alcançá-los enquanto ele estiver desconectado. O elemento pode ser recolhido pelo coletor de lixo quando ele e seus ouvintes não puderem mais ser alcançados. Um ouvinte em window ou document permanece registrado até ser removido explicitamente.

Dispare um evento personalizado

const event = new CustomEvent("cart:add", {
  detail: { id: 42 },
  bubbles: true
});
item.dispatchEvent(event);

Os ouvintes leem event.detail.id. O disparo chama os ouvintes imediatamente, antes de retornar. bubbles: true permite que os ancestrais também o recebam. Um evento enviado com dispatchEvent() tem isTrusted igual a false; eventos disparados pelo navegador podem ser confiáveis mesmo quando causados por uma API como focus().

Um clique dentro de um botão também pode ser recebido pelos ancestrais do botão. Propagação é o percurso do evento pela árvore do documento. Acompanhar esse percurso explica tanto os ouvintes compartilhados úteis quanto as ações adicionais inesperadas.

Acompanhe três fases

1. Captura: o evento percorre o caminho de window para baixo, pelos ancestrais, em direção ao alvo.
2. Alvo: ouvintes são executados no elemento onde o evento começou.
3. Borbulhamento: um evento que borbulha volta a subir pelos ancestrais até window.

A propriedade eventPhase informa 1 para captura, 2 no alvo e 3 para borbulhamento. Um ouvinte registrado sem opções é executado no alvo ou no caminho de borbulhamento. Um ouvinte com { capture: true } é executado no caminho de descida, inclusive no alvo se estiver registrado nele.

Rastreie um clique concreto

<div id="outer">
  <div id="inner">
    <button>Go</button>
  </div>
</div>

Suponha que o botão e cada div tenham ouvintes de clique comuns que registram seus nomes. Clicar em “Go” registra “button”, “inner” e depois “outer”. Clicar em uma área vazia de inner registra “inner” e depois “outer”; o botão não está no caminho desse evento.

Agora adicione um ouvinte de captura a outer. Um clique no botão registra primeiro “outer (capture)”, depois “button”, “inner” e “outer” pelos ouvintes comuns. O ouvinte de captura vê o clique antes dos descendentes. Após outer, o evento pode continuar por body, html, document e window se houver ouvintes registrados nesses elementos.

É um único evento, não um novo clique criado em cada ancestral. target permanece sendo o botão durante todo o percurso. currentTarget muda conforme cada ouvinte é executado. No ouvinte externo, ler target ainda identifica o botão original.

Verifique quais eventos borbulham

A propriedade bubbles do evento informa se ele tem uma fase de borbulhamento. Eventos que não borbulham ainda podem ser observados por um ouvinte de captura em um ancestral. Para tratar mudanças de foco por meio de um ouvinte comum no contêiner, escolha focusin ou focusout.

Explique um erro de ação aninhada

Um cartão de produto abre uma visão de detalhes quando clicado. Seu botão “Remover” exclui o produto. Clicar nesse botão primeiro o exclui, depois alcança o ouvinte do cartão e abre a visão de detalhes. O caminho do evento explica por que ambas as funções de retorno são executadas.

O cartão pode ignorar cliques de remoção com if (event.target.closest(".remove")) return;. Como alternativa, o botão pode interromper a propagação. Filtrar no cartão preserva o evento para outros ancestrais que possam precisar dele.

Um ouvinte pode mudar o que acontece após um evento ou por onde o evento passa. São decisões distintas. Um evento em um link pode continuar borbulhando mesmo depois que a navegação foi cancelada.

Substitua uma ação do navegador

Uma ação padrão é um comportamento fornecido pelo navegador: seguir um link, enviar um formulário, alternar uma caixa de seleção, inserir texto, rolar com a barra de espaço ou mover o foco com Tab. Use preventDefault() quando seu código substituir essa ação:

help.addEventListener("click", (event) => {
  event.preventDefault();
  openHelpPanel();
});

Para um link para /help, isso abre o painel sem navegar. O link ainda oferece seu destino quando o JavaScript não é executado.

Somente eventos canceláveis podem ser cancelados. Inspecione event.cancelable; defaultPrevented registra o cancelamento bem-sucedido. input ocorre após a mudança do valor e não é cancelável. Chamar preventDefault() nele não remove o texto inserido. Um evento beforeinput cancelável é o lugar adequado para interceptar uma edição; cancelar um keydown relevante pode impedir o efeito padrão dessa tecla.

Controle a propagação separadamente

Um link cujo ouvinte apenas interrompe a propagação ainda segue sua URL. Cancelar apenas a navegação ainda permite que um ouvinte de clique no documento receba o evento. Retornar false de uma função de retorno de addEventListener não faz nenhuma das duas coisas. Uma propriedade ou um atributo em linha de tratamento pode cancelar a ação padrão ao retornar false, mas isso ainda não interrompe a propagação.

Mantenha o comportamento compartilhado funcionando

Um ancestral pode fechar um menu ou contar interações. Interromper a propagação oculta o evento desse código. Muitas vezes, o ancestral pode inspecionar target ou defaultPrevented.

Por exemplo, um menu fecha apenas quando um clique ocorre fora tanto do menu quanto de seu controle de abertura:

document.addEventListener("click", (event) => {
  if (!menu.contains(event.target) &&
      !menuButton.contains(event.target)) {
    menu.hidden = true;
  }
});

contains() inclui o próprio elemento e seus descendentes. Verificar o controle de abertura é importante porque o clique que abre o menu também borbulha até o documento. Sem esse segundo teste, o menu recém-aberto fecharia imediatamente.

Cancele apenas uma ação tratada

Em um ouvinte de teclado, verifique a tecla antes de cancelar. Cancelar todas as teclas bloqueia a digitação normal e pode impedir que Tab mova o foco. Em um ouvinte passivo, o cancelamento é ignorado por completo.

A delegação de eventos coloca um ouvinte em um ancestral estável e usa a origem do evento para escolher uma ação. Ela é útil quando uma lista tem muitos itens ou quando o código cria novos itens após a configuração.

Encontre o controle desejado

Um clique que borbulha chega à lista, independentemente de qual descendente foi clicado. Comece por event.target, encontre o controle correspondente mais próximo e descarte cliques não relacionados:

const list = document.querySelector("#todos");
list.addEventListener("click", (event) => {
  const button = event.target.closest(".remove");
  if (!button || !list.contains(button)) return;
  const item = button.closest("li");
  console.log("Removing item " + item.dataset.id);
  item.remove();
});

A lista contém itens como <li data-id="7">Buy milk <button class="remove">Remove</button></li>. O ouvinte pertence à lista, então um novo item com a mesma marcação funciona imediatamente após a inserção.

Acompanhe um clique em um ícone pelo código. O alvo é o ícone, closest(".remove") encontra seu botão, e button.closest("li") encontra o item. Seu data-id identifica o item na mensagem. Por fim, remove() altera a página.

Mantenha as duas verificações

Testar apenas event.target.matches(".remove") perde cliques no ícone porque o próprio ícone não corresponde ao seletor. closest() verifica o alvo e sobe por seus ancestrais. Em um ouvinte delegado, currentTarget é a lista; ele não se torna o botão encontrado.

Encaminhe várias ações

Atributos de dados permitem que um ouvinte de barra de ferramentas escolha entre ações conhecidas:

const actions = { bold: makeBold, italic: makeItalic,
  clear: clearText };
toolbar.addEventListener("click", (event) => {
  const button = event.target.closest("button[data-action]");
  if (!button || !toolbar.contains(button)) return;
  const action = actions[button.dataset.action];
  if (typeof action === "function") action();
});

Um botão com data-action="clear" seleciona clearText. A verificação da função trata uma ação desconhecida sem tentar chamar undefined.

Escolha um evento adequado

A delegação funciona com eventos que borbulham, além de cliques. Um único ouvinte de input no formulário pode passar event.target a uma função de verificação de campo. Para delegar mudanças de foco, use focusin ou focusout; focus e blur comuns não borbulham. Para transições de passagem do ponteiro, use eventos over/out que borbulham quando a delegação for necessária.

Uma chamada a stopPropagation() em um descendente pode impedir que um evento chegue ao contêiner. Quando um ouvinte delegado parecer inativo, verifique o tipo de evento, o alvo, a correspondência com o seletor e se algo abaixo do contêiner interrompeu o percurso.

A entrada do teclado vai para o elemento com foco, disponível como document.activeElement, e depois borbulha. Um ouvinte no documento pode, portanto, receber teclas de campos e de outros controles. Esse alcance torna os atalhos de teclado úteis, mas também significa que eles podem interromper a digitação.

Escolha a propriedade pelo seu significado

Em um teclado AZERTY, a posição identificada como Q em um teclado dos EUA produz key "a" e code "KeyQ". Use key para o significado, como Escape para fechar ou uma letra de atalho. Use code para posições fixas, como teclas de movimento em um jogo. O key da barra de espaço é um único espaço, não "Space".

keydown dispara no pressionamento inicial e pode se repetir enquanto a tecla é mantida pressionada. Chamadas repetidas têm event.repeat === true. keyup dispara quando a tecla é solta. Use keydown em vez do evento obsoleto keypress.

Trate um atalho com precisão

document.addEventListener("keydown", (event) => {
  if ((event.ctrlKey || event.metaKey) &&
      event.key.toLowerCase() === "s") {
    event.preventDefault();
    saveDraft();
  }
});

Isso trata Ctrl+S e Command+S. A conversão para minúsculas permite também "S". O cancelamento substitui a ação Salvar página do navegador apenas para o atalho correspondente. Outros indicadores de teclas modificadoras incluem shiftKey e altKey.

Para um atalho de uma única letra válido para toda a página, ignore contextos de digitação antes de agir:

if (event.target.matches("input, textarea, select") ||
    event.target.isContentEditable) return;
if (event.repeat) return;

A primeira verificação protege a entrada de texto. A segunda faz uma ação ser executada uma vez por pressionamento físico. Não cancele Tab em toda a página; é assim que usuários de teclado avançam.

Ouça o texto depois que ele mudar

Para uma tecla comum que produz um caractere imprimível, a sequência é keydown, beforeinput, input e depois keyup. Ler value em keydown fornece o valor anterior à inserção desse caractere. Use input para uma prévia de texto ou contagem de caracteres. Ele também trata edições como colagem e ditado, que não precisam de um pressionamento de tecla correspondente.

Observe mudanças de foco

focus e blur informam o recebimento e a perda de foco sem borbulhar. focusin e focusout borbulham, então um formulário pode observar seus campos por meio de um único ouvinte. relatedTarget identifica o outro elemento envolvido na mudança ou null quando não há nenhum.

password.addEventListener("focus", () => {
  hint.hidden = false;
});
password.addEventListener("blur", () => {
  hint.hidden = true;
});

A dica fica disponível quando o campo recebe foco, inclusive por Tab. Chamar element.focus() move o foco por código; a próxima entrada de teclado vai para esse elemento.

Uma pessoa pode usar mouse, dedo, caneta ou teclado. Escolha um evento conforme a interação necessária. click expressa ativação; eventos de ponteiro descrevem pressionamento, movimento e liberação.

Mantenha ações disponíveis pelo teclado

Um botão nativo emite click quando ativado com Enter ou a barra de espaço. Um link com foco faz isso com Enter. Associar uma ação apenas a pointerdown ou mousedown deixa de captar essas ativações pelo teclado. Use click para ações como abrir um painel; use pointerdown quando o trabalho precisar começar no pressionamento, como em um arraste.

Um clique com ponteiro ocorre após pressionar e soltar. Quando essas ações ocorrem em elementos diferentes, o clique pode ter como alvo o ancestral comum mais próximo. dblclick ocorre após dois cliques rápidos; event.detail conta cliques rápidos sucessivos. auxclick trata cliques não primários. contextmenu pode vir de um clique secundário, de um toque longo ou de um comando de menu do teclado.

Use uma única família de eventos de ponteiro

pointerdown, pointermove, pointerup e pointercancel abrangem mouse, toque e caneta. pointerType identifica o dispositivo como "mouse", "touch" ou "pen"; pointerId distingue ponteiros ativos, incluindo dois dedos.

Famílias mais antigas de eventos de mouse e toque ainda existem. Os navegadores podem emitir eventos de mouse para compatibilidade após eventos de ponteiro. Registrar tanto pointerdown quanto mousedown para a mesma ação pode, portanto, executá-la duas vezes.

Escolha coordenadas adequadas à tarefa

Quando o documento é rolado 300 px para baixo e um clique ocorre 100 px abaixo do topo da área de visualização, clientY é 100 e pageY é 400. Mantenha ambas as posições no mesmo referencial de coordenadas ao calcular o movimento. Uma mudança no alvo aninhado também pode mudar a origem das coordenadas de deslocamento.

button informa qual botão mudou em um evento de pressionamento ou liberação: 0 primário, 1 meio, 2 secundário. buttons informa a combinação atualmente pressionada: o primário contribui com 1, o secundário com 2 e o do meio com 4. Assim, buttons === 3 significa que o primário e o secundário estão pressionados; não significa que o botão do meio mudou.

Escolha o comportamento de passagem para um controle inteiro

Eventos over/out borbulham e podem disparar quando o ponteiro cruza os limites dos filhos. Eventos enter/leave não borbulham e descrevem a entrada ou saída do elemento inteiro, incluindo seus filhos. Uma dica pode evitar a oscilação nos limites dos filhos com pointerenter e pointerleave.

Usuários de toque e teclado não passam o ponteiro. Ofereça informações essenciais também por clique ou foco. Para um efeito visual de passagem sem comportamento adicional, o CSS :hover é mais simples que um ouvinte.

O arraste precisa manter informações entre vários eventos. Armazene as coordenadas iniciais do ponteiro e a posição inicial do elemento. Cada movimento aplica a diferença em relação a esse ponto inicial, para que o elemento não salte colocando seu canto sob o ponteiro.

Calcule o deslocamento

Uma caixa começa em left: 100px; top: 50px. O ponteiro começa nas coordenadas 220, 140 da área de visualização e se move para 260, 125. A mudança horizontal é 40 px; a mudança vertical é −15 px. Somar essas mudanças à posição inicial da caixa resulta em left: 140px; top: 35px.

Use coordenadas de cliente consistentes para as duas leituras do ponteiro. O cálculo geral é a posição inicial do elemento mais o deslocamento do ponteiro. Não some cada deslocamento completo à posição já atualizada da caixa, pois isso contaria novamente o movimento anterior.

Armazene e capture um ponteiro

Para uma caixa sem margem e com posicionamento absoluto dentro de um contêiner com posicionamento relativo:

let start = null;
box.addEventListener("pointerdown", (event) => {
  if (start || event.button !== 0) return;
  start = { id: event.pointerId, x: event.clientX,
    y: event.clientY, left: box.offsetLeft,
    top: box.offsetTop };
  box.setPointerCapture(event.pointerId);
});
box.addEventListener("pointermove", (event) => {
  if (!start || event.pointerId !== start.id) return;
  box.style.left = start.left +
    (event.clientX - start.x) + "px";
  box.style.top = start.top +
    (event.clientY - start.y) + "px";
});
function endDrag(event) {
  if (start && event.pointerId === start.id) start = null;
}
box.addEventListener("pointerup", endDrag);
box.addEventListener("pointercancel", endDrag);

O ID armazenado descarta movimentos e liberações de um segundo ponteiro. offsetLeft e offsetTop fornecem posições iniciais como números; os estilos precisam do sufixo "px".

A captura de ponteiro mantém os eventos seguintes desse ponteiro direcionados à caixa mesmo quando ele se move para fora dela. O navegador libera a captura após a liberação ou o cancelamento do ponteiro. releasePointerCapture(id) pode liberá-la antes.

Trate a tomada de controle pelo navegador

Um gesto de toque pode se tornar rolagem ou zoom da página, causando pointercancel. Encerre o arraste nesse caso e também em pointerup; caso contrário, um estado desatualizado pode continuar movendo a caixa depois. Aplique touch-action: none à superfície de arraste antes da interação para reservar o gesto. Mantenha essa regra local para que o restante da página possa rolar.

Use user-select: none na superfície arrastável para evitar a seleção de texto. Defina draggable="false" em suas imagens para impedir o comportamento nativo de arraste de imagem.

Ofereça outra forma de mover

Ofereça movimento pelo teclado para um controle com foco e botões de movimento que possam ser clicados ou tocados. Teclas de seta, por si só, não fornecem uma alternativa ao arraste com um único ponteiro. O critério de sucesso 2.5.7 das WCAG 2.2 exige essa alternativa, a menos que o arraste seja essencial ou seja um comportamento não modificado do navegador. Botões nativos de movimento podem servir tanto a usuários de teclado quanto de ponteiro.

A API HTML Drag and Drop, separada desse padrão, usa dragstart, dragover e drop para transferir dados, como arquivos. Sua sequência de eventos difere desta mudança de posição baseada em ponteiro.

Controles de formulário expõem diferentes tipos de estado. O value de um campo de texto é uma cadeia de caracteres; o checked de uma caixa de seleção é um booleano. Ler a propriedade correta é o primeiro passo para cálculos e prévias confiáveis.

Converta números de forma deliberada

Mesmo <input type="number"> tem um value que é uma cadeia de caracteres. Com o texto "3", somar 1 resulta em "31". Number(input.value) + 1 resulta em 4. Uma entrada numérica também expõe valueAsNumber.

Uma entrada vazia precisa de uma decisão própria. Number("") resulta em 0, o que pode fazer uma quantidade ausente parecer um zero real. Verifique primeiro input.value === "" ou use valueAsNumber, que resulta em NaN para um campo numérico vazio. Teste esse resultado com Number.isNaN().

Leia o estado selecionado

O value de uma caixa de seleção é seu texto de envio configurado ou "on" se nenhum for fornecido. Ele não informa se ela está marcada. Uma lista de seleção informa o valor da opção escolhida. Para encontrar o próprio elemento de opção selecionado, consulte input[name="size"]:checked.

Associe o evento à atualização

input informa edições do usuário à medida que ocorrem, incluindo digitação e colagem. change informa uma escolha confirmada: depois que um campo de texto alterado perde o foco ou imediatamente quando uma caixa de seleção, um botão de opção ou uma lista de seleção é alterado.

message.addEventListener("input", () => {
  counter.textContent = 280 - message.value.length +
    " characters left";
});

Após “Hello”, cinco caracteres foram usados e o contador mostra “275 characters left”. Um ouvinte de keydown seria executado antes de o novo caractere entrar no valor e não detectaria uma colagem por menu. Atribuir message.value por código não dispara input nem change; chame também a função de atualização diretamente.

Colete os campos nomeados de um formulário

form.elements.email.value acessa um controle pelo nome ou ID. Use form.elements["first-name"] para um nome com hífen. O envio usa nomes: um ID sozinho não coloca um campo nos dados.

const data = new FormData(form);
const email = data.get("email");
const topics = data.getAll("topics");

FormData coleta os pares de nome e valor atuais que podem ser incluídos. Caixas de seleção não marcadas, controles desabilitados e campos sem nome são omitidos. get() retorna o primeiro valor de um nome; getAll() preserva valores repetidos, como vários tópicos marcados. Controles de arquivo podem fornecer objetos de arquivo; controles de texto comuns fornecem cadeias de caracteres.

Object.fromEntries(data) é conveniente para nomes distintos, mas mantém apenas o último par para nomes repetidos. Escolha getAll() quando cada seleção importar. Como input borbulha, um ouvinte no formulário pode ler event.target para atualizar qualquer campo alterado.

O envio pertence ao formulário. Ouça seu evento submit para tratar por um único caminho um clique em botão de envio, Enter em um campo de uma linha e uma chamada a requestSubmit() por script.

Substitua a navegação por uma atualização da página

Normalmente, um formulário envia dados para sua URL action e carrega a resposta. Sem uma ação, o destino é a página atual. O método padrão GET coloca os dados na URL. Para atualizar a página atual com JavaScript, cancele essa ação padrão:

const form = document.querySelector("#new-todo");
form.addEventListener("submit", (event) => {
  event.preventDefault();
  const data = new FormData(form);
  const title = data.get("title").trim();
  if (title === "") return;
  addTodo(title);
  form.reset();
});

Esse formulário tem um campo de texto habilitado chamado title. O ouvinte remove espaços das extremidades, ignora um resultado vazio, adiciona um item e redefine os campos para seus valores iniciais. reset() nem sempre significa vazio; um controle com valor inicial retorna a esse valor.

Se o item aparecer brevemente e desaparecer quando a página recarregar, verifique se preventDefault() está faltando. Um ouvinte de clique no botão, por si só, não é o ponto adequado para tratar o formulário, especialmente quando outro caminho o envia.

Saiba o que aciona o envio

O envio implícito por Enter pode clicar no botão de envio padrão habilitado. Enter em um textarea insere uma nova linha. Um botão dentro de um formulário é, por padrão, um botão de envio quando seu tipo é omitido, então um botão “Mostrar senha” deve usar explicitamente type="button".

Quando há vários botões de envio, event.submitter identifica o que foi usado. Ele pode ser null em caminhos sem um botão específico, então o código deve verificar antes de lê-lo:

const button = event.submitter;
const intent = button ? button.value : "save";
const data = button ? new FormData(form, button) :
  new FormData(form);

Um botão responsável pelo envio com nome, como name="intent" value="publish", acrescenta esse par quando passado a FormData. Uma chamada a FormData(form) por si só não inclui o par de nome e valor de um botão de envio.

Preserve o caminho de validação

A validação nativa é executada antes do evento de envio. Se um campo obrigatório vazio falhar, o navegador informa o problema e não dispara submit. Uma verificação personalizada apenas dentro desse ouvinte não será executada nessa tentativa malsucedida. novalidate no formulário desativa a etapa de validação automática.

Use requestSubmit() quando o código precisar do caminho normal de validação e evento de envio. Ele solicita o envio sem disparar um clique no botão. Passe um botão de envio específico a requestSubmit(button) quando as configurações de envio desse botão devam ser aplicadas.

O HTML pode descrever muitas regras de entrada sem um teste personalizado em JavaScript. O navegador verifica essas regras durante o envio e expõe os resultados para seu código. Comece pelas restrições que correspondem aos dados de que você precisa.

Escolha uma restrição

Para pattern="[0-9]{5}", “12345” passa; “1234”, “123456” e “12345a” falham. O padrão abrange o valor inteiro, não qualquer parte correspondente. Uma entrada vazia ignora a verificação de padrão, então adicione required quando a omissão não for permitida.

A validação de e-mail verifica a sintaxe, não se uma caixa de entrada existe. Tanto “ann@example.com” quanto “ann@example” passam na regra de e-mail do navegador, enquanto “ann.example.com” não passa. Um padrão adicional pode impor um formato mais específico quando a aplicação exigir.

Leia o motivo da falha

O objeto validity de um campo contém indicadores booleanos. valueMissing, typeMismatch, patternMismatch, tooShort e tooLong descrevem texto ausente ou malformado. rangeUnderflow, rangeOverflow e stepMismatch descrevem restrições numéricas. badInput abrange uma entrada que o navegador não consegue transformar em um valor utilizável, e customError registra uma mensagem de validade personalizada. valid é verdadeiro quando nenhuma restrição falha.

Para um campo numérico com min="0" max="10" step="2", 12 está acima do máximo, 7 não segue o incremento permitido e 6 passa. Mais de um indicador pode ser verdadeiro; não suponha que todo campo inválido tenha exatamente um problema.

Verifique silenciosamente ou informe de forma visível

checkValidity() retorna um booleano e dispara invalid nos controles que falham sem mostrar a mensagem do navegador. reportValidity() verifica e também informa o problema ao usuário. Chame qualquer um deles em um campo ou formulário. validationMessage fornece a mensagem no idioma do navegador. O evento invalid não borbulha.

Restrições de comprimento de texto se aplicam ao texto inserido pelo usuário. Atribuir input.value = "ab" no código não torna tooShort verdadeiro apenas porque minlength é 3. maxlength normalmente também impede que o usuário continue digitando além do limite.

Mostre erros em um momento útil

:invalid se aplica imediatamente, então um campo obrigatório ainda não tocado já corresponde ao seletor. :user-invalid espera uma interação do usuário ou uma tentativa de envio e pode evitar um campo vermelho cedo demais. Use texto para explicar o erro, além de um estilo visual.

novalidate ignora a validação automática de envio para o formulário; formnovalidate a ignora para um botão de envio. Eles não removem restrições nem desativam checkValidity(). As verificações do navegador ajudam os usuários a corrigir erros; o servidor deve validar novamente os dados recebidos, pois uma requisição pode contornar a página.

Uma regra que envolve dois campos precisa de código. Por exemplo, uma confirmação deve corresponder a uma senha, ou uma data final deve vir após uma data inicial. Mantenha a regra separada de como e quando seu erro é exibido.

Defina e limpe um erro personalizado

Uma cadeia de caracteres não vazia passada a setCustomValidity() marca o campo como inválido e define customError. Passar "" limpa essa falha personalizada; restrições de obrigatoriedade, padrão ou outras ainda podem falhar.

function checkMatch() {
  const matches = confirm.value === password.value;
  confirm.setCustomValidity(matches ? "" :
    "The passwords do not match.");
}
password.addEventListener("input", checkMatch);
confirm.addEventListener("input", checkMatch);

Verifique novamente ambas as dependências. Alterar a primeira senha pode invalidar uma confirmação que antes estava correta. Uma mensagem que nunca é limpa mantém o campo inválido depois que a pessoa corrige a divergência. Execute também a verificação inicial quando os campos puderem começar com valores.

Entradas de data fornecem cadeias ISO como "2026-03-10", independentemente do formato local de data exibido. Valores não vazios desses controles podem ser comparados como texto. Se a regra disser que o fim deve ser posterior ao início, rejeite end.value <= start.value, incluindo a igualdade. Trate datas ausentes com required ou com uma verificação separada de valor vazio.

Explique a próxima ação útil

Uma mensagem deve identificar o problema e sua correção. Para um e-mail ausente, diga “Digite seu endereço de e-mail.” Para um texto de e-mail malformado, diga “Digite um endereço de e-mail no formato nome@example.com.” Mantenha o valor inserido para que a pessoa possa editá-lo.

Um campo de nome obrigatório aceita espaços porque eles formam uma cadeia não vazia. Verifique name.value.trim() === "" quando espaços em branco nas extremidades não devem contar. Limpe esse erro personalizado quando aparecer um texto com conteúdo.

Associe mensagens aos controles

<label for="email">Email</label>
<input id="email" name="email" type="email"
  required aria-describedby="email-error">
<p id="email-error"></p>

Coloque o erro nesse parágrafo e defina aria-invalid="true" enquanto o campo tiver um erro. Limpe o texto e remova aria-invalid ou defina-o como "false" após a correção. aria-describedby associa a explicação ao campo para a tecnologia assistiva. Use texto; uma borda vermelha sozinha não informa a todos o que falhou.

Escolha o fluxo de validação

Para mensagens inteiramente personalizadas, adicione novalidate e use um ouvinte de submit no formulário. Atualize as regras personalizadas, inspecione a validade dos campos, escreva suas mensagens e impeça o envio quando algum falhar. Mova o foco para o primeiro campo inválido ou para um resumo de erros com links. Se o JavaScript também tratar localmente o envio bem-sucedido, cancele esse envio padrão.

Evite informar que um texto de e-mail está incompleto a cada tecla pressionada no início. Uma sequência útil é mostrar erros após a perda de foco ou o envio e depois verificar novamente um erro já informado em input.

Um controle precisa de mais do que uma resposta a clique. As pessoas precisam ser capazes de encontrá-lo, alcançá-lo, entender sua finalidade, operá-lo e ver onde está o foco. O HTML nativo já fornece grande parte desse comportamento.

Escolha o elemento para a tarefa

Use um <button> para uma ação, um <a href> para navegação e um controle de formulário com rótulo para entrada. <details> com <summary> fornece um controle de expansão e recolhimento. Estilize esses elementos com CSS para combinar com a página. Um botão com foco é ativado por Enter ou pela barra de espaço sem um ouvinte de teclado adicional.

Um div com ouvinte de clique não tem a semântica nem o comportamento de teclado nativos do botão. Atribuir-lhe role="button" altera o que a tecnologia assistiva anuncia, mas não permite que ele receba foco nem transforma pressionamentos de teclas em cliques.

Mantenha a ordem de foco previsível

tabindex="0" adiciona um elemento à sequência normal de Tab na ordem do documento. tabindex="-1" permite foco por código sem adicionar uma parada de Tab. Valores positivos movem elementos para antes da sequência usual e são difíceis de manter; evite-os.

Nenhuma das duas configurações acrescenta comportamento de ativação. Um botão personalizado que pode receber foco ainda precisa de um ouvinte para sua operação pelo teclado. Um papel, uma parada de Tab e uma função de retorno resolvem partes diferentes da interação.

Dê um nome a cada controle

Um leitor de tela usa um nome acessível para distinguir controles. Um botão de texto pode usar seu texto visível. Um campo de texto ou uma lista de seleção precisa de um rótulo associado, como <label for="email">Email</label> combinado com id="email". aria-labelledby pode fazer referência a um texto visível em outro lugar; aria-label pode fornecer um nome quando não houver texto visível adequado.

Um botão de fechar que contém apenas um ícone pode ser <button type="button" aria-label="Close">×</button>. O nome descreve a ação em vez de fazer o usuário deduzir o significado do símbolo.

Mostre e faça cumprir o estado

Mantenha um indicador de foco visível. Se substituir o contorno padrão, forneça um substituto claro com :focus-visible, por exemplo outline: 3px solid #1a73e8. Removê-lo sem substituição oculta a posição do usuário de teclado.

Um botão nativo desabilitado sai da sequência de Tab e não pode ser ativado normalmente. aria-disabled="true" apenas comunica a indisponibilidade. A ação de clique e de teclado de um controle personalizado deve verificar esse estado e retornar sem agir. Centralizar essa verificação na função de ativação mantém os dois caminhos de entrada consistentes.

Um controle personalizado deve produzir o mesmo resultado independentemente de como é ativado. Mantenha a ação em uma função, encaminhe a ela o uso de teclado e ponteiro e atualize o estado lido pela estilização e pela tecnologia assistiva.

Dê ativação por teclado a um botão personalizado

fakeButton.addEventListener("click", activate);
fakeButton.addEventListener("keydown", (event) => {
  if (event.key === "Enter" || event.key === " ") {
    event.preventDefault();
    activate();
  }
});

Isso se aplica a um botão personalizado que pode receber foco. Cancelar a barra de espaço impede a rolagem da página durante a ação. Um botão nativo já produz cliques pela ativação com teclado, então adicionar um segundo caminho por tecla pode executar a ação duas vezes.

Escolha o estado correspondente ao controle

Um botão de alternância “Silenciar” mantém esse rótulo e altera aria-pressed. Se o design mudar o rótulo da ação para “Ativar som”, omita aria-pressed. Uma caixa de seleção usa role="checkbox" e a barra de espaço para alternar; um interruptor usa role="switch" para o estado ligado/desligado.

Atributos contêm cadeias de caracteres. Compare getAttribute("aria-expanded") com "true", não com o booleano true:

detailsButton.addEventListener("click", () => {
  const open = detailsButton.getAttribute(
    "aria-expanded") === "true";
  detailsButton.setAttribute("aria-expanded", String(!open));
  panel.hidden = open;
});

Quando open era verdadeiro, o novo estado é falso e o painel fica oculto. aria-controls pode identificar o painel pelo ID. Os elementos nativos <details> e <summary> fornecem o comportamento de expansão e recolhimento sem esse script.

Use o atributo de estado como fonte para a estilização, como [aria-pressed="true"], para que os estados visível e anunciado mudem juntos. Feche pop-ups com Escape e devolva o foco ao controle de abertura.

Dê ao grupo uma única parada de Tab

Abas, barras de ferramentas e grupos de botões de opção usam Tab para entrar ou sair do grupo e teclas de seta para se mover dentro dele. O tabindex itinerante mantém o item atual em 0 e os outros em -1. Ao mover, defina o item anterior como -1, o novo como 0 e dê foco ao novo item.

Para três itens, mover à direita a partir do índice 2 retorna a 0 com (2 + 1) % 3. Mover à esquerda a partir de 0 usa (0 - 1 + 3) % 3 para chegar a 2. Some o tamanho antes da operação de resto porque -1 % 3 em JavaScript é −1.

Verifique com o teclado: entre no controle, veja o foco, ative-o com as teclas adequadas, mova-se dentro de um grupo e feche um pop-up com Escape. Verifique o estado visível e o estado ARIA a cada mudança.

O foco determina para onde vai a próxima ação do teclado. Se o controle com foco desaparecer, o usuário pode perder sua posição. Trate o foco como parte da atualização da página, especialmente ao abrir uma caixa de diálogo, excluir um item ou informar um erro.

Abra uma caixa de diálogo e retorne ao controle de abertura

Lembre qual elemento tinha foco antes de abrir. Mova o foco para a nova interação e restaure-o ao fechar:

let opener;
openButton.addEventListener("click", () => {
  opener = document.activeElement;
  dialog.showModal();
});
dialog.addEventListener("close", () => {
  if (opener && opener.isConnected) opener.focus();
});

showModal() em uma caixa de diálogo nativa move o foco para dentro dela e torna o restante da página inerte, de modo que não possa ser clicado nem receber foco enquanto a caixa modal estiver aberta. Escape normalmente causa um evento cancel, seguido pelo fechamento e por um evento close. Um ouvinte de cancel pode impedir o fechamento se a aplicação precisar desse comportamento.

Escolha um local inicial de foco útil na caixa de diálogo, como seu primeiro controle relevante. Para um pop-up personalizado, o código deve mover o foco intencionalmente. Quando o controle de abertura original não existir mais, escolha um controle útil próximo em vez de tentar dar foco a um elemento desconectado.

Permita que um destino útil receba foco

Um título ou resumo de erros normalmente não pode receber foco. Dê a ele tabindex="-1" antes de chamar .focus(). Ele poderá receber o foco intencionalmente sem se tornar uma parada extra durante a navegação normal por Tab. Use 0 apenas quando ele pertencer a essa sequência normal.

Preserve a posição após uma exclusão

Antes de remover um item de lista cujo botão de exclusão tem foco, encontre o próximo destino útil. Dê foco ao botão do próximo item; se não houver próximo item, use o botão do item anterior. Se a lista ficar vazia, dê foco ao seu título com tabindex="-1".

Encontrar o destino antes da remoção evita perder a relação com os itens vizinhos. Não envie o foco para o início do documento após cada exclusão; a pessoa deve poder continuar trabalhando perto da alteração.

Mantenha o foco em uma interação em andamento

Um pop-up pode fechar quando o foco sai de toda a sua área. O evento focusout, que borbulha, fornece o destino:

menu.addEventListener("focusout", (event) => {
  if (!menu.contains(event.relatedTarget)) {
    menu.hidden = true;
  }
});

Mover-se entre dois controles do menu não o fecha porque o destino permanece dentro dele. Um destino null também está fora; contains(null) é falso. Não devolva o foco automaticamente ao controle de abertura quando o usuário tiver se movido intencionalmente para outro controle da página.

Torne as mudanças previsíveis

Após uma validação personalizada de formulário malsucedida, dê foco ao primeiro campo inválido ou a um resumo de erros com links para eles. A validação nativa já dá foco a um campo que falha. Mantenha o texto de erro disponível para que a pessoa saiba o que corrigir.

Não pule para um novo campo enquanto o usuário estiver digitando nem navegue assim que uma lista de seleção mudar. Permita que uma ação clara confirme a alteração. O movimento de foco deve apoiar uma ação deliberada ou a recuperação, não interromper a entrada normal.