Document.rootElement — Eigenschaft · JavaScript-Referenz

Signatur

get Document.rootElement

Beschreibung

Document.rootElement ist eine schreibgeschützte Eigenschaft. Sie stammt aus dem früheren Interface SVGDocument aus SVG 1.1. Wenn das Wurzelelement des Dokuments ein <svg>-Element ist, liefert sie dieses als SVGSVGElement. In allen anderen Fällen gibt sie null zurück, zum Beispiel in normalen HTML-Dokumenten mit <html> als Wurzel.

Nützlich ist die Eigenschaft vor allem in eigenständigen SVG-Dateien, also .svg-Dateien, die direkt im Browser geöffnet oder über <object>, <iframe> oder <embed> eingebunden werden. Ein Skript kann damit prüfen, ob es in einem SVG-Dokument läuft, und dann direkt SVG-Methoden wie createSVGPoint(), getCurrentTime() oder pauseAnimations() auf dem Wurzelelement aufrufen.

Ein <svg>-Element, das inline in einem HTML-Dokument steht, ist nicht das Wurzelelement. Dort gibt document.rootElement also null zurück. Für neuen Code empfiehlt sich document.documentElement zusammen mit einer Typprüfung (instanceof SVGSVGElement). Diese Kombination ist standardkonform und verhält sich bei jedem Dokumenttyp gleich.

Rückgabewert

Typ

SVGSVGElement | null

Beschreibung

Das <svg>-Wurzelelement des Dokuments oder null, wenn das Wurzelelement kein SVG-Element ist, z. B. <html>.

Beispiele

Prüfen, ob das Skript in einem SVG-Dokument läuft

// In einer HTML-Seite ist das Wurzelelement <html>
const svgRoot = document.rootElement;

if (svgRoot) {
  console.log('SVG-Dokument, Breite:', svgRoot.width.baseVal.value);
} else {
  console.log('Kein SVG-Dokument – Wurzel ist', document.documentElement.nodeName);
}

Kein SVG-Dokument – Wurzel ist HTML

Animationen in einer eigenständigen SVG-Datei anhalten

<!-- animation.svg -->
<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200">
  <circle cx="100" cy="100" r="40" fill="tomato">
    <animate attributeName="r" values="40;80;40" dur="2s" repeatCount="indefinite"/>
  </circle>
  <script>
    const root = document.rootElement; // SVGSVGElement
    document.addEventListener('click', () => {
      root.animationsPaused() ? root.unpauseAnimations() : root.pauseAnimations();
      console.log('Pausiert:', root.animationsPaused(), 'Zeit:', root.getCurrentTime().toFixed(2));
    });
  </script>
</svg>

Pausiert: true Zeit: 1.37

Zukunftssichere Alternative mit documentElement

const getSvgRoot = (doc = document) => {
  const root = doc.documentElement;
  return root instanceof SVGSVGElement ? root : null;
};

// Beispiel: SVG aus <object> auslesen
const obj = document.querySelector('object[type="image/svg+xml"]');
obj?.addEventListener('load', () => {
  const svg = getSvgRoot(obj.contentDocument);
  console.log(svg ? `viewBox: ${svg.getAttribute('viewBox')}` : 'Kein SVG geladen');
});

viewBox: 0 0 100 100

// Wichtig · Fallstricke

Veraltet: In SVG 2 wurde rootElement zusammen mit SVGDocument entfernt. Die gängigen Browser unterstützen die Eigenschaft zwar noch, trotzdem sollte neuer Code document.documentElement mit instanceof SVGSVGElement verwenden.
Inline-SVG: In HTML-Dokumenten liefert die Eigenschaft immer null, auch wenn die Seite <svg>-Elemente enthält. Diese findet man mit document.querySelector('svg').
Nicht verwechseln mit Node.getRootNode() (liefert Document oder ShadowRoot) oder mit SVGElement.ownerSVGElement (das nächste übergeordnete <svg>-Element).
Gleicher Ursprung: Auf contentDocument eingebundener SVG-Dateien kann man nur zugreifen, wenn sie vom gleichen Ursprung stammen. Sonst ist contentDocument null.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert bzw. wirft im Strict Mode einen TypeError.

Siehe auch

Document.documentElement SVGSVGElement SVGElement.ownerSVGElement Node.getRootNode() HTMLObjectElement.contentDocument Document.customElementRegistry Document.firstElementChild