WindowOrWorkerGlobalScope.fetch()

Il metodo fetch() del mixin WindowOrWorkerGlobalScope avvia il processo di recupero di una risorsa dalla rete. Questo ritorna una "promise" che si risolve all'oggetto Response che rappresenta la risposta alla tua richiesta.

WorkerOrGlobalScope è implementato sia da Window sia da WorkerGlobalScope, ciò significa che il metodo fetch() è disponibile in quasi tutti i contesti nei quali potresti voler recuperare risorse..

Una promise fetch() responge con un TypeError quando viene incontrato un errore di rete, sebbene questo stia spesso a significare un errore di permessi o simili. Un controllo accurato per un fetch() di successo richiederebbe di controllare che la promise si sia risolta,  e anche il controllo che la propriet√† Response.ok ha valore true. Uno stato HTTP 404 non costituisce un errore di rete.

Il metodo fetch() è controllato dalla direttiva connect-src della Content Security Policy piuttosto che dalla direttiva delle risorse che sta recuperando.

Nota: I parametri del metodo fetch() sono identici a quelli del costruttore Request().

Sintassi

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

Parametri

input
Definisce la risorsa ceh vuoi recuperare. Questa può essere:
  • Una USVString contenente l'URL diretto della risorsa che vuoi recuperare. Alcuni browsers accettano blob: e data: come schemi.
  • Un oggetto Request.
init Optional
Un oggetto opzioni contenente qualsiasi impostazione personalizzata che si vuole applicare alla richiesta. Le opzioni possibili sono:
  • method: Il metodo di richiesta, es., GET, POST.
  • headers: Qualsiasi header si voglia aggiungere alla richiesta, contenuto in un oggetto Headers o un oggetto letterale con valori ByteString.
  • body: Qualsiasi corpo si voglia aggiungere alla richiesta: pu√≤ essere un oggetto Blob, BufferSource, FormData, URLSearchParams, o USVString. Si noti che una richiesta che usa il metodo GET o HEAD non pu√≤ avere un corpo.
  • mode: La modalit√† che si vuole usare per la richiesta, es., cors, no-cors, o same-origin.
  • credentials: Le credenziali che si vuole vengano usate per la richiesta: omit, same-origin, o include. Per inviare automaticamente dei cookies per il dominio corrente, questa opzione deve essere indicata. Iniziando da Chrome 50, questa propriet√† accetta anche un'istanza FederatedCredential o PasswordCredential.
  • cache: La modalit√† cache ceh si vuole usare per la richiesta: default, no-store, reload, no-cache, force-cache, o only-if-cached.
  • redirect: Il metodo di reindirizzamento: follow (seguire automaticamente i reindirizzamenti), error (interrompere con un errore se avviene un reindirizzamento), o manual (gestire manualmente i reindirizzamento). In Chrome il valore di default √® follow (prima di Chrome 47 era impostato a manual).
  • referrer: Una USVString che specifica no-referrerclient, o una URL. Il valore predefinito √® client.
  • referrerPolicy: Specifica il valore dello header HTTP del referente. Pu√≤ essere: no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url.
  • integrity: Contiene il valore di integrit√† della sottorisorsa (subresource integrity) della richiesta (es., sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).
  • keepalive: L'opzione keepalive pu√≤ essere usata per premettere alla richiesta di sopravvivere alla pagina. Il recupero di una risorsa con l'opzione keepalive sostituisce l'API Navigator.sendBeacon()
  • signal: Un'istanza oggetto AbortSignal; permette di comunicare con una richiesta di recupero e di interromperla se lo si desidera con un AbortController.

Valore di ritorno

Una Promise che risolve ad un oggetto Response.

Eccezioni

Tipo Descrizione
AbortError La richiesta è stata interrotta (tramite AbortController.abort()).
TypeError Da Firefox 43, fetch() produrrà un TypeError se la URL possiede credenziali, come http://user:password@example.com.

Esempi

Nel nostro esempio Fetch Request (vedi Fetch Request live) viene creata un nuovo oggetto Request usando il costruttore relativo, per poi recuperarlo con una chiamata fetch(). Siccome stiamo recuperando un'immagine, eseguiamo Body.blob() alla risposta per dargli il tipo MIME adeguato in modo che venga gestito correttamente, poi creiamo un Oggetto URL dello stesso e lo mostriamo in un elemento <img>.

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;
});

Nel nostro esempio Fetch with init then Request (vedi Fetch Request init live) facciamo la stessa cosa eccetto che passiamo un oggetto per l'inizializzazione quando invochiamo fetch():

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

Si noti che si può passare l'oggetto per l'inizializzazione insieme al costruttore Request per ottenere lo stesso effetto, es.:

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

Si può anche usare un oggetto letterale come headers in init.

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

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

Specificazioni

Specificazioni Status Comment
Fetch
The definition of 'fetch()' in that specification.
Living Standard Definito in un WindowOrWorkerGlobalScope parziale nella specifica pi√Ļ recente.
Fetch
The definition of 'fetch()' in that specification.
Living Standard Definizione iniziale
Credential Management Level 1 Working Draft Aggiunge l'istanza FederatedCredential o PasswordCredential com un valore possibile per init.credentials.

Compatibilità Browser

BCD tables only load in the browser

Vedi anche