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

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support4214

39

341

522

No

29

283

10
Streaming response body4314 No No2910
Support for blob: and data:48 No ? No ? ?
referrerPolicy52 Yes ? No39 ?
signal ? ?57 No ? No
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support424214

39

341

522

?10 ?
Streaming response body434314 No No10 ?
Support for blob: and data:4343 No ? ? ? ?
referrerPolicy5252 ? ?39 ? ?
signal ? ? ?57 ? No ?

1. From version 34: this feature is behind the dom.fetch.enable preference. To change preferences in Firefox, visit about:config.

2. fetch() now defined on WindowOrWorkerGlobalScope mixin.

3. From version 28: this feature is behind the Experimental Web Platform Features preference.

Vedi anche

Tag del documento e collaboratori

Hanno collaborato alla realizzazione di questa pagina: iruy
Ultima modifica di: iruy,