HTMLIFrameElement.name — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.name

Beschreibung

Die Eigenschaft name der Schnittstelle HTMLIFrameElement spiegelt das HTML-Attribut name des <iframe>-Elements wider. Liest man sie, erhält man den aktuellen Attributwert als Zeichenkette. Schreibt man sie, ändert sich das Attribut im DOM.

Der Name gibt dem eingebetteten Browsing-Kontext einen festen Bezeichner. So kann der Frame als Ziel dienen: für <a target="…">, <form target="…">, <base target="…"> und für das zweite Argument von window.open(url, name). Außerdem ist der Frame über window.frames[name] erreichbar. Innerhalb des Frames liefert window.name denselben Wert.

Typische Einsatzfälle sind klassische Formular-Uploads in einen versteckten Frame, Navigationen in einen Vorschau-Frame und das gezielte Ansprechen mehrerer eingebetteter Dokumente. Namen, die mit einem Unterstrich beginnen (z. B. _blank, _self, _parent, _top), sind reservierte Schlüsselwörter und sollten nicht als Frame-Namen verwendet werden.

Rückgabewert

Typ

string

Beschreibung

Der Wert des name-Attributs. Fehlt das Attribut, ist es eine leere Zeichenkette "". Beim Setzen wird der Wert in eine Zeichenkette umgewandelt.

Beispiele

Namen lesen und setzen

const frame = document.createElement('iframe');
console.log(JSON.stringify(frame.name)); // noch kein Attribut

frame.name = 'vorschau';
document.body.append(frame);

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

"" vorschau vorschau

Link gezielt im iframe öffnen

// HTML: <iframe id="preview"></iframe>
const preview = document.getElementById('preview');
preview.name = 'preview-frame';

const link = document.createElement('a');
link.href = '/hilfe.html';
link.target = preview.name; // Navigation landet im iframe
link.textContent = 'Hilfe in der Vorschau anzeigen';
document.body.append(link);

Formular in einen versteckten Frame absenden

const sink = document.createElement('iframe');
sink.name = 'upload-sink';
sink.hidden = true;
document.body.append(sink);

const form = document.querySelector('#upload-form');
form.target = sink.name;

sink.addEventListener('load', () => {
  console.log('Antwort des Servers im Frame geladen');
});

Antwort des Servers im Frame geladen

Frame per window.open() und window.frames ansprechen

const frame = document.createElement('iframe');
frame.name = 'inhalt';
document.body.append(frame);

// Lädt die URL in den vorhandenen Frame statt in ein neues Fenster
window.open('/artikel/42', 'inhalt');

// Zugriff auf das WindowProxy-Objekt des Frames
console.log(window.frames['inhalt'] === frame.contentWindow);

true

// Wichtig · Fallstricke

Attribut und window.name sind nicht dasselbe: Das Attribut legt den Anfangsnamen des Browsing-Kontexts fest. Setzt das eingebettete Dokument selbst window.name, ändert sich zwar der Name des Kontexts, das Attribut iframe.name bleibt aber gleich. Wird iframe.name nachträglich geändert, übernehmen die Browser den neuen Wert nicht überall gleich in den schon bestehenden Kontext.
Reservierte Namen: Werte wie _blank, _self, _parent oder _top sind Schlüsselwörter für Navigationsziele. Als Frame-Name führen sie zu unerwartetem Verhalten.
Eindeutigkeit: Tragen mehrere Frames denselben Namen, entscheidet der Browser nach seinen eigenen Regeln, welcher Frame als Ziel dient. Vergib die Namen deshalb eindeutig.
Sicherheit: window.name bleibt auch über Navigationen hinweg erhalten. Deshalb wurde es früher für Datenaustausch zwischen Ursprüngen (Cross-Origin) missbraucht. Moderne Browser setzen den Namen bei Navigationen zwischen verschiedenen Ursprüngen im obersten Fenster teilweise zurück. Lege keine sensiblen Daten im Namen ab. Für die Kommunikation zwischen Frames ist postMessage() mit Prüfung von origin der richtige Weg. Ein sandbox-Attribut ohne allow-top-navigation bzw. allow-popups schränkt außerdem ein, welche Ziele ein Frame navigieren darf.
Kompatibilität: Wird von allen gängigen Browsern seit Langem unterstützt.

Siehe auch

Window.name Window.open() Window.frames HTMLIFrameElement.csp HTMLIFrameElement.src