GlobalFetch.fetch()

La méthode fetch() du mixin WindowOrWorkerGlobalScope démarre le chargement d'une ressource sur le réseau et retourne une promesse qui est résolue dès que la réponse est disponible. La promesse résoud l'objet Response représentant la réponse de votre requête. Cette promesse n'échoue pas en cas d'erreur HTTP, elle n'échoue que sur les problèmes de réseau. Vous devez utiliser un gestionnaire then pour identifier les erreurs HTTP.

WindowOrWorkerGlobalScope est aussi bien implémenté par Window que par WorkerGlobalScope, ce qui signifie que la méthode fetch() est disponible dans la plupart des cas où vous pourriez en avoir besoin.

Une promesse fetch() n'est rejetée que quand un problème de réseau est rencontré, même si en réalité cela signifie généralement qu'il y a un problème de permissions ou quelque chose de similaire. La promesse ne sera pas rejetée en cas d'erreur HTTP (404, etc.) Pour cela, un gestionnaire then() doit vérifier que la propriété Response.ok ait bien pour valeur true et/ou la valeur de la propriété Response.status.

La méthode fetch() est contrôlée par la directive connect-src de l'entête Content Security Policy plutôt que par la directive de la ressource qui est récupérée.

Les paramètres de la méthode fetch() sont identiques à ceux du contructeur d'une Request().

Syntaxe

const fetchResponsePromise = Promise<Response> fetch(entrée[, init]);

Paramètres

entrée
Définit la ressource que vous voulez obtenir. Cela peut être :
  • Un USVString qui contient l'URL de la ressource à obtenir. Certains navigateurs acceptent blob: et data:.
  • Un objet Request.
init Facultatif

Un objet qui contient les paramètres de votre requête. Les options possibles sont :

method
La méthode de la requête, par exemple GET ou POST.
headers
Les entêtes à ajouter à votre requête, contenues dans un objet Headers ou dans un objet avec des ByteString pour valeurs.
body
Le corps de votre requête. Cela peut être un Blob, un BufferSource, un FormData, un URLSearchParams, ou un USVString. Notez cependant qu'une requête avec GET ou HEAD pour méthode ne peut pas avoir de corps.
mode
Le mode à utiliser pour cette requête, par exemple cors, no-cors, ou same-origin.
credentials
Les identifiants à utiliser pour cette requête : omit, same-origin, ou include. Pour envoyer automatiquement les cookies pour le domaine actuel, cette option doit être définie. À partir de Chrome 50, cette propriété peut aussi prendre un objet FederatedCredential ou une instance de PasswordCredential.
cache
Le comportement du cache pour cette requête : default, no-store, reload, no-cache, force-cache, ou only-if-cached.
redirect
Le mode de redirection à adopter pour cette requête : follow (suivre les redirections automatiquement), error (abandonner avec une erreur si une redirection a lieu), ou manual (gérer les redirections manuellement). Dans Chrome, la valeur par défaut était follow avant Chrome 47, mais à partir de cette version, c'est manual.
referrer
Un USVString qui vaut no-referrerclient, ou qui contient une URL. La valeur par défaut est client.
referrerPolicy
Spécifie la valeur de l'entête HTTP referer. Cela peut être no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin ou unsafe-url.
integrity
Contient la valeur de l'intégrité de la sous-ressource de la requête (par exemple, sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).
keepalive
Peut être utilisée pour autoriser la requête à se poursuivre après la fermeture de la page. Une requête avec ce paramètre est équivalente à l'API Navigator.sendBeacon().
signal
Une instance de AbortSignal vous permettant de communiquer avec une requête et de l'interrompre si vous le souhaitez via un AbortController.

Valeur retournée

Une Promise qui se résoud avec un object Response.

Exceptions

AbortError
La requête a été interrompue à cause d'un appel à la méthode abort() de AbortController.
TypeError
L'URL spécifié inclut des identifiants. Ces informations devraient plutôt être fournises via l'en-tête HTTP Authorization.

Exemple

Dans notre exemple de requête avec fetch (voir cet exemple en direct) nous créons une nouvelle Request avec le constructeur correspondant, puis on l'envoie en appellant fetch(). Comme nous récupérons une image, nous utilisons la méthode Body.blob() sur la réponse pour lui donner le bon type MIME pour qu'elle soit gérée correctement, puis l'on crée l'URL correspondant à cet objet et on l'affiche dans un élément <img>.

const monImage = document.querySelector('img');

let maRequete = new Request('fleurs.jpg');

fetch(maRequete)
.then(function(reponse) {
  if (!response.ok) {
    throw new Error(`erreur HTTP! statut: ${reponse.status}`);
  }
  return reponse.blob();
})
.then(function(reponse) {
  let URLobjet = URL.createObjectURL(reponse);
  monImage.src = URLobjet;
});

Dans notre exemple fetch avec initialisation et requête (voir cet exemple en direct) nous faisons la même chose à la différence que nous passons aussi un objet d'initalisation à la méthode fetch :

const monImage = document.querySelector('img');

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

const monInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

let maRequete = new Request('fleurs.jpg');

fetch(maRequete, monInit).then(function(reponse) {
  ... 
});

Notez que vous pouvez aussi passer l'objet d'initialisation au constructeur de la requête pour obtenir le même effet, par exemple :

let maRequete = new Request('fleurs.jpg', monInit);

Vous pouvez aussi utiliser un objet litéral comme en-têtes dans votre objet d'initalisation.

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

let maRequete = new Request('fleurs.jpg', monInit);

Spécifications

Specification Statut Commentaire
Fetch
La définition de 'fetch()' dans cette spécification.
Standard évolutif Définie dans un WindowOrWorkerGlobalScope dans la nouvelle spécification.
Fetch
La définition de 'fetch()' dans cette spécification.
Standard évolutif Définition initiale
Credential Management Level 1 Version de travail Ajoute la possiblité d'utiliser une instance de FederatedCredential ou de PasswordCredential comme valeur de init.credentials.

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung Internet
fetch
Expérimentale
Chrome Support complet 42Edge Support complet 14Firefox Support complet 39
Support complet 39
Support complet 34
Désactivée
Désactivée From version 34: this feature is behind the dom.fetch.enable preference. To change preferences in Firefox, visit about:config.
Support complet 52
Notes
Notes fetch() now defined on WindowOrWorkerGlobalScope mixin.
IE Aucun support NonOpera Support complet 29
Support complet 29
Support complet 28
Désactivée
Désactivée From version 28: this feature is behind the Experimental Web Platform Features preference.
Safari Support complet 10.1WebView Android Support complet 42Chrome Android Support complet 42Firefox Android Support complet 39
Support complet 39
Support complet 34
Désactivée
Désactivée From version 34: this feature is behind the dom.fetch.enable preference. To change preferences in Firefox, visit about:config.
Support complet 52
Notes
Notes fetch() now defined on WindowOrWorkerGlobalScope mixin.
Opera Android Support complet 29
Support complet 29
Support complet 28
Désactivée
Désactivée From version 28: this feature is behind the Experimental Web Platform Features preference.
Safari iOS Support complet 10.3Samsung Internet Android Support complet 4.0
Support for blob: and data:
Expérimentale
Chrome Support complet 48Edge Support complet 79Firefox ? IE Aucun support NonOpera ? Safari ? WebView Android Support complet 43Chrome Android Support complet 48Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android Support complet 5.0
referrerPolicyChrome Support complet 52Edge Support complet 79Firefox Support complet 52IE Aucun support NonOpera Support complet 39Safari Support complet 11.1WebView Android Support complet 52Chrome Android Support complet 52Firefox Android Support complet 52Opera Android Support complet 41Safari iOS Aucun support NonSamsung Internet Android Support complet 6.0
signal
Expérimentale
Chrome Support complet 66Edge Support complet 16Firefox Support complet 57IE Aucun support NonOpera Support complet 53Safari Support complet 11.1WebView Android Support complet 66Chrome Android Support complet 66Firefox Android Support complet 57Opera Android Support complet 47Safari iOS Support complet 11.3Samsung Internet Android Support complet 9.0
Streaming response body
Expérimentale
Chrome Support complet 43Edge Support complet 14Firefox Support complet Oui
Désactivée
Support complet Oui
Désactivée
Désactivée This feature is behind the dom.streams.enabled preference and the javascript.options.streams preference. To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 29Safari Support complet 10.1WebView Android Support complet 43Chrome Android Support complet 43Firefox Android Aucun support NonOpera Android Aucun support NonSafari iOS Support complet 10.3Samsung Internet Android Support complet 4.0

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Voir les notes d'implémentation.
Voir les notes d'implémentation.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.

Voir aussi