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
- HTML Standard — Form submission algorithm
- HTML Standard — Constraints: Security
- HTMLFormElement: submit event
- Element: input event
- HTMLElement: change event
- HTMLFormElement: requestSubmit() method
- HTMLFormElement: submit() method
- Event: currentTarget property
- Event: preventDefault() method
- EventTarget: dispatchEvent() method