HTMLObjectElement.contentWindow — Eigenschaft · JavaScript-Referenz

Signatur

HTMLObjectElement.contentWindow

Beschreibung

Die Eigenschaft contentWindow eines HTMLObjectElement gibt das WindowProxy-Objekt des eingebetteten Dokuments zurück. Das gilt, wenn das <object>-Element ein HTML-, SVG- oder anderes Dokument lädt, für das der Browser einen eigenen Browsing-Kontext anlegt (ähnlich wie bei einem <iframe>). Gibt es keinen solchen Kontext, etwa bei einem Bild, einem Plugin-Inhalt oder solange noch nichts geladen ist, ist der Wert null.

Über das zurückgegebene Fensterobjekt kannst du mit dem eingebetteten Inhalt arbeiten: Nachrichten per postMessage() schicken und, falls der Inhalt vom gleichen Ursprung stammt, direkt auf document, globale Variablen und Funktionen des eingebetteten Dokuments zugreifen.

Bei Inhalten von einem fremden Ursprung erlaubt der WindowProxy nur einige wenige ursprungsübergreifende Operationen, zum Beispiel postMessage(), location (nur zum Setzen), close() oder frames. Jeder andere Zugriff löst einen SecurityError aus.

Wenn du nur das Dokument brauchst, ist contentDocument meist der kürzere Weg. Bei fremdem Ursprung liefert es null.

Rückgabewert

Typ

WindowProxy | null

Beschreibung

Das Fensterobjekt des eingebetteten Browsing-Kontextes, oder null, wenn keiner existiert (z. B. bei Bildern, Plugins oder noch nicht geladenem Inhalt).

Beispiele

Auf ein eingebettetes Dokument vom gleichen Ursprung zugreifen

// HTML: <object id="widget" data="/widgets/uhr.html" type="text/html"></object>
const obj = document.getElementById('widget');

obj.addEventListener('load', () => {
  const win = obj.contentWindow;
  if (!win) {
    console.log('Kein Browsing-Kontext vorhanden');
    return;
  }
  // Gleicher Ursprung: voller Zugriff
  console.log(win.document.title);
  win.document.body.style.background = '#f5f5f5';
});

Uhr-Widget

Ursprungsübergreifende Kommunikation mit postMessage

// HTML: <object id="karte" data="https://maps.example.com/embed" type="text/html"></object>
const karte = document.getElementById('karte');

karte.addEventListener('load', () => {
  // Immer den Zielursprung angeben, nie '*'
  karte.contentWindow?.postMessage(
    { typ: 'zoom', stufe: 12 },
    'https://maps.example.com'
  );
});

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://maps.example.com') return;
  if (event.source !== karte.contentWindow) return;
  console.log('Antwort der Karte:', event.data);
});

Antwort der Karte: { status: 'ok' }

Prüfen, ob Zugriff erlaubt ist

const istGleicherUrsprung = (objEl) => {
  const win = objEl.contentWindow;
  if (!win) return false;
  try {
    // Wirft bei fremdem Ursprung einen SecurityError
    void win.document;
    return true;
  } catch (err) {
    console.warn(err.name); // "SecurityError"
    return false;
  }
};

const obj = document.querySelector('object');
obj.addEventListener('load', () => console.log(istGleicherUrsprung(obj)));

true // bzw. "SecurityError" und false bei fremdem Ursprung

// Wichtig · Fallstricke

Zeitpunkt: Vor dem load-Ereignis zeigt contentWindow möglicherweise noch auf ein leeres about:blank-Dokument oder ist null. Greife deshalb erst im load-Handler darauf zu.
Same-Origin-Policy: Bei fremdem Ursprung löst jeder Zugriff auf document, globale Variablen und Ähnliches einen SecurityError aus. Nur postMessage() und wenige weitere Operationen sind erlaubt.
Sicherheit bei postMessage: Gib immer einen konkreten targetOrigin an, nicht '*'. Prüfe bei eingehenden Nachrichten event.origin und event.source, damit du keine Nachrichten von fremden Seiten verarbeitest (XSS-Risiko).
Kein Browsing-Kontext: Bei Bildern (image/*) und Plugin-Inhalten, etwa PDFs mit bestimmten Viewern, ist der Wert null. Das Verhalten beim PDF-Viewer unterscheidet sich zwischen den Browsern.
Schreibgeschützt: Eine Zuweisung an contentWindow bleibt ohne Wirkung. Um den Inhalt zu wechseln, änderst du das Attribut data.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Für eingebettete Seiten ist ein <iframe> oft die bessere Wahl, weil es zusätzlich Schutzmechanismen wie sandbox und allow bietet.

Siehe auch

HTMLObjectElement.contentDocument HTMLIFrameElement.contentWindow Window.postMessage() HTMLObjectElement HTMLObjectElement.data HTMLObjectElement.form