Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

HTMLFormElement.requestSubmit() — wysyłanie formularza z walidacją

requestSubmit() uruchamia standardową procedurę wysyłania formularza, która może obejmować walidację i zdarzenie submit. Opcjonalny przycisk określa inicjatora wysyłania oraz może zmienić jego parametry. W przeciwieństwie do submit() metoda nie pomija tych mechanizmów.

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

Składnia

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

HTMLFormElement.requestSubmit to metoda formularza zdefiniowana w HTML Living Standard, a nie w ECMAScript. Wywołanie form.requestSubmit() rozpoczyna procedurę wysyłania, która może zakończyć się przed interaktywną walidacją ograniczeń. Tak dzieje się na przykład, gdy formularz nie jest podłączony do dokumentu: walidacja nie jest wykonywana, a zdarzenie submit nie jest wywoływane. Jeśli procedura dotrze do etapu walidacji, walidacja zostanie wykonana, chyba że wyłącza ją novalidate formularza lub formnovalidate wybranego przycisku. Niepowodzenie walidacji zatrzymuje wysyłanie, ale jej pomyślny wynik lub pominięcie nie gwarantuje wywołania anulowalnego zdarzenia submit. Metoda zwraca undefined, nie wynik walidacji ani obietnicę.

Przekazanie null jako opcjonalnego argumentu submitter jest równoważne pominięciu argumentu. W obu przypadkach metoda nie wybiera automatycznie pierwszego przycisku, a event.submitter ma wartość null. Tylko gdy submitter nie jest równy null, metoda sprawdza, czy jest to przycisk wysyłający powiązany z tym formularzem. Przycisk nie musi znajdować się wewnątrz formularza, ponieważ powiązanie może zapewnić atrybut form. Element, który nie jest przyciskiem wysyłającym, powoduje TypeError, a przycisk wysyłający powiązany z innym formularzem lub niepowiązany z żadnym — NotFoundError.

Przekazany przycisk jest dostępny jako event.submitter. Jego formaction, formenctype, formmethod, formnovalidate i formtarget mogą wpływać na wysyłanie, a jego para name/value może wejść do danych formularza. requestSubmit() nie emituje zdarzenia click. Natomiast form.submit() pomija zarówno interaktywną walidację, jak i zdarzenie submit; nie jest równoważnym zamiennikiem. event.preventDefault() w obsłudze submit zatrzymuje domyślne wysłanie.

W przykładzie formularz jest podłączony do dokumentu: puste pole required blokuje pierwszą próbę wysłania, a druga dochodzi do zdarzenia submit. To API przeglądarkowe; obecność Node 24 nie potwierdza jego dostępności. Tabela zgodności w standardzie podaje Chrome 76+, Firefox 75+ i Safari 16+; w docelowym środowisku sprawdź typeof HTMLFormElement === 'function' && typeof HTMLFormElement.prototype.requestSubmit === 'function'.

Przykłady

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

Wynik

invalid
submit: save
submissions: 1

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła