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

CKTIS / JavaScript

HTMLFormElement.requestSubmit() — submeter um formulário com validação

requestSubmit() inicia o procedimento normal de submissão de um formulário, que pode incluir a validação e um evento submit. Um botão opcional identifica o elemento que inicia a submissão e pode alterar as respetivas opções. Ao contrário de submit(), este método não contorna estes mecanismos.

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.requestSubmit();
form.requestSubmit(submitter);

HTMLFormElement.requestSubmit é um método de formulário definido pelo HTML Living Standard, não pelo ECMAScript. A chamada form.requestSubmit() inicia o procedimento de submissão, que pode terminar antes da validação interativa das restrições. Por exemplo, se o formulário não estiver ligado ao documento, o procedimento termina sem efetuar a validação nem disparar um evento submit. Se o procedimento chegar à etapa de validação, esta é efetuada, exceto se novalidate no formulário ou formnovalidate no botão selecionado a desativar. Se a validação falhar, a submissão é interrompida, mas passar na validação ou ignorá-la não garante que seja disparado um evento submit cancelável. O método devolve undefined, não um resultado da validação nem uma promessa.

Passar null como argumento opcional submitter equivale a omitir o argumento. Em ambos os casos, o método não seleciona automaticamente o primeiro botão e event.submitter tem o valor null. Só quando submitter é diferente de null é que tem de ser um botão de submissão associado a este formulário. O botão não precisa de estar dentro do formulário, pois o atributo form pode estabelecer essa associação. Um elemento que não seja um botão de submissão provoca TypeError, enquanto um botão de submissão associado a outro formulário ou a nenhum formulário provoca NotFoundError.

O botão indicado está disponível através de event.submitter. Os atributos formaction, formenctype, formmethod, formnovalidate e formtarget podem influenciar a submissão; além disso, o par name/value pode ser incluído nos dados do formulário. requestSubmit() não dispara um evento click. Em contrapartida, form.submit() contorna tanto a validação interativa como o evento submit; não é uma alternativa equivalente. Chamar event.preventDefault() no processador de submit impede a submissão predefinida.

No exemplo, o formulário está ligado ao documento: um campo required vazio bloqueia a primeira tentativa de submissão e a segunda chega ao evento submit. Esta é uma API do navegador; ter Node 24 não comprova a sua disponibilidade. A tabela de compatibilidade da norma indica Chrome 76+, Firefox 75+ e Safari 16+; verifica typeof HTMLFormElement === 'function' && typeof HTMLFormElement.prototype.requestSubmit === 'function' no ambiente de destino.

Exemplos

(() => {
  const form = document.createElement('form');
  const input = document.createElement('input');
  input.name = 'topic';
  input.required = true;

  const button = document.createElement('button');
  button.type = 'submit';
  button.name = 'action';
  button.value = 'save';
  form.append(input, button);
  document.body.append(form);

  let submissions = 0;
  input.addEventListener('invalid', event => {
    event.preventDefault();
    console.log('invalid');
  });
  form.addEventListener('submit', event => {
    event.preventDefault();
    submissions++;
    console.log('submit: ' + event.submitter.value);
  });

  try {
    form.requestSubmit(button);
    input.value = 'JavaScript';
    form.requestSubmit(button);
    console.log('submissions: ' + submissions);
  } finally {
    form.remove();
  }
})();

Resultado

invalid
submit: save
submissions: 1

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.

Fontes