HOWTO · JavaScript
Como impedir o envio de um formulário em JavaScript
Impeça o envio de um formulário quando a validação do lado do cliente falhar com um ouvinte de evento submit, um manipulador onsubmit inline ou jQuery.
Nesta página
Para impedir que um formulário seja enviado quando os seus dados falham na validação do lado do cliente, trate o evento submit do formulário e chame event.preventDefault() apenas quando uma verificação falhar. Anexe o ouvinte ao formulário, não ao seu botão de envio: o evento submit do formulário também abrange o envio pelo teclado. Quando os dados forem válidos, deixe a ação predefinida intacta para que o navegador possa enviar o formulário.
Impedir o envio de um formulário com um ouvinte de evento submit
Um ouvinte submit é a escolha habitual para código JavaScript novo. Este exemplo autónomo em Node.js modela a interface de eventos utilizada por um formulário de navegador e mostra um e-mail válido a chegar ao caminho de envio normal. Numa página, registe o mesmo manipulador com form.addEventListener('submit', handleSubmit).
const form = {
listener: null,
addEventListener(type, callback) {
if (type === 'submit') this.listener = callback;
},
submit(event) {
this.listener(event);
return !event.defaultPrevented;
}
};
const email = 'reader@example.com';
const handleSubmit = (event) => {
if (!email.includes('@')) event.preventDefault();
};
form.addEventListener('submit', handleSubmit);
const event = {
defaultPrevented: false,
preventDefault() {
this.defaultPrevented = true;
}
};
console.log(form.submit(event) ? 'Form may submit' : 'Submission prevented');
O pequeno objeto de formulário do exemplo permite que o manipulador seja executado em Node.js; num navegador, o navegador fornece o formulário e o evento. Na sua página, leia os controlos relevantes dentro do manipulador e chame event.preventDefault() quando uma verificação falhar. Chamá-lo cancela a ação de envio predefinida do navegador; não navega para outra página nem recua no histórico. Tanto um clique no botão de envio como premir Enter num controlo do formulário levam ao evento submit do formulário.
Usar um manipulador onsubmit inline
Um manipulador onsubmit inline é uma alternativa para marcação existente. Por exemplo, <form onsubmit="return validateForm()"> chama uma função quando o formulário é enviado. Devolva false quando a validação falhar para cancelar o envio; devolva true quando o formulário estiver pronto para ser enviado. Mantenha a função disponível para a página e certifique-se de que devolve um valor em todos os caminhos. Para código novo, um ouvinte geralmente mantém o comportamento separado do HTML.
Impedir o envio com jQuery
Se um projeto já utiliza jQuery, anexe um manipulador ao formulário com $('#myForm').on('submit', function (event) { ... }). Verifique os valores do formulário dentro da chamada de retorno e chame event.preventDefault() apenas quando a validação falhar. Não chame $('#myForm').submit() a partir do manipulador para impedir o envio: isso desencadeia o comportamento de envio em vez de cancelar a ação predefinida do navegador. O jQuery é opcional; o addEventListener nativo fornece o mesmo evento de formulário sem a dependência.
Validar as entradas e fornecer feedback
Quando uma verificação falhar, impeça o envio e mostre uma mensagem concisa junto ao campo que necessita de atenção. Associe essa mensagem ao seu controlo, exponha o erro à tecnologia de apoio e mova o foco para o primeiro campo que necessita de correção, quando apropriado. Evite depender de um alerta como único feedback. Quando todas as verificações passarem, permita que o envio continue e deixe o servidor validar também os dados recebidos; as verificações do lado do cliente melhoram a interação, mas não protegem os dados por si só.
Utilize restrições HTML como required, type="email" e minlength quando se adequarem ao formulário. O navegador pode comunicar estas falhas antes de ser enviado um evento submit normal; verificações personalizadas podem adicionar regras que as restrições HTML não expressam. Não desative o botão de envio como substituto da validação, pois os utilizadores continuam a precisar de um caminho claro para corrigir a sua entrada.