Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

HTMLFormElement.requestSubmit() — enviar un formulario con validación

requestSubmit() inicia el procedimiento estándar de envío de formularios, que puede incluir la validación y un evento submit. Un botón opcional identifica el elemento que inicia el envío y puede cambiar sus opciones. A diferencia de submit(), este método no omite estos mecanismos.

Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxis

form.requestSubmit();
form.requestSubmit(submitter);

HTMLFormElement.requestSubmit es un método de formulario definido por el HTML Living Standard, no por ECMAScript. Al llamar a form.requestSubmit() se inicia el procedimiento de envío, que puede detenerse antes de la validación interactiva de restricciones. Por ejemplo, si el formulario no está conectado al documento, el procedimiento termina sin validar ni disparar un evento submit. Si el procedimiento llega a la etapa de validación, esta se realiza salvo que novalidate en el formulario o formnovalidate en el botón seleccionado la desactive. Si la validación falla, el envío se detiene, pero superarla u omitirla no garantiza que se dispare un evento submit cancelable. El método devuelve undefined, no un resultado de validación ni una promesa.

Pasar null como argumento opcional submitter equivale a omitir el argumento. En ambos casos, el método no selecciona automáticamente el primer botón y event.submitter es null. Solo si submitter no es null debe ser un botón de envío asociado a este formulario. El botón no tiene que estar dentro del formulario, ya que el atributo form puede establecer esa asociación. Un elemento que no sea un botón de envío provoca TypeError, mientras que un botón de envío asociado a otro formulario o a ninguno provoca NotFoundError.

El botón proporcionado está disponible como event.submitter. Sus atributos formaction, formenctype, formmethod, formnovalidate y formtarget pueden afectar al envío, y su par name/value puede incluirse en los datos del formulario. requestSubmit() no dispara un evento click. En cambio, form.submit() omite tanto la validación interactiva como el evento submit; no es un sustituto equivalente. Llamar a event.preventDefault() en el controlador de submit detiene el envío predeterminado.

En el ejemplo, el formulario está conectado al documento: un campo required vacío bloquea el primer intento de envío y el segundo llega al evento submit. Esta es una API del navegador; tener Node 24 no demuestra que esté disponible. La tabla de compatibilidad del estándar indica Chrome 76+, Firefox 75+ y Safari 16+; comprueba typeof HTMLFormElement === 'function' && typeof HTMLFormElement.prototype.requestSubmit === 'function' en el entorno de destino.

Ejemplos

(() => {
  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

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes