HTMLIFrameElement.getSVGDocument() — Methode · JavaScript-Referenz

Signatur

HTMLIFrameElement.prototype.getSVGDocument()

Beschreibung

Die Methode getSVGDocument() des HTMLIFrameElement-Interfaces gibt das Document-Objekt des im Frame geladenen Inhalts zurück. Gedacht ist sie für den Fall, dass ein <iframe> eine SVG-Datei einbettet (z. B. src="grafik.svg"). Über das zurückgegebene Dokument kann man die SVG-Elemente per Skript lesen und ändern, etwa Farben anpassen, Texte ersetzen oder Event-Listener an einzelne Formen hängen.

Die Methode stammt aus der alten SVG-1.1-Spezifikation (GetSVGDocument-Interface). Heute liefert sie im Wesentlichen dasselbe wie die Eigenschaft contentDocument. Laut HTML-Spezifikation gibt sie das Dokument zurück, sofern es mit dem aufrufenden Dokument same-origin ist, sonst null. Modernen Code schreibt man daher meist direkt mit iframe.contentDocument. getSVGDocument() ist aber weiterhin verfügbar und in älterem Code häufig anzutreffen.

Wichtig ist der richtige Zeitpunkt: Das Dokument steht erst nach dem load-Event des Iframes vollständig bereit. Ruft man die Methode vorher auf, erhält man oft nur ein leeres about:blank-Dokument oder null.

Rückgabewert

Typ

Document | null

Beschreibung

Das Document des eingebetteten Inhalts (bei SVG-Dateien ein XMLDocument mit einem <svg> als documentElement), oder null, wenn kein Dokument geladen ist oder es aus einer anderen Origin stammt.

Beispiele

SVG im Iframe nach dem Laden einfärben

// HTML: <iframe id="logo" src="/img/logo.svg"></iframe>
const frame = document.getElementById('logo');

frame.addEventListener('load', () => {
  const svgDoc = frame.getSVGDocument();
  if (!svgDoc) {
    console.warn('Kein Zugriff auf das SVG (Cross-Origin?)');
    return;
  }
  // Alle Pfade einheitlich einfärben
  svgDoc.querySelectorAll('path').forEach((p) => {
    p.setAttribute('fill', '#0a7cff');
  });
  console.log('Wurzelelement:', svgDoc.documentElement.nodeName);
});

Wurzelelement: svg

Klick auf Regionen einer SVG-Karte auswerten

// HTML: <iframe id="karte" src="/img/deutschland.svg"></iframe>
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(`Ausgewählt: ${region.dataset.land}`);
    });
  });
});

Ausgewählt: Bayern

Robuster Zugriff mit Fallback auf contentDocument

const getFrameSvg = (iframe) => {
  const doc = typeof iframe.getSVGDocument === 'function'
    ? iframe.getSVGDocument()
    : iframe.contentDocument;
  // Nur zurückgeben, wenn tatsächlich ein SVG geladen ist
  return doc?.documentElement?.localName === 'svg' ? doc : null;
};

const frame = document.querySelector('iframe.diagramm');
frame.addEventListener('load', () => {
  const svg = getFrameSvg(frame);
  console.log(svg ? 'SVG bereit' : 'Kein SVG verfügbar');
});

SVG bereit

// Wichtig · Fallstricke

Same-Origin-Policy: Stammt das SVG aus einer anderen Origin, gibt die Methode null zurück. CORS-Header helfen hier nicht. Nötig ist dieselbe Origin; alternativ holt man das SVG per fetch() und fügt es inline ein.
Zeitpunkt: Erst nach dem load-Event aufrufen. Vorher bekommt man ein leeres about:blank-Dokument oder null.
Veraltete API: Die Methode stammt aus SVG 1.1. Bevorzugt contentDocument verwenden, das denselben Wert liefert. Die Methode wird von Chrome, Firefox, Safari und Edge unterstützt.
Die Methode prüft nicht, ob wirklich ein SVG geladen ist. Bei einer HTML-Seite im Iframe kommt einfach deren Document zurück. Bei Bedarf documentElement.localName prüfen.
Das Attribut sandbox ohne allow-same-origin macht den Inhalt cross-origin, und der Zugriff schlägt fehl.
Sicherheit: SVGs können Skripte enthalten. Nicht vertrauenswürdige SVGs nicht same-origin einbetten, sondern über <img> oder mit sandbox isolieren.

Siehe auch

HTMLIFrameElement.contentDocument HTMLIFrameElement.contentWindow HTMLObjectElement.getSVGDocument() HTMLEmbedElement.getSVGDocument() HTMLIFrameElement Document