SVGSymbolElement.viewBox — Eigenschaft · JavaScript-Referenz

Signatur

SVGSymbolElement.viewBox

Beschreibung

Die Eigenschaft viewBox der Schnittstelle SVGSymbolElement gibt das viewBox-Attribut eines <symbol>-Elements als SVGAnimatedRect zurück. Die viewBox legt das interne Koordinatensystem des Symbols fest, also den Ausschnitt (x, y, width, height), der beim Einbinden per <use> auf die Zielgröße skaliert wird.

Das Objekt hat zwei Teile: baseVal ist ein DOMRect-ähnliches SVGRect mit dem Attributwert. Du kannst es direkt ändern, und die Änderung wird ins Attribut zurückgeschrieben. animVal enthält den aktuellen, eventuell durch SMIL-Animation veränderten Wert und ist nur lesbar.

Typische Einsätze: Icon-Sprites auswerten (z. B. das Seitenverhältnis eines Symbols bestimmen), Symbole zur Laufzeit neu zuschneiden oder zoomen und Werkzeuge bauen, die SVG-Sprites prüfen oder umwandeln.

„Schreibgeschützt“ bezieht sich nur auf die Eigenschaft selbst: Du kannst symbol.viewBox kein neues Objekt zuweisen, die Felder von baseVal lassen sich aber ändern.

Rückgabewert

Typ

SVGAnimatedRect

Beschreibung

Ein Objekt mit baseVal (änderbares SVGRect mit x, y, width, height) und animVal (nur lesbarer, animierter Wert).

Beispiele

viewBox eines Sprite-Symbols auslesen

// <svg style="display:none"><symbol id="icon-star" viewBox="0 0 24 24">…</symbol></svg>
const symbol = document.getElementById('icon-star');
const { x, y, width, height } = symbol.viewBox.baseVal;
console.log(`viewBox: ${x} ${y} ${width} ${height}`);
console.log('Seitenverhältnis:', width / height);

viewBox: 0 0 24 24 Seitenverhältnis: 1

Symbol zur Laufzeit zoomen (Ausschnitt ändern)

const symbol = document.querySelector('symbol#map');
const box = symbol.viewBox.baseVal;

// Auf die Mitte heranzoomen, Faktor 2
const zoom = (factor) => {
  const cx = box.x + box.width / 2;
  const cy = box.y + box.height / 2;
  box.width /= factor;
  box.height /= factor;
  box.x = cx - box.width / 2;
  box.y = cy - box.height / 2;
};

zoom(2);
console.log(symbol.getAttribute('viewBox'));

25 25 50 50 (bei ursprünglich viewBox="0 0 100 100")

Alle Symbole eines Sprites ohne viewBox finden

const symbols = [...document.querySelectorAll('symbol')];

const ohneViewBox = symbols
  .filter((s) => !s.hasAttribute('viewBox'))
  .map((s) => s.id);

const groessen = symbols
  .filter((s) => s.hasAttribute('viewBox'))
  .map((s) => ({ id: s.id, w: s.viewBox.baseVal.width, h: s.viewBox.baseVal.height }));

console.log('Ohne viewBox:', ohneViewBox);
console.table(groessen);

Ohne viewBox: ["icon-legacy"]

// Wichtig · Fallstricke

Fehlendes Attribut: Hat das Symbol kein viewBox-Attribut, liefert baseVal trotzdem ein Rechteck, meist mit lauter 0-Werten. Prüfe deshalb vorher mit hasAttribute('viewBox'), statt dich auf width === 0 zu verlassen.
Keine Zuweisung: symbol.viewBox = … wirkt nicht (im Strict Mode gibt es einen TypeError). Ändere stattdessen baseVal.x usw. oder rufe setAttribute('viewBox', '0 0 48 48') auf.
animVal: Der Wert ist nur lesbar. Ohne laufende SMIL-Animation entspricht er baseVal.
Ungültige Werte wie negative Breite oder Höhe führen dazu, dass das Symbol nicht gezeichnet wird. Eine Breite oder Höhe von 0 schaltet die Darstellung ebenfalls ab.
Kompatibilität: Wird in allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). SVGSymbolElement erbt die Eigenschaft über die Mixin-Schnittstelle SVGFitToViewBox, zusammen mit preserveAspectRatio.

Siehe auch

SVGSymbolElement SVGSymbolElement.preserveAspectRatio SVGSVGElement.viewBox SVGAnimatedRect SVGUseElement HTMLTableColElement.vAlign SVGImageElement.decoding