CKTIS / JavaScript
HTMLFormElement.reset() — restaurar o estado predefinido de um formulário
HTMLFormElement.reset() restaura o estado predefinido dos controlos associados a um formulário, em vez de simplesmente os esvaziar. Primeiro, emite um evento reset cancelável; preventDefault() impede a restauração.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
form.reset()HTMLFormElement.reset é um método da API DOM do navegador, não faz parte do ECMAScript. A chamada form.reset() não recebe argumentos e devolve undefined. Todos os principais motores de navegador atuais o suportam; a versão do Node.js, por si só, não comprova a disponibilidade desta API.
A reposição afeta os controlos associados ao formulário de destino cujo estado pode ser reposto, mesmo que não sejam descendentes desse formulário. Num input de texto, restaura o valor predefinido; numa caixa de verificação, restaura o estado assinalado predefinido. Por isso, não significa «esvaziar tudo». Alterar defaultValue muda o valor usado numa reposição posterior; não é uma captura imutável do estado no carregamento da página. A reposição não remove o atributo disabled.
Antes de alterar os controlos, o formulário emite um evento reset que propaga e pode ser cancelado. Chamar event.preventDefault() no respetivo processador impede a reposição. A leitura dos valores num processador síncrono deste evento ocorre antes da restauração. As alterações efetuadas pela reposição não desencadeiam eventos input.
Evita controlos com name="reset" ou id="reset": podem ocultar o método, tornando form.reset() impossível de chamar. Se ocorrer essa colisão, usa HTMLFormElement.prototype.reset.call(form). O exemplo mostra uma reposição normal e o seu cancelamento.
Exemplos
const form = document.createElement('form');
const input = document.createElement('input');
input.defaultValue = 'Ada';
form.append(input);
input.value = 'Grace';
form.addEventListener('reset', () => {
console.log('before reset: ' + input.value);
});
form.reset();
console.log('after reset: ' + input.value);
input.value = 'Lin';
form.addEventListener('reset', event => event.preventDefault(), { once: true });
form.reset();
console.log('after canceled reset: ' + input.value);Resultado
before reset: Grace after reset: Ada before reset: Lin after canceled reset: Lin
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.