HTMLImageElement.referrerPolicy — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.referrerPolicy

Beschreibung

Die Eigenschaft referrerPolicy spiegelt das HTML-Attribut referrerpolicy eines <img>-Elements wider. Sie bestimmt, ob und in welchem Umfang der Referer-HTTP-Header gesendet wird, wenn der Browser die Bildressource (src bzw. srcset) anfordert.

Das ist vor allem für Datenschutz und Sicherheit wichtig: Enthält die URL der aktuellen Seite sensible Daten wie Sitzungs-IDs, Suchbegriffe oder Token in der Query, können diese über den Referrer an fremde Bild-Hosts (CDNs, Tracking-Pixel, externe Avatare) gelangen. Mit einer strengeren Richtlinie wie "no-referrer" oder "strict-origin" lässt sich das pro Bild verhindern, ohne die Richtlinie der ganzen Seite zu ändern.

Umgekehrt kann eine lockerere Richtlinie nötig sein, wenn ein Bildserver Hotlink-Schutz über den Referrer prüft und die vollständige Herkunfts-URL erwartet.

Mögliche Werte:

"" (leer) – keine eigene Richtlinie; es gilt die Richtlinie des Dokuments (Standard ist strict-origin-when-cross-origin).
"no-referrer" – es wird kein Referer-Header gesendet.
"no-referrer-when-downgrade" – vollständige URL, außer bei HTTPS → HTTP.
"origin" – nur der Ursprung (Schema, Host, Port).
"origin-when-cross-origin" – vollständige URL bei gleichem Ursprung, sonst nur der Ursprung.
"same-origin" – Referrer nur bei gleichem Ursprung, sonst keiner.
"strict-origin" – nur der Ursprung, bei HTTPS → HTTP gar nichts.
"strict-origin-when-cross-origin" – vollständige URL bei gleichem Ursprung, Ursprung bei Cross-Origin, nichts bei Downgrade.
"unsafe-url" – immer die vollständige URL (ohne Fragment und Zugangsdaten), auch bei Downgrade.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: einer der gültigen Richtlinienwerte, z. B. `"no-referrer"` oder `"origin"`. Ungültige Werte werden beim Lesen als `""` zurückgegeben.

Rückgabewert

Typ

string

Beschreibung

Die aktuell gesetzte Referrer-Richtlinie als Zeichenkette in Kleinbuchstaben oder "", wenn keine (gültige) Richtlinie gesetzt ist.

Beispiele

Externes Bild ohne Referrer laden

// Avatar von einem Fremd-Host laden, ohne die aktuelle Seiten-URL preiszugeben
const avatar = new Image(64, 64);
avatar.referrerPolicy = 'no-referrer';
avatar.alt = 'Profilbild';
avatar.src = 'https://cdn.example.org/avatars/42.png';
document.body.append(avatar);

console.log(avatar.referrerPolicy);
console.log(avatar.getAttribute('referrerpolicy'));

no-referrer no-referrer

Richtlinie aus dem HTML-Attribut auslesen

// HTML: <img id="logo" src="/logo.svg" referrerpolicy="origin" alt="Logo">
//       <img id="banner" src="/banner.jpg" alt="Banner">
const logo = document.getElementById('logo');
const banner = document.getElementById('banner');

console.log(logo.referrerPolicy);
console.log(JSON.stringify(banner.referrerPolicy)); // keine eigene Richtlinie

origin ""

Alle Drittanbieter-Bilder nachträglich absichern

// Richtlinie für Bilder fremder Herkunft verschärfen – VOR dem Setzen von src,
// sonst ist die Anfrage evtl. schon unterwegs
const addImage = (url, alt) => {
  const img = document.createElement('img');
  const isCrossOrigin = new URL(url, location.href).origin !== location.origin;
  img.referrerPolicy = isCrossOrigin ? 'strict-origin' : 'strict-origin-when-cross-origin';
  img.alt = alt;
  img.src = url;
  return img;
};

const img = addImage('https://images.example.com/foto.jpg', 'Foto');
document.querySelector('#galerie')?.append(img);
console.log(img.referrerPolicy);

strict-origin

Ungültige Werte erkennen

const img = document.createElement('img');
img.referrerPolicy = 'kein-referrer'; // Tippfehler
console.log(JSON.stringify(img.referrerPolicy));
console.log(img.getAttribute('referrerpolicy'));

"" kein-referrer

// Wichtig · Fallstricke

Reihenfolge beachten: referrerPolicy vor src/srcset setzen. Wird die Richtlinie erst danach geändert, kann die Anfrage bereits mit der alten Richtlinie gesendet worden sein; eine nachträgliche Änderung startet keinen neuen Ladevorgang, solange sich die Quelle nicht ändert.
Ungültige Werte werden stillschweigend ignoriert: Das Attribut behält den Text, die Eigenschaft liefert "", und es gilt die Dokument-Richtlinie. Groß-/Kleinschreibung im Attribut ist egal, zurückgegeben wird Kleinschreibung.
Die Richtlinie pro Element hat Vorrang vor der Dokument-Richtlinie (Referrer-Policy-Header oder <meta name="referrer">).
Datenschutz: "unsafe-url" kann sensible Pfade und Query-Parameter an Fremdserver übertragen, auch über unverschlüsseltes HTTP – nur einsetzen, wenn es wirklich nötig ist.
Hotlink-Schutz: Manche Bildserver lehnen Anfragen ohne Referrer ab. "no-referrer" kann dann zu fehlerhaft geladenen Bildern führen (error-Event).
Kompatibilität: in allen aktuellen Browsern unterstützt, ältere Safari-Versionen (vor 14) haben die Eigenschaft nur teilweise. Der Standardwert der Dokument-Richtlinie wurde in modernen Browsern auf strict-origin-when-cross-origin umgestellt.

Siehe auch

Document.referrer HTMLImageElement.fetchPriority HTMLImageElement.currentSrc HTMLImageElement.border HTMLImageElement.decoding