Использование объектов FormData

Объект FormData позволяет собрать набор пар «ключ/значение» для отправки с помощью API Fetch или XMLHttpRequest. Он предназначен в первую очередь для отправки данных формы, но может использоваться независимо от форм для передачи данных с ключами. Передаваемые данные имеют тот же формат, что и метод submit() формы, если тип кодирования формы был установлен в multipart/form-data.

Создание объекта `FormData` с нуля

Вы можете сами создать объект FormData, инициализировав его, а затем добавив поля, вызвав его метод append(), например так:

const send = document.querySelector("#send");

send.addEventListener("click", async () => {
  const formData = new FormData();
  formData.append("username", "Groucho");
  formData.append("accountNum", 123456);

  // A file <input> element
  const avatar = document.querySelector("#avatar");
  formData.append("avatar", avatar.files[0]);

  // JavaScript file-like object
  const content = '<q id="a"><span id="b">hey!</span></q>';
  const blob = new Blob([content], { type: "text/xml" });
  formData.append("webmasterFile", blob);

  const response = await fetch("http://example.org/post", {
    method: "POST",
    body: formData,
  });
  console.log(await response.json());
});

Примечание: Поля "avatar" и "webmasterFile" оба содержат файл. Число, присвоенное полю "accountNum", немедленно преобразуется в строку методом FormData.append() (значение поля может быть Blob, File или строкой. Если значение не является ни Blob, ни File, оно преобразуется в строку).

Этот пример создаёт экземпляр FormData, содержащий значения для полей с именами "username", "accountNum", "avatar" и "webmasterFile", а затем использует fetch() для отправки данных формы. Поле "webmasterFile" является Blob. Объект Blob представляет собой похожий на файл объект неизменяемых, сырых данных. Blobs представляют данные, которые не обязательно находятся в формате, поддерживаемом JavaScript. Интерфейс File основан на Blob, наследует функциональность blob и расширяет её для поддержки файлов на компьютере пользователя. Для создания Blob можно вызвать конструктор Blob().

Получение объекта `FormData` из HTML-формы

Чтобы создать объект FormData, содержащий данные из существующей формы <form>, укажите этот элемент формы при создании объекта FormData:

Примечание: FormData будет использовать только поля ввода, которые используют атрибут name.

const formData = new FormData(someFormElement);

Например:

const send = document.querySelector("#send");

send.addEventListener("click", async () => {
  // A <form> element
  const userInfo = document.querySelector("#user-info");
  const formData = new FormData(userInfo);

  const response = await fetch("http://example.org/post", {
    method: "POST",
    body: formData,
  });
  console.log(await response.json());
});

Вы также можете добавить дополнительные данные в объект FormData между получением его из формы и отправкой, например так:

const send = document.querySelector("#send");

send.addEventListener("click", async () => {
  const userInfo = document.querySelector("#user-info");
  const formData = new FormData(userInfo);
  formData.append("serialnumber", 12345);

  const response = await fetch("http://example.org/post", {
    method: "POST",
    body: formData,
  });
  console.log(await response.json());
});

Это позволяет дополнить данные формы перед отправкой, включив дополнительную информацию, которая не обязательно подлежит редактированию пользователем.

Отправка файлов с помощью объекта `FormData`

Вы также можете отправлять файлы с помощью FormData. Включите элемент <input> типа file в вашей форме <form>:

<form enctype="multipart/form-data" method="post" name="fileinfo" id="fileinfo">
  <p>
    <label
      >Your email address:
      <input
        type="email"
        autocomplete="on"
        name="userid"
        placeholder="email"
        required
        size="32"
        maxlength="64" />
    </label>
  </p>
  <p>
    <label
      >Custom file label:
      <input type="text" name="file-label" size="12" maxlength="32" />
    </label>
  </p>
  <p>
    <label
      >File to stash:
      <input type="file" name="file" required />
    </label>
  </p>
  <p>
    <input type="submit" value="Stash the file!" />
  </p>
</form>

Затем вы можете отправить его с помощью следующего кода:

const form = document.querySelector("#fileinfo");

form.addEventListener("submit", async (event) => {
  const formData = new FormData(form);

  formData.append("CustomField", "This is some extra data");

  const response = await fetch("stash.php", {
    method: "POST",
    body: formData,
  });
  event.preventDefault();
});

Примечание: Если вы передаёте ссылку на форму, метод HTTP запроса, указанный в форме, будет использоваться вместо метода, указанного в вызове open().

Предупреждение: При использовании FormData для отправки POST-запросов с помощью XMLHttpRequest или API Fetch с типом содержимого multipart/form-data (например, при загрузке файлов и blobs на сервер), не устанавливайте явно заголовок Content-Type запроса. Это предотвратит возможность браузеру установить заголовок Content-Type с выражением границы, которое он будет использовать для разграничения полей формы в теле запроса.

Вы также можете добавить File или Blob непосредственно в объект FormData, как показано ниже:

data.append("myfile", myBlob, "filename.txt");

При использовании метода append() можно использовать третий необязательный параметр для передачи имени файла в заголовок Content-Disposition , который отправляется на сервер. Если имя файла не указано (или параметр не поддерживается), используется имя «blob».

Использование события `formdata`

Событие formdata, более новое, чем объект FormData, генерируется на объекте HTMLFormElement после построения списка элементов, представляющего данные формы. Это происходит при отправке формы, но также может быть вызвано вызовом конструктора FormData().

Это позволяет быстро получить объект FormData в ответ на срабатывание события formdata, вместо того чтобы создавать его самостоятельно.

Например, в JavaScript мы можем сослаться на форму:

const formElem = document.querySelector("form");

В обработчике события submit мы используем preventDefault для остановки стандартной отправки формы, а затем вызываем конструктор FormData() для запуска события formdata:

formElem.addEventListener("submit", (e) => {
  // on form submission, prevent default
  e.preventDefault();

  // construct a FormData object, which fires the formdata event
  new FormData(formElem);
});

Когда срабатывает событие formdata , мы можем получить доступ к объекту FormData с помощью FormDataEvent.formData, а затем сделать с ним что-то (ниже мы отправляем его на сервер с помощью XMLHttpRequest).

formElem.addEventListener("formdata", (e) => {
  console.log("formdata fired");

  // Get the form data from the event object
  const data = e.formData;
  for (const value of data.values()) {
    console.log(value);
  }

  // Submit the data via fetch()
  fetch("/formHandler", {
    method: "POST",
    body: data,
  });
});

Особенности

Объект FormData не включает данные из полей, которые отключены, или из наборов полей, которые отключены.

См. также

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects

Создание объекта FormData с нуля

Получение объекта FormData из HTML-формы