Request.keepalive — Eigenschaft · JavaScript-Referenz

Signatur

Request.keepalive

Beschreibung

Die schreibgeschützte Eigenschaft keepalive eines Request-Objekts zeigt an, ob die Anfrage mit der Option keepalive: true erzeugt wurde. Ist das der Fall, bricht der Browser die Anfrage nicht ab, wenn der Nutzer die Seite verlässt, den Tab schließt oder das Dokument neu lädt. Ohne diese Option werden laufende fetch()-Anfragen beim Entladen der Seite normalerweise abgebrochen.

Gesetzt wird der Wert über das Optionsobjekt von new Request(url, { keepalive: true }) oder direkt über fetch(url, { keepalive: true }). Die Eigenschaft selbst kann danach nur noch ausgelesen werden. Wird ein Request aus einem anderen Request erzeugt, übernimmt er dessen keepalive-Wert, sofern er im Optionsobjekt nicht überschrieben wird.

Typische Anwendungsfälle sind Analyse- und Telemetriedaten, die beim Verlassen der Seite gesendet werden sollen (etwa in visibilitychange- oder pagehide-Handlern), das Speichern von Entwürfen oder Abmelde-Aufrufe. Gegenüber navigator.sendBeacon() bietet fetch mit keepalive mehr Kontrolle: beliebige HTTP-Methoden, eigene Header und Zugriff auf die Antwort, solange die Seite noch existiert.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Anfrage das Entladen der Seite überdauern darf, sonst false (Standardwert).

Beispiele

Wert auslesen

const normal = new Request('/api/status');
const dauerhaft = new Request('/api/log', { method: 'POST', keepalive: true });

console.log(normal.keepalive);
console.log(dauerhaft.keepalive);

false true

Telemetrie beim Verlassen der Seite senden

const sendeMetriken = () => {
  const daten = JSON.stringify({
    seite: location.pathname,
    verweildauer: Math.round(performance.now())
  });

  const req = new Request('/api/metrics', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: daten,
    keepalive: true
  });

  // Anfrage läuft weiter, auch wenn der Tab geschlossen wird
  fetch(req).catch(() => { /* Fehler ignorieren */ });
};

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') sendeMetriken();
});

keepalive beim Kopieren eines Requests

const original = new Request('/api/draft', {
  method: 'PUT',
  body: 'Entwurf',
  keepalive: true
});

// Übernimmt keepalive vom Original
const kopie = new Request(original);
// Überschreibt keepalive explizit
const ohne = new Request(original, { keepalive: false });

console.log(kopie.keepalive, ohne.keepalive);

true false

// Wichtig · Fallstricke

Größenlimit: Die Summe aller Bodys laufender keepalive-Anfragen ist auf 64 KiB begrenzt. Wird das überschritten, schlägt fetch() mit einem TypeError fehl – große Nutzlasten also vorher kürzen oder aufteilen.
Kein Streaming: Ein ReadableStream als Body ist in Kombination mit keepalive: true nicht erlaubt.
Antwort nicht garantiert: Ist die Seite bereits entladen, lässt sich die Antwort nicht mehr verarbeiten – keepalive eignet sich für „Fire-and-forget“-Anfragen.
Ereigniswahl: unload und beforeunload sind unzuverlässig (besonders mobil) und verhindern teils den Back-Forward-Cache. Besser visibilitychange oder pagehide verwenden.
CORS: Anfragen mit nicht einfachen Headern (z. B. Content-Type: application/json) lösen einen Preflight aus; einige ältere Chrome-Versionen unterstützten Preflight bei keepalive nicht.
Kompatibilität: Firefox unterstützt keepalive erst seit Version 133; in älteren Versionen ist die Eigenschaft undefined bzw. wird ignoriert. Als Fallback eignet sich navigator.sendBeacon().

Siehe auch

Request Request.signal PaymentRequest.shippingType Request.cache Request.duplex