SVGSVGElement.viewBox — Eigenschaft · JavaScript-Referenz

Signatur

SVGSVGElement.viewBox

Beschreibung

Die Eigenschaft viewBox des Interfaces SVGSVGElement liefert ein SVGAnimatedRect-Objekt, das das viewBox-Attribut des <svg>-Elements widerspiegelt. Die viewBox legt fest, welcher Ausschnitt des Nutzerkoordinatensystems (x, y, width, height) auf den Darstellungsbereich des SVG abgebildet wird. Damit steuert sie Skalierung, Zoom und Verschiebung der Grafik.

Das zurückgegebene Objekt hat zwei Eigenschaften: baseVal (ein DOMRect mit dem Attributwert, veränderbar) und animVal (der aktuelle, ggf. durch SMIL-Animation veränderte Wert, nur lesbar). Die Eigenschaft viewBox selbst ist schreibgeschützt – verändert wird der Ausschnitt, indem man die Felder von baseVal anpasst oder das Attribut per setAttribute() neu setzt.

Typische Einsatzzwecke sind Zoom- und Pan-Funktionen für Diagramme, Karten oder Editoren, das Auslesen des internen Koordinatensystems zur Umrechnung von Mauskoordinaten sowie das dynamische Anpassen einer Grafik an ihren Inhalt (etwa mit getBBox()).

Rückgabewert

Typ

SVGAnimatedRect

Beschreibung

Objekt mit baseVal (DOMRect, änderbar) und animVal (DOMRectReadOnly, animierter Wert). Ist kein viewBox-Attribut gesetzt, enthält baseVal in aktuellen Browsern die Werte 0, 0, 0, 0.

Beispiele

viewBox auslesen

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.setAttribute('viewBox', '0 0 200 100');
document.body.append(svg);

const { x, y, width, height } = svg.viewBox.baseVal;
console.log(x, y, width, height);

0 0 200 100

Zoom per Mausrad über baseVal

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

svg.addEventListener('wheel', (event) => {
  event.preventDefault();
  const vb = svg.viewBox.baseVal;
  const factor = event.deltaY > 0 ? 1.1 : 0.9;

  // Um die Mitte herum zoomen
  const cx = vb.x + vb.width / 2;
  const cy = vb.y + vb.height / 2;
  vb.width *= factor;
  vb.height *= factor;
  vb.x = cx - vb.width / 2;
  vb.y = cy - vb.height / 2;
}, { passive: false });

viewBox an Inhalt anpassen

const svg = document.querySelector('svg');
const box = svg.getBBox(); // Begrenzungsrahmen aller Kinder
const padding = 10;

svg.setAttribute(
  'viewBox',
  `${box.x - padding} ${box.y - padding} ${box.width + 2 * padding} ${box.height + 2 * padding}`
);

console.log(svg.viewBox.baseVal.width === box.width + 20);

true

// Wichtig · Fallstricke

Nur lesbar: svg.viewBox = … hat keine Wirkung (im Strict Mode TypeError). Ändern Sie stattdessen svg.viewBox.baseVal.x usw. oder nutzen Sie setAttribute('viewBox', …).
Fehlendes Attribut: Ohne viewBox-Attribut liefert baseVal Nullwerte; ältere Browser gaben teils null zurück. Prüfen Sie ggf. vorher mit svg.hasAttribute('viewBox').
Attributname: Das Attribut ist case-sensitiv – viewBox, nicht viewbox. Bei in HTML eingebettetem SVG korrigiert der Parser dies, bei setAttribute auf per createElement (statt createElementNS) erzeugten Elementen nicht.
Negative Werte: Negative width/height sind ungültig und deaktivieren die Darstellung; 0 blendet die Grafik aus.
animVal weicht nur bei SMIL-Animationen (<animate attributeName=\"viewBox\">) von baseVal ab. Die Eigenschaft wird von allen modernen Browsern unterstützt.

Siehe auch

SVGSVGElement SVGAnimatedRect SVGGraphicsElement.getBBox() SVGSVGElement.preserveAspectRatio Element.setAttribute() SensorErrorEvent.error