Window: fetch() Methode

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.

Die fetch() Methode der Window Schnittstelle startet den Prozess des Abrufens einer Ressource aus dem Netzwerk und gibt ein Promise zurück, das erfüllt wird, sobald die Antwort verfügbar ist.

Das Promise wird mit dem Response Objekt aufgelöst, das die Antwort auf Ihre Anfrage darstellt.

Ein fetch()-Promise wird nur abgelehnt, wenn die Anfrage fehlschlägt, zum Beispiel wegen einer schlecht formatierten Anfrages-URL oder einem Netzwerkfehler. Ein fetch()-Promise wird nicht abgelehnt, wenn der Server mit HTTP-Statuscodes antwortet, die auf Fehler hinweisen (404, 504 usw.). Stattdessen muss ein then()-Handler die Eigenschaften Response.ok und/oder Response.status überprüfen.

Die fetch() Methode wird durch die connect-src Direktive der Content Security Policy gesteuert, anstatt durch die Direktive der Ressourcen, die abgerufen werden.

Hinweis: Die Parameter der fetch() Methode sind identisch mit denen des Request() Konstruktors.

Syntax

js
fetch(resource)
fetch(resource, options)

Parameter

resource

Dies definiert die Ressource, die Sie abrufen möchten. Dies kann entweder sein:

  • Ein String oder ein anderes Objekt mit einem stringifier — einschließlich eines URL Objekts — das die URL der Ressource bereitstellt, die Sie abrufen möchten. Die URL kann relativ zur Basis-URL sein, die in einem Fensterkontext das baseURI des Dokuments oder WorkerGlobalScope.location in einem Worker-Kontext ist.
  • Ein Request Objekt.
options Optional

Ein RequestInit Objekt, das benutzerdefinierte Einstellungen enthält, die Sie auf die Anfrage anwenden möchten.

Rückgabewert

Ein Promise, das in ein Response Objekt aufgelöst wird.

Ausnahmen

AbortError DOMException

Die Anfrage wurde abgebrochen aufgrund eines Aufrufs der AbortController abort() Methode.

NotAllowedError DOMException

Wird ausgelöst, wenn die Verwendung der Topics API ausdrücklich durch eine browsing-topics Berechtigungsrichtlinie untersagt ist und eine fetch()-Anfrage mit browsingTopics: true durchgeführt wurde.

TypeError

Kann aus folgenden Gründen auftreten:

Grund Fehlgeschlagene Beispiele
Durch eine Berechtigungspolicy blockiert Die Verwendung der Attribution Reporting API ist durch eine attribution-reporting Permissions-Policy blockiert, und eine fetch()-Anfrage wurde mit attributionReporting angegeben.
Ungültiger Header-Name. 
// Leerzeichen in "C ontent-Type"
const headers = {
  'C ontent-Type': 'text/xml',
  'Breaking-Bad': '<3',
};
fetch('https://example.com/', { headers });
Ungültiger Header-Wert. Das Header-Objekt muss genau zwei Elemente enthalten. 
const headers = [
  ['Content-Type', 'text/html', 'extra'],
  ['Accept'],
];
fetch('https://example.com/', { headers });
Ungültige URL oder Schema, oder die Verwendung eines Schemas, das von fetch nicht unterstützt wird, oder die Verwendung eines Schemas, das für einen bestimmten Anfragemodus nicht unterstützt wird. 
fetch('blob://example.com/', { mode: 'cors' });
URL enthält Anmeldeinformationen. 
fetch('https://user:password@example.com/');
Ungültige Referrer-URL. 
fetch('https://example.com/', { referrer: './abc\u0000df' });
Ungültige Modi (navigate und websocket). 
fetch('https://example.com/', { mode: 'navigate' });
Wenn der Request-Cache-Modus "only-if-cached" ist und der Anfragemodus anders als "same-origin" ist. 
fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors',
});
Wenn die Anfragemethode ein ungültiger Name-Token oder einer der verbotenen Header ist ('CONNECT', 'TRACE' oder 'TRACK'). 
fetch('https://example.com/', { method: 'CONNECT' });
Wenn der Anfragemodus "no-cors" ist und die Anfragemethode keine CORS-sichere Methode ist ('GET', 'HEAD' oder 'POST'). 
fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors',
});
Wenn die Anfragemethode 'GET' oder 'HEAD' ist und der Body nicht null oder undefiniert ist. 
fetch('https://example.com/', {
  method: 'GET',
  body: new FormData(),
});
Wenn fetch einen Netzwerkfehler auslöst.

Beispiele

In unserem Fetch Request Beispiel (siehe Fetch Request live) erstellen wir ein neues Request Objekt mit dem entsprechenden Konstruktor und rufen es dann mit einem fetch()-Aufruf ab. Da wir ein Bild abrufen, führen wir Response.blob() aus, um den richtigen MIME-Typ zu vergeben, damit es korrekt verarbeitet wird. Anschließend erstellen wir eine Objekt-URL davon und zeigen sie in einem <img> Element an.

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

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

window
  .fetch(myRequest)
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    return response.blob();
  })
  .then((response) => {
    myImage.src = URL.createObjectURL(response);
  });

In unserem Fetch Request mit init Beispiel (siehe Fetch Request init live) tun wir dasselbe, außer dass wir ein options Objekt übergeben, wenn wir fetch() aufrufen. In diesem Fall können wir einen Cache-Control Wert festlegen, um anzugeben, mit welcher Art von zwischengespeicherten Antworten wir einverstanden sind:

js
const myImage = document.querySelector("img");
const reqHeaders = new Headers();

// A cached response is okay unless it's more than a week old
reqHeaders.set("Cache-Control", "max-age=604800");

const options = {
  headers: reqHeaders,
};

// Pass init as an "options" object with our headers.
const req = new Request("flowers.jpg", options);

fetch(req).then((response) => {
  // ...
});

Sie könnten das init Objekt auch mit dem Request Konstruktor übergeben, um denselben Effekt zu erzielen:

js
const req = new Request("flowers.jpg", options);

Sie können auch ein Objektliteral als headers in init verwenden:

js
const options = {
  headers: {
    "Cache-Control": "max-age=60480",
  },
};

const req = new Request("flowers.jpg", options);

Spezifikationen

Specification
Fetch Standard
# fetch-method

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch