HTMLEmbedElement.getSVGDocument() — Methode · JavaScript-Referenz

Signatur

HTMLEmbedElement.prototype.getSVGDocument()

Beschreibung

Die Methode getSVGDocument() des Interfaces HTMLEmbedElement liefert das Dokument, das in einem <embed>-Element geladen ist. Ist dort eine SVG-Datei eingebettet, bekommst du ein Document (genauer: ein XMLDocument mit einem <svg>-Wurzelelement). Dessen DOM kannst du dann per Skript lesen und ändern, z. B. Farben anpassen, Texte austauschen oder Event-Listener an einzelne Formen hängen.

Die Methode ist ein Überbleibsel aus der SVG-1.1-Zeit und entspricht funktional der Eigenschaft contentDocument. Moderne Browser geben laut HTML-Spezifikation schlicht das Content-Dokument zurück, sofern es same-origin ist – und das unabhängig davon, ob es tatsächlich ein SVG ist.

Wichtig: Das eingebettete Dokument lädt asynchron. Rufst du die Methode zu früh auf, erhältst du null oder ein leeres Dokument. Warte deshalb immer auf das load-Event des <embed>-Elements.

Rückgabewert

Typ

Document | null

Beschreibung

Das eingebettete Dokument (bei SVG ein XMLDocument mit documentElement vom Typ SVGSVGElement) oder null, wenn nichts geladen ist oder das Dokument von einem anderen Ursprung stammt.

Beispiele

SVG nach dem Laden einfärben

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

embed.addEventListener('load', () => {
  const svgDoc = embed.getSVGDocument();
  if (!svgDoc) {
    console.warn('Kein Zugriff auf das SVG (Cross-Origin?)');
    return;
  }
  svgDoc.querySelectorAll('path').forEach((path) => {
    path.setAttribute('fill', '#0066cc');
  });
  console.log('Wurzelelement:', svgDoc.documentElement.nodeName);
});

Wurzelelement: svg

Klick auf Regionen einer eingebetteten SVG-Karte

// HTML: <embed id="karte" src="deutschland.svg" type="image/svg+xml">
const karte = document.getElementById('karte');

karte.addEventListener('load', () => {
  const svgDoc = karte.getSVGDocument();
  svgDoc?.querySelectorAll('[data-land]').forEach((region) => {
    region.style.cursor = 'pointer';
    region.addEventListener('click', () => {
      console.log(`Bundesland gewählt: ${region.dataset.land}`);
    });
  });
});

Bundesland gewählt: Bayern

Promise-Helfer mit Fallback auf contentDocument

const loadEmbeddedSvg = (embed) =>
  new Promise((resolve, reject) => {
    const getDoc = () =>
      (typeof embed.getSVGDocument === 'function'
        ? embed.getSVGDocument()
        : null) ?? embed.contentDocument ?? null;

    const done = () => {
      const doc = getDoc();
      doc ? resolve(doc) : reject(new Error('SVG nicht zugreifbar'));
    };

    // Evtl. bereits geladen
    if (getDoc()?.documentElement) return done();
    embed.addEventListener('load', done, { once: true });
    embed.addEventListener('error', () => reject(new Error('Ladefehler')), { once: true });
  });

const svgDoc = await loadEmbeddedSvg(document.querySelector('embed'));
console.log(svgDoc.documentElement.getAttribute('viewBox'));

0 0 100 100

// Wichtig · Fallstricke

Same-Origin-Policy: Stammt die SVG-Datei von einer anderen Origin, gibt die Methode null zurück. CORS-Header helfen hier nicht – die Datei muss vom selben Ursprung ausgeliefert werden.
Timing: Vor dem load-Event ist das Ergebnis null oder ein leeres about:blank-Dokument. Ändert man src, wird ein neues Dokument geladen; alte Referenzen werden ungültig.
Lokale Dateien: Unter file:// behandeln viele Browser (z. B. Chrome) jede Datei als eigene Origin – nutze einen lokalen Webserver.
Legacy-API: getSVGDocument() gilt als veraltet bzw. Kompatibilitätsmethode. In neuem Code ist contentDocument vorzuziehen; auch <object> und <iframe> bieten beides. Für reine Stylebarkeit ist Inline-SVG oft einfacher.
Sicherheit: Mit Zugriff auf das SVG-DOM kann man auch <script>-Elemente darin beeinflussen. Füge keine unbereinigten Benutzereingaben per innerHTML in das SVG ein (XSS-Gefahr).

Siehe auch

Document HTMLIFrameElement.getSVGDocument() HTMLObjectElement.getSVGDocument() HTMLMediaElement.getStartDate() HTMLCanvasElement.getContext()