HTMLObjectElement.contentDocument — Eigenschaft · JavaScript-Referenz

Signatur

HTMLObjectElement.contentDocument

Beschreibung

Über contentDocument greifst du auf das Dokument zu, das ein <object>-Element geladen hat. Das kann zum Beispiel eine SVG-Grafik (type="image/svg+xml") oder eine HTML-Seite sein. Wenn das Dokument geladen ist und vom selben Ursprung (Same-Origin) stammt, kannst du es wie jedes andere Document abfragen und verändern.

Typische Anwendungsfälle:

Eingebettete SVG-Dateien zur Laufzeit einfärben oder animieren
Einzelne Elemente im eingebetteten Dokument hervorheben
Werte aus einer eingebetteten Seite auslesen

Die Eigenschaft gibt null zurück, wenn kein verschachtelter Browsing-Kontext existiert (etwa bei Plugins oder Bildern), wenn das Dokument noch nicht geladen ist oder wenn es aus einem fremden Ursprung stammt. Warte deshalb immer auf das load-Ereignis des <object>-Elements, bevor du darauf zugreifst.

Für den Zugriff auf das zugehörige Window-Objekt gibt es HTMLObjectElement.contentWindow. Es ist auch bei fremdem Ursprung verfügbar, zum Beispiel für postMessage().

Rückgabewert

Typ

Document | null

Beschreibung

Das aktive Document des eingebetteten Browsing-Kontexts (bei SVG meist ein XMLDocument). Bei fremdem Ursprung, fehlendem Kontext oder noch nicht geladenem Inhalt ist der Wert null.

Beispiele

Eingebettetes SVG nach dem Laden einfärben

// HTML: <object id="logo" data="logo.svg" type="image/svg+xml"></object>
const obj = document.getElementById('logo');

obj.addEventListener('load', () => {
  const svgDoc = obj.contentDocument;
  if (!svgDoc) {
    console.warn('Kein Zugriff (fremder Ursprung oder nicht geladen)');
    return;
  }
  svgDoc.querySelectorAll('path').forEach((p) => {
    p.setAttribute('fill', '#e63946');
  });
  console.log('Pfade eingefärbt:', svgDoc.querySelectorAll('path').length);
});

Pfade eingefärbt: 4

Promise-Helfer mit Prüfung auf bereits geladenes Dokument

const getObjectDocument = (obj) =>
  new Promise((resolve, reject) => {
    const doc = obj.contentDocument;
    // Bereits geladen? (about:blank-Dokument ausschließen)
    if (doc && doc.readyState === 'complete' && doc.URL !== 'about:blank') {
      resolve(doc);
      return;
    }
    obj.addEventListener('load', () => {
      obj.contentDocument
        ? resolve(obj.contentDocument)
        : reject(new Error('contentDocument ist null'));
    }, { once: true });
    obj.addEventListener('error', () => reject(new Error('Laden fehlgeschlagen')), { once: true });
  });

const main = async () => {
  const obj = document.querySelector('object#karte');
  try {
    const doc = await getObjectDocument(obj);
    doc.getElementById('bayern')?.classList.add('aktiv');
    console.log('Titel:', doc.title || doc.documentElement.nodeName);
  } catch (err) {
    console.error(err.message);
  }
};
main();

Titel: svg

Objekt dynamisch erzeugen und Inhalt auslesen

const obj = document.createElement('object');
obj.type = 'text/html';
obj.data = '/hilfe/kurzinfo.html'; // gleicher Ursprung
obj.width = 400;
obj.height = 200;

obj.onload = () => {
  const heading = obj.contentDocument?.querySelector('h1');
  console.log(heading ? heading.textContent : 'Keine Überschrift gefunden');
};

document.body.append(obj);

Kurzinfo

// Wichtig · Fallstricke

Same-Origin-Policy: Bei Inhalten von einem anderen Ursprung gibt contentDocument null zurück. Für die Kommunikation über Ursprungsgrenzen hinweg nutzt du contentWindow.postMessage(). Prüfe dabei im Ziel immer event.origin.
Zeitpunkt: Vor dem load-Ereignis ist der Wert null oder zeigt auf ein leeres Übergangsdokument. Registriere den Handler, bevor du data setzt oder das Element einfügst.
Lokale Dateien: Unter file:// behandeln viele Browser (z. B. Chrome) jede Datei als eigenen Ursprung. Dann ist der Wert null. Zum Testen einen lokalen Webserver verwenden.
Ändern von data: Setzt du data neu, wird ein neues Dokument geladen. Frühere Referenzen auf contentDocument sind danach veraltet.
Sicherheit: Füge keine ungeprüften Daten per innerHTML in das eingebettete Dokument ein. Es teilt sich den Ursprung mit deiner Seite, und XSS-Risiken gelten dort genauso.
Kompatibilität: Wird von allen modernen Browsern unterstützt. getSVGDocument() ist veraltet, stattdessen contentDocument verwenden.

Siehe auch

Document HTMLObjectElement.contentWindow HTMLObjectElement.name HTMLObjectElement.form HTMLObjectElement.height