Request.mode — Eigenschaft · JavaScript-Referenz

Signatur

get Request.prototype.mode

Beschreibung

Die Eigenschaft Request.mode gibt an, nach welchen Regeln ein Request ursprungsübergreifend (Cross-Origin) behandelt wird. Der Modus bestimmt, ob eine Anfrage an eine fremde Herkunft überhaupt erlaubt ist, ob CORS-Header ausgewertet werden und ob die Antwort für JavaScript lesbar ist.

"cors": Cross-Origin-Anfragen sind erlaubt, sofern der Server passende CORS-Header sendet. Standard für new Request() und fetch().
"no-cors": Nur „einfache“ Methoden (GET, HEAD, POST) und sichere Header sind zulässig. Die Antwort ist opaque (response.type === "opaque"): Status, Header und Body sind nicht lesbar.
"same-origin": Anfragen an eine fremde Herkunft schlagen mit einem TypeError fehl.
"navigate": Nur bei Seitennavigationen durch den Browser. Kann nicht selbst gesetzt werden, taucht aber z. B. im fetch-Event eines Service Workers auf.

Gesetzt wird der Modus über die Option mode im Konstruktor new Request(url, { mode }) oder direkt in fetch(url, { mode }). Die Eigenschaft selbst ist nur lesbar. Besonders nützlich ist sie in Service Workern: Dort unterscheidet man damit Navigationsanfragen (HTML-Seiten) von Anfragen nach Ressourcen wie Skripten oder Bildern.

Rückgabewert

Typ

"cors" | "no-cors" | "same-origin" | "navigate"

Beschreibung

Der Modus der Anfrage als String. Ohne Angabe im Konstruktor ist er "cors".

Beispiele

Standardmodus und explizit gesetzter Modus

const standard = new Request('https://api.example.com/daten');
console.log(standard.mode);

const lokal = new Request('/api/profil', { mode: 'same-origin' });
console.log(lokal.mode);

cors same-origin

Service Worker: Navigationen gesondert behandeln (Offline-Fallback)

// sw.js
self.addEventListener('fetch', (event) => {
  if (event.request.mode === 'navigate') {
    event.respondWith(
      (async () => {
        try {
          return await fetch(event.request);
        } catch {
          const cache = await caches.open('offline-v1');
          return cache.match('/offline.html');
        }
      })()
    );
  }
});

no-cors liefert eine undurchsichtige Antwort

const req = new Request('https://fremde-domain.example/pixel.gif', { mode: 'no-cors' });
console.log(req.mode);

const res = await fetch(req);
console.log(res.type, res.status, res.ok);

no-cors opaque 0 false

same-origin blockiert fremde Herkunft

try {
  await fetch('https://andere-domain.example/api', { mode: 'same-origin' });
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Kein CORS-Umweg: "no-cors" umgeht CORS nicht. Die Antwort ist opaque: status ist 0, Header und Body sind nicht zugänglich. Sinnvoll ist der Modus nur zum Cachen im Service Worker oder für Anfragen, bei denen man die Antwort nicht auswerten muss.
Einschränkungen bei no-cors: Nur GET, HEAD und POST sowie CORS-sichere Header (z. B. Content-Type nur mit einfachen Werten) sind erlaubt. Andere Methoden führen zu einem TypeError.
navigate ist nicht setzbar: new Request(url, { mode: 'navigate' }) wirft einen TypeError. Erstellt man aus einer Navigationsanfrage mit new Request(request) eine neue Anfrage, wird der Modus zu "same-origin".
Opaque-Antworten im Cache: Sie belegen in Chromium aus Sicherheitsgründen deutlich mehr Speicherkontingent (Padding), als ihre tatsächliche Größe beträgt.
Kompatibilität: Wird von allen modernen Browsern unterstützt. In Node.js ist die Eigenschaft ab Version 18 vorhanden (undici). Da es dort keine Same-Origin-Policy gibt, hat sie in Node.js kaum Wirkung.

Siehe auch

Request Request.credentials Response.type FetchEvent Request.destination PaymentRequest.id