fetch()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

El método fetch() lanza el proceso de solicitud de un recurso de la red. Esto devuelve una promesa que resuelve al objeto Response que representa la respuesta a la solicitud realizada.

Tanto Window como WorkerGlobalScope implementan WorkerOrGlobalScope, por lo que el método fetch() está disponible en prácticamente cualquier contexto desde el que se pueda necesitar solicitar un recurso.

Una promesa fetch() se rechaza con un TypeError cuando sucede un error en la red, aunque normalmente significa un tema de permisos o similar. Una comprobación más precisa de una solicitud con fetch() debería comprobar que la promesa se resuelve, y que la propiedad Response.ok tiene valor true. Un estatus HTTP 404 no constituye un error de red.

El método fetch() es controlado por la directiva connect-src de la Política de Seguridad de Contenido (Content Security Policy) en lugar de la directiva del recurso que se solicita.

Nota: Los parámetros del método fetch() son indénticos a los del constructor de Request().

Sintaxis

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

Parámetros

input

Define el recurso que se quiere solicitar. Puede ser:

Un USVString con la URL del recurso a solicitar. Algunos navegadores aceptan los esquemas blob: y data:.
Un objeto Request.

init Opcional

Objeto de opciones que contiene configuraciones para personalizar la solicitud. Estas opciones pueden ser:

method: El método de solicitud, p.ej., GET, POST.
headers: Cualquier cabecera que se quiera añadir a la solicitud, contenidas en un objeto Headers o un objeto literal con valores ByteString.
body: Cualquier cuerpo que se quiera añadir a la solicitud: puede ser un Blob, BufferSource, FormData, URLSearchParams, u objeto USVString. Nótese que las solicitudes con métodos GET o HEAD no pueden tener cuerpo.
mode: El modo a usar en la solicitud, p.ej., cors, no-cors, o same-origin.
credentials: Las credenciales que se quieran utilizar para la solicitud: omit, same-origin, o include. Para enviar automáticamente las cookies del dominio actual, debe indicarse esta opción. Desde Chrome 50, esta propiedad también acepta una instancia de FederatedCredential o de PasswordCredential.
cache: El modo de caché a utilizar en la solicitud: default, no-store, reload, no-cache, force-cache, o only-if-cached.
redirect: El modo de redirección a usar: follow (seguir redirecciones automáticamente), error (abortar si sucede un error durante la redirección), o manual (gestionar redirecciones manualmente). El valor por defecto en Chrome es follow (hasta la versión 46 era manual).
referrer: Un USVString que especifique no-referrer, client, o una URL. El valor por defecto es client.
referrerPolicy: Especifica el valor de la cabecera HTTP referer. Puede ser no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url.
integrity: Contiene el valor de integridad de subrecurso (subresource integrity) de la solicitud (p.ej., sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).
keepalive: La opción keepalive se puede usar para permitir que recurso dure más que la página. Las solicitudes con el indicador keepalive son un reemplazo de la API Navigator.sendBeacon().
signal: Una instancia de objeto AbortSignal; permite comunicarse con con una solicitud vigente y abortarla si se desea via AbortController.

Return value

Una Promise que resuelve a un objeto Response.

Excepciones

Tipo	Descriptción
`AbortError`	Se abortó la solicitud (mediante `AbortController.abort()`).
`TypeError`	Desde Firefox 43, `fetch()` lanza un `TypeError` si la URL tiene credenciales, como en `http://usuario:clave@ejemplo.com`.

Ejemplo

En el ejemplo de solicitud con Request (ver Fetch Request live) creamos un nuevo objeto Request usando el constructor pertinente, y realizamos una solicitud usando fetch(). Dado que estamos solicitando una imagen, ejecutamos Body.blob() en la respuesta para darle el tipo MIME correspondiente para que sea gestionada apropiadamente, luego creamos un objeto URL de ella para mostrarla en un elemento <img>.

var miImagen = document.querySelector("img");

var miSolicitud = new Request("flores.jpg");

fetch(miSolicitud)
  .then(function (respuesta) {
    return respuesta.blob();
  })
  .then(function (respuesta) {
    var objeto = URL.createObjectURL(respuesta);
    miImagen.src = objeto;
  });

En el ejemplo de solicitud con inicializador y Request (ver Fetch Request init live) hacemos lo mismo pero además pasamos un objeto inicializador cuando invocamos el fetch():

var miImagen = document.querySelector('img');

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

var miInicializador = { method: 'GET',
                        headers: misCabeceras,
                        mode: 'cors',
                        cache: 'default' };

var miSolicitud = new Request('flores.jpg');

fetch(miSolicitud,miInicializador).then(function(respuesta) {
  ...
});

Nótese que también podríamos pasar el objeto inicializador con el constructor de Request para conseguir el mismo efecto, p.ej.:

var miSolicitud = new Request("flores.jpg", miInicializador);

También se puede usar un objeto literal a modo de headers en init.

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

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

Especificaciones

Specification
Fetch Standard # fetch-method

Compatibilidad con navegadores

BCD tables only load in the browser