Глобальная функция fetch()

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since март 2017 г..

* Some parts of this feature may have varying levels of support.

Примечание: Эта возможность доступна в Web Workers.

Глобальный метод fetch() запускает процесс извлечения ресурса из сети. Возвращает promise, содержащий Response объект (ответ на запрос).

Промис fetch() завершается TypeError, если возникает сетевая ошибка, хотя обычно это означает проблему с доступами или аналогичную ей. Для успешного завершения fetch() достаточно удостовериться в том, что промис выполнен и что свойство Response.ok имеет значение true. HTTP статус 404 не является сетевой ошибкой.

Метод fetch() контролируется директивой connect-src directive of Content Security Policy (политика безопасности контента), а не директивой ресурсов, которые извлекает.

Примечание: Аргументы метода fetch() идентичны аргументам Request() конструктора.

Синтаксис

Promise<Response> fetch(input[, init]);

Аргументы

input

Определяет желаемый для получения ресурс. Это может быть:

USVString (строка), содержащая прямую URL ссылку на ресурс. Некоторые браузеры принимают blob: и data: , как схемы.
Request объект (объект ответа).

init Необязательный

Объект с опциями, содержащий пользовательские настройки, которые вы желаете применить к запросу. Возможные варианты:

method: Метод запроса, например, GET, POST.
headers: Заголовки, содержащиеся в объекте Headers или в объекте литерале с побитовыми значениями (ByteString).
body: Тело запроса, которое может быть: Blob, BufferSource, FormData, URLSearchParams, или USVString объектами. Обратите внимание, что GET или HEAD запрос не может иметь тела.
mode: Режим, например, cors, no-cors или same-origin.
credentials: Полномочия: omit, same-origin или include. Для автоматической отправки куки для текущего домена, эта опция должна быть указана. Начиная с Chrome 50, это свойство также принимает экземпляр класса FederatedCredential или PasswordCredential.
cache: Режим кеширования запроса default, no-store, reload, no-cache, force-cache или only-if-cached.
redirect: Режим редиректа: follow (автоматически переадресовывать), error (прерывать перенаправление ошибкой) или manual (управлять перенаправлениями вручную). В Chrome по дефолту стоит follow (ранее, в Chrome 47, стояло manual).
referrer: USVString, определяющая no-referrer, client или a URL. Дефолтное значение - client.
referrerPolicy: Определяет значение HTTP заголовка реферера. Может быть: no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url.
integrity: Содержит значение целостности субресурсов (subresource integrity) запроса (например, sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).
keepalive: Эта опция может быть использована, чтобы разрешить запросу "пережить" страницу. Получение ресурсов с флагом keepalive - это альтернатива Navigator.sendBeacon() API.
signal: Экземпляр объекта AbortSignal; позволяет коммуницировать с fetch запросом и, если нужно, отменять его с помощью AbortController.

Возвращаемое значение

Promise, содержащий Response объект (ответ на запрос).

Исключения

ТипОписание

AbortError	Запрос был отменён (используя AbortController.abort()).
TypeError	Начиная с версии Firefox 43, fetch() завершится ошибкой TypeError, если URL имеет такие полномочия, как http://user:password@example.com.

Пример

В нашем Fetch Request примере (см. Fetch Request live) мы создаём новый объект Request (запроса), используя релевантный конструктор, а затем получаем его вызовом fetch(). Так как запрашиваемый ресурс - изображение, для того, чтобы присвоить ему подходящий MIME тип и обработать должным образом, мы применяем к ответу метод Body.blob(), после чего создаём для него Object URL и передаём её в элемент <img>.

js
var myImage = document.querySelector("img");

var myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then(function (response) {
    return response.blob();
  })
  .then(function (response) {
    var objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });

В нашем Fetch with init then Request примере (см. Fetch Request init live) мы делаем тоже самое, за исключением того, что передаём в качестве аргумента для fetch() объект init:

js
var myImage = document.querySelector('img');

var myHeaders = new Headers();
myHeaders.append('Content-Type', 'image/jpeg');

var myInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

var myRequest = new Request('flowers.jpg');

fetch(myRequest,myInit).then(function(response) {
  ...
});

Обратите внимание, что объект init в качестве аргумента можно передать и в конструктор Request для получения аналогичного результата, например:

var myRequest = new Request("flowers.jpg", myInit);

Допустимо использования объекта литерала в качестве headers в init.

js
var myInit = {
  method: "GET",
  headers: {
    "Content-Type": "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

var myRequest = new Request("flowers.jpg", myInit);