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

Объект FormData позволяет создать набор пар ключ/значение и передать их, используя XMLHttpRequest. Объект FormData предназначен для передачи данных форм, однако может быть использован для передачи пар ключ/значение независимо от форм. Данные передаются в том же формате, как и данные, передаваемые методом submit() формы, с установленной кодировкой enctype="multipart/form-data".

Создание объекта FormData

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

var formData = new FormData();

formData.append("username", "Groucho");
formData.append("accountnum", 123456); // число 123456 немедленно преобразуется в строку "123456"

// Файл, выбранный пользователем
formData.append("userfile", fileInputElement.files[0]);

// JavaScript Blob объект
var content = '<a id="a"><b id="b">hey!</b></a>'; // содержимое нового файла...
var blob = new Blob([content], { type: "text/xml" });

formData.append("webmasterfile", blob);

var request = new XMLHttpRequest();
request.open("POST", "http://foo.com/submitform.php");
request.send(formData);

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

Данный пример показывает создание экземпляра FormData, содержащего поля "username", "accountnum", "userfile" и "webmasterfile". Экземпляр FormData затем отправляется при помощи метода send() объекта XMLHttpRequest. Поле "webmasterfile" является экземпляром класса Blob. Объект класса Blob является файлом-подобным объектом, содержащим "сырые" данные. Определение данных как Blob не является обязательным в нативном javascript. ИнтерфейсFileбазируется на Blob, наследуя его функциональность и расширяя его для поддержки файлов в ОС пользователя. Для создания объектов класса Blob используйте Blob() constructor.

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

Для создания объекта FormDatа, содержащего данные существующей формы (<form>) передайте форму в качестве аргумента при создании объекта FormData:

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

var formData = new FormData(someFormElement);

Например:

var formElement = document.querySelector("form");
var request = new XMLHttpRequest();
request.open("POST", "submitform.php");
request.send(new FormData(formElement));

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

var formElement = document.querySelector("form");
var formData = new FormData(formElement);
var request = new XMLHttpRequest();
request.open("POST", "submitform.php");
formData.append("serialnumber", serialNumber++);
request.send(formData);

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

Отправка файлов при помощи объекта FormData

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

html

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

Затем вы сможете отправить выбранный файл следующим образом:

var form = document.forms.namedItem("fileinfo");
form.addEventListener(
  "submit",
  function (ev) {
    var oOutput = document.querySelector("div"),
      oData = new FormData(form);

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

    var oReq = new XMLHttpRequest();
    oReq.open("POST", "stash.php", true);
    oReq.onload = function (oEvent) {
      if (oReq.status == 200) {
        oOutput.innerHTML = "Uploaded!";
      } else {
        oOutput.innerHTML =
          "Error " +
          oReq.status +
          " occurred when trying to upload your file.<br />";
      }
    };

    oReq.send(oData);
    ev.preventDefault();
  },
  false,
);

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

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

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

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

Вы так же можете использовать FormData с jQuery:

var fd = new FormData(document.querySelector("form"));
fd.append("CustomField", "This is some extra data");
$.ajax({
  url: "stash.php",
  type: "POST",
  data: fd,
  processData: false, // Сообщить jQuery не передавать эти данные
  contentType: false, // Сообщить jQuery не передавать тип контента
});

Отправка форм и файлов при помощи AJAX без использования объекта `FormData`

Если вы заинтересованы в отправке форм и файлов при помощи AJAX без использования FormData, прочитайте /ru/docs/Web/API/XMLHttpRequest_API/Using_XMLHttpRequest#Submitting_forms_and_uploading_files

Смотрите также

Help improve MDN

Learn how to contribute

This page was last modified on ⁨24 мар. 2025 г.⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content