HTMLIFrameElement.sandbox — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLIFrameElement.sandbox

Beschreibung

Die Eigenschaft sandbox spiegelt das HTML-Attribut sandbox eines <iframe> als DOMTokenList wider. Ist das Attribut vorhanden, gelten für den eingebetteten Inhalt alle Einschränkungen: kein Skript, keine Formularübermittlung, keine Pop-ups, eine eindeutige „opake“ Herkunft (opaque origin), keine Navigation des obersten Fensters usw. Jedes Token wie allow-scripts oder allow-forms hebt gezielt eine dieser Einschränkungen auf.

Die Eigenschaft selbst ist schreibgeschützt, die Liste ist aber live: Mit add(), remove(), toggle() und replace() änderst du direkt das zugrunde liegende Attribut. Mit supports() prüfst du, ob der Browser ein bestimmtes Token kennt. Wird der Eigenschaft ein String zugewiesen, landet er (wie bei classList) über [PutForwards=value] im Attribut.

Einsatzgebiete sind vor allem das Einbetten nicht vertrauenswürdiger Inhalte: Werbung, Nutzer-HTML, Code-Spielwiesen, Vorschauen von E-Mails oder Widgets Dritter. Grundsatz: so wenige Tokens wie möglich freigeben.

Wichtig: Änderungen an den Sandbox-Tokens wirken erst bei der nächsten Navigation des iframes. Ein bereits geladenes Dokument behält seine Einschränkungen, bis src bzw. srcdoc neu geladen wird.

Rückgabewert

Typ

DOMTokenList

Beschreibung

Live-Liste der Sandbox-Tokens, z. B. allow-scripts, allow-forms, allow-popups, allow-same-origin, allow-modals, allow-downloads, allow-top-navigation-by-user-activation. Ist das Attribut nicht gesetzt, ist die Liste leer (length === 0); ohne Attribut gilt aber keine Sandbox.

Beispiele

Sandbox-iframe für Nutzer-HTML erzeugen

const frame = document.createElement('iframe');
// Leeres Attribut = maximale Einschränkung
frame.setAttribute('sandbox', '');
// Nur Skripte erlauben, KEIN allow-same-origin
frame.sandbox.add('allow-scripts');
frame.srcdoc = '<p>Hallo</p><script>document.body.append(" – Skript läuft")<\/script>';
document.body.append(frame);

console.log(frame.sandbox.value);
console.log(frame.getAttribute('sandbox'));

allow-scripts allow-scripts

Token-Unterstützung prüfen

const frame = document.createElement('iframe');
const tokens = ['allow-downloads', 'allow-modals', 'allow-foo'];

for (const token of tokens) {
  console.log(token, frame.sandbox.supports(token));
}

allow-downloads true allow-modals true allow-foo false

Rechte umschalten und iframe neu laden

const frame = document.querySelector('iframe#vorschau');

const setFormsAllowed = (erlaubt) => {
  frame.sandbox.toggle('allow-forms', erlaubt);
  // Änderung greift erst nach erneuter Navigation
  frame.src = frame.src;
};

setFormsAllowed(true);
console.log(frame.sandbox.contains('allow-forms'));

true

Aktuelle Tokens auflisten

const frame = document.createElement('iframe');
frame.sandbox = 'allow-scripts allow-popups';

console.log(frame.sandbox.length);
console.log([...frame.sandbox]);

2 ["allow-scripts", "allow-popups"]

// Wichtig · Fallstricke

Sicherheit: Die Kombination allow-scripts + allow-same-origin bei Inhalten derselben Herkunft hebelt die Sandbox aus: Das eingebettete Skript kann das sandbox-Attribut seines eigenen iframes über parent entfernen und sich neu laden. Nutze diese Kombination nur für fremde Herkunft.
Leere Liste ≠ keine Sandbox: Eine leere DOMTokenList kann „Attribut fehlt“ (keine Einschränkung) oder sandbox=\"\" (volle Einschränkung) bedeuten. Prüfe mit frame.hasAttribute('sandbox').
Verzögerte Wirkung: Änderungen gelten erst nach der nächsten Navigation des iframes.
Die Sandbox ersetzt keine serverseitige Absicherung. Ergänzend lassen sich Content-Security-Policy: sandbox (HTTP-Header) und das Attribut allow (Permissions Policy) einsetzen.
Inhalte in einer Sandbox ohne allow-same-origin haben eine opake Herkunft: localStorage, Cookies und postMessage mit fester Ziel-Herkunft funktionieren anders; der Empfänger sieht event.origin === \"null\".
Kompatibilität: In allen aktuellen Browsern unterstützt; supports() für neuere Tokens wie allow-downloads oder allow-top-navigation-to-custom-protocols verwenden.

Siehe auch

HTMLIFrameElement DOMTokenList DOMTokenList.prototype.supports() HTMLIFrameElement.srcdoc HTMLIFrameElement.allow Window.prototype.postMessage() Element.classList