Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Eventos `submit` e `input` em formulários HTML

Usa `input` para reagir a alterações e `submit` para tratar a submissão do formulário na altura certa do processo de validação.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

form.addEventListener("submit", onSubmit);
form.addEventListener("input", onInput);
form.requestSubmit();
form.requestSubmit(submitter);
form.submit();

input é disparado no controlo editado e propaga-se pela árvore DOM até aos seus antepassados. Num ouvinte no formulário, event.target identifica o controlo e event.currentTarget identifica o formulário enquanto o ouvinte é executado. Se um controlo estiver fora do formulário e lhe estiver associado pelo atributo form, só essa associação não faz com que o evento chegue ao formulário. Usa input para dar feedback durante a edição; change indica que a alteração foi confirmada, normalmente quando um campo de texto perde o foco. Atribuir um valor a .value não dispara input por si só.

submit é disparado no formulário, não no botão. É um SubmitEvent que se propaga e pode ser cancelado. Escuta-o em vez do click do botão, para também tratares a submissão implícita, por exemplo ao premir Enter se o navegador o permitir. event.submitter identifica o botão de submissão ou vale null se nenhum botão iniciou a submissão. Para impedir a submissão predefinida, chama event.preventDefault() no ouvinte antes de qualquer await.

form.requestSubmit() segue as regras normais de submissão sem selecionar um botão. form.requestSubmit(button) usa esse botão e respeita as suas definições, como formaction e formnovalidate. Se a validação das restrições for efetuada e falhar, os controlos inválidos recebem invalid e não é disparado submit. Passar um elemento que não é um botão de submissão lança TypeError; passar um botão de submissão que não pertence ao formulário lança NotFoundError.

Chamar diretamente form.submit() ignora a validação das restrições e não dispara submit. Um controlo com name ou id igual a submit pode ocultar o método. A validação no navegador não substitui a validação no servidor. Estas API são da plataforma web, não do ECMAScript 2024; verifica o suporte no ambiente de destino.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Form submit and input events</title>
</head>
<body>
<script>
(() => {
  const form = document.createElement("form");
  const field = document.createElement("input");
  field.type = "text";
  field.required = true;

  const button = document.createElement("button");
  button.type = "submit";
  button.value = "save";
  button.textContent = "Save";
  form.append(field, button);

  field.addEventListener("invalid", (event) => {
    event.preventDefault();
    console.log("invalid");
  });
  form.addEventListener("input", (event) => {
    if (event.target === field) console.log(`input: ${field.value}`);
  });
  form.addEventListener("submit", (event) => {
    event.preventDefault();
    console.log(`submit: ${event.submitter.value}`);
  });

  document.body.append(form);
  try {
    form.requestSubmit(button);
    field.value = "Ada";
    console.log(`set: ${field.value}`);
    field.dispatchEvent(new Event("input", { bubbles: true }));
    form.requestSubmit(button);
  } finally {
    form.remove();
  }
})();
</script>
</body>
</html>

Resultado

invalid
set: Ada
input: Ada
submit: save

Guarda o exemplo como ficheiro HTML e abre-o num navegador. Abre a consola e recarrega a página. O primeiro pedido escreve `invalid`. Depois de `set: Ada`, só o evento disparado manualmente produz `input: Ada`; o segundo pedido escreve `submit: save`, mas o ouvinte cancela a submissão.

Lições relacionadas

  • JavaScript · Lição 15 · Avançado · Versão: 4

Fontes