HTMLIFrameElement.src — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.src

Beschreibung

Die Eigenschaft src eines HTMLIFrameElement spiegelt das HTML-Attribut src wider. Sie enthält die Adresse des Dokuments, das im Inline-Frame angezeigt wird. Beim Lesen liefert sie immer eine absolute, aufgelöste URL, auch wenn im Attribut ein relativer Pfad steht. Wer den Rohwert braucht, nutzt getAttribute('src').

Wird src gesetzt, startet der Browser sofort eine Navigation im Frame und lädt den neuen Inhalt. Das eignet sich zum Beispiel für nachgeladene Widgets, Vorschaufenster, eingebettete Videos oder Karten, die erst bei Bedarf eingebunden werden. Ist das Laden abgeschlossen, wird am Element das Ereignis load ausgelöst.

Ist zusätzlich das Attribut srcdoc gesetzt, hat es Vorrang vor src. Fehlt src oder ist es leer, zeigt der Frame about:blank an. Beim Lesen gibt die Eigenschaft in diesem Fall einen leeren String zurück.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: absolute oder relative URL des einzubettenden Inhalts. Relative URLs werden gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

string

Beschreibung

Die vollständig aufgelöste URL aus dem Attribut src oder ein leerer String, wenn das Attribut fehlt.

Beispiele

Aufgelöste URL lesen und mit dem Attributwert vergleichen

// Seite läuft unter https://example.com/app/
const frame = document.createElement('iframe');
frame.setAttribute('src', 'vorschau.html');
document.body.append(frame);

console.log(frame.getAttribute('src'));
console.log(frame.src);

vorschau.html https://example.com/app/vorschau.html

Inhalt dynamisch wechseln und auf das Laden warten

const frame = document.querySelector('#preview');

const loadInFrame = (iframe, url) => new Promise((resolve, reject) => {
  iframe.addEventListener('load', () => resolve(iframe), { once: true });
  iframe.addEventListener('error', reject, { once: true });
  iframe.src = url;
});

const init = async () => {
  await loadInFrame(frame, '/docs/kapitel-2.html');
  console.log('Geladen:', frame.src);
};
init();

Geladen: https://example.com/docs/kapitel-2.html

YouTube-Video erst beim Klick einbetten (Lazy Embed)

const button = document.querySelector('#play');
const frame = document.querySelector('#video');

button.addEventListener('click', () => {
  const url = new URL('https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ');
  url.searchParams.set('autoplay', '1');
  frame.src = url.href; // erst jetzt wird etwas geladen
  button.hidden = true;
});

Frame zurücksetzen bzw. neu laden

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

// Neu laden: denselben Wert erneut zuweisen
frame.src = frame.src;

// Inhalt leeren
frame.src = 'about:blank';
console.log(frame.src);

about:blank

// Wichtig · Fallstricke

Sicherheit: Weisen Sie src niemals ungeprüfte Benutzereingaben zu. URLs wie javascript:alert(1) führen Code im Kontext der Seite aus (XSS). Erlauben Sie nur https:-URLs von bekannten Hosts und prüfen Sie diese vorher mit new URL(). Mit Trusted Types kann eine Content Security Policy solche Zuweisungen zusätzlich absichern.
Fremde Inhalte sollten Sie mit dem Attribut sandbox und passenden allow-Richtlinien einschränken. Die CSP-Direktive frame-src legt fest, welche Quellen überhaupt erlaubt sind. Ob sich eine Seite einbetten lässt, bestimmt dagegen der Zielserver über X-Frame-Options bzw. frame-ancestors. Wird das Einbetten blockiert, bleibt der Frame leer und es gibt kein zuverlässiges error-Ereignis.
Bei Frames von einer anderen Herkunft (cross-origin) kann frame.src nach einer Navigation im Frame veraltet sein. Die Eigenschaft zeigt nur den gesetzten Attributwert, nicht die aktuelle Adresse des Frames. contentWindow.location ist bei anderer Herkunft nicht lesbar.
Jede Zuweisung von src erzeugt einen neuen Eintrag im Verlauf der Sitzung. Der Zurück-Knopf navigiert dann womöglich im Frame. Ohne neuen Verlaufseintrag geht es mit frame.contentWindow.location.replace(url) (nur bei gleicher Herkunft) oder indem Sie den Frame vor dem Einfügen ins DOM konfigurieren.
Ist srcdoc gesetzt, hat eine Änderung von src keine sichtbare Wirkung.
Für verzögertes Laden gibt es auch loading="lazy". Das wird in allen modernen Browsern unterstützt.

Siehe auch

HTMLIFrameElement HTMLIFrameElement.srcdoc HTMLIFrameElement.contentWindow HTMLIFrameElement.sandbox HTMLIFrameElement.loading Window.postMessage() Element.getAttribute()