SVGSVGElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGSVGElement extends SVGGraphicsElement

Beschreibung

Das Interface SVGSVGElement steht für jedes <svg>-Element – sowohl das äußerste Wurzelelement einer SVG-Grafik als auch verschachtelte <svg>-Elemente. Es erbt von SVGGraphicsElement und damit von SVGElement, Element und EventTarget.

Wichtige Eigenschaften sind x, y, width und height (jeweils SVGAnimatedLength), viewBox (SVGAnimatedRect), preserveAspectRatio sowie currentScale und currentTranslate für Zoom und Verschiebung des Wurzelelements.

Zu den Methoden gehören:

Animationssteuerung (SMIL): pauseAnimations(), unpauseAnimations(), animationsPaused(), getCurrentTime(), setCurrentTime(sekunden).
Fabrikmethoden: createSVGPoint(), createSVGMatrix(), createSVGRect(), createSVGTransform(), createSVGLength(), createSVGNumber(), createSVGAngle().
Trefferprüfung: getIntersectionList(), getEnclosureList(), checkIntersection(), checkEnclosure().
Sonstiges: getElementById(), deselectAll().

Typische Anwendungsfälle sind interaktive Diagramme, Zeichenwerkzeuge oder Karten: Man rechnet Mauspositionen mithilfe von getScreenCTM() in SVG-Koordinaten um, passt die viewBox für Zoom und Pan an oder pausiert eingebettete SMIL-Animationen.

Parameter

Name	Typ	Default	Beschreibung
$seconds Pflicht	number		Parameter von `setCurrentTime(seconds)`: Zielzeit der SMIL-Animationszeitleiste in Sekunden.
$rect Pflicht	DOMRectReadOnly\|SVGRect		Parameter von `getIntersectionList(rect, referenceElement)` und `getEnclosureList()`: Rechteck in Benutzerkoordinaten, gegen das geprüft wird.
$referenceElement	SVGElement\|null	null	Optionale Einschränkung auf Nachfahren dieses Elements bei `getIntersectionList()`/`getEnclosureList()`.
$elementId Pflicht	string		Parameter von `getElementById(elementId)`: ID des gesuchten Elements innerhalb des SVG-Teilbaums.

Rückgabewert

Typ

SVGSVGElement

Beschreibung

Eine Instanz erhält man über document.createElementNS("http://www.w3.org/2000/svg", "svg") oder per DOM-Abfrage eines vorhandenen <svg>-Elements.

Beispiele

SVG-Element per Skript erzeugen

const SVG_NS = 'http://www.w3.org/2000/svg';

const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('width', '200');
svg.setAttribute('height', '100');
svg.setAttribute('viewBox', '0 0 200 100');

const kreis = document.createElementNS(SVG_NS, 'circle');
kreis.setAttribute('cx', '100');
kreis.setAttribute('cy', '50');
kreis.setAttribute('r', '40');
kreis.setAttribute('fill', 'tomato');

svg.append(kreis);
document.body.append(svg);

console.log(svg instanceof SVGSVGElement);
console.log(svg.viewBox.baseVal.width);

true 200

Mausposition in SVG-Koordinaten umrechnen

const svg = document.querySelector('svg');

svg.addEventListener('click', (event) => {
  const ctm = svg.getScreenCTM();
  if (!ctm) return;
  // DOMPoint statt veraltetem createSVGPoint()
  const punkt = new DOMPoint(event.clientX, event.clientY)
    .matrixTransform(ctm.inverse());
  console.log(`SVG-Koordinaten: ${punkt.x.toFixed(1)}, ${punkt.y.toFixed(1)}`);
});

SVG-Koordinaten: 57.3, 21.8

Zoom über die viewBox

const svg = document.querySelector('svg');

const zoom = (faktor) => {
  const vb = svg.viewBox.baseVal;
  const cx = vb.x + vb.width / 2;
  const cy = vb.y + vb.height / 2;
  vb.width /= faktor;
  vb.height /= faktor;
  vb.x = cx - vb.width / 2;
  vb.y = cy - vb.height / 2;
};

svg.addEventListener('wheel', (e) => {
  e.preventDefault();
  zoom(e.deltaY < 0 ? 1.1 : 1 / 1.1);
}, { passive: false });

SMIL-Animationen pausieren und springen

const svg = document.querySelector('svg');

svg.pauseAnimations();
svg.setCurrentTime(2.5);
console.log(svg.animationsPaused(), svg.getCurrentTime());

document.querySelector('#play').addEventListener('click', () => {
  svg.unpauseAnimations();
});

true 2.5

// Wichtig · Fallstricke

Namensraum: Mit document.createElement('svg') entsteht ein unbekanntes HTML-Element, kein SVGSVGElement. Nutzen Sie immer createElementNS('http://www.w3.org/2000/svg', 'svg').
viewBox ohne Attribut: Ist kein viewBox-Attribut gesetzt, liefert svg.viewBox.baseVal je nach Browser null oder ein Rechteck mit lauter Nullen. Prüfen Sie vorher mit svg.hasAttribute('viewBox').
Veraltete Fabrikmethoden: createSVGPoint(), createSVGMatrix() und createSVGRect() funktionieren zwar überall, gelten aber als Altlast. Verwenden Sie besser DOMPoint, DOMMatrix und DOMRect.
Trefferprüfung: Firefox unterstützt getIntersectionList(), getEnclosureList(), checkIntersection() und checkEnclosure() nicht. Diese Methoden sollten Sie deshalb nicht plattformübergreifend einsetzen.
Entfernte APIs: suspendRedraw(), unsuspendRedraw() und forceRedraw() tun heute nichts mehr. useCurrentView und currentView wurden entfernt.
getScreenCTM() kann null zurückgeben, wenn das Element nicht dargestellt wird (z. B. bei display: none).
Sicherheit: SVG kann Skripte enthalten. Fremdes SVG-Markup sollten Sie nie ungeprüft über innerHTML einfügen, sondern vorher bereinigen (z. B. mit DOMPurify) oder als <img> einbinden.

Siehe auch

SVGGraphicsElement SVGElement Document.createElementNS() SVGGraphicsElement.getScreenCTM() SVGGraphicsElement.getBBox() SVGAnimatedRect