SVGPatternElement.viewBox — Eigenschaft · JavaScript-Referenz

Signatur

SVGPatternElement.viewBox

Beschreibung

Die Eigenschaft viewBox des Interfaces SVGPatternElement liefert ein SVGAnimatedRect-Objekt, das das viewBox-Attribut des <pattern>-Elements abbildet. Das Attribut legt ein eigenes Koordinatensystem für den Inhalt der Musterkachel fest: x, y, width und height bestimmen, welcher Ausschnitt des Musterinhalts in die Kachel (definiert durch width/height des Patterns) skaliert wird.

Das Objekt hat zwei Eigenschaften: baseVal (der im Attribut gesetzte Grundwert, ein veränderbares DOMRect) und animVal (der aktuell animierte, schreibgeschützte Wert, z. B. während einer SMIL-Animation). Die Eigenschaft viewBox selbst kann nicht neu zugewiesen werden, wohl aber die Felder von baseVal.

Man nutzt viewBox vor allem, um Musterkacheln per Skript auszulesen oder dynamisch zu zoomen bzw. zu verschieben – etwa um ein Schraffurmuster feiner oder gröber darzustellen, ohne die Muster-Inhalte selbst anzupassen. Das Zusammenspiel mit preserveAspectRatio bestimmt, wie der Ausschnitt in die Kachel eingepasst wird.

Rückgabewert

Typ

SVGAnimatedRect

Beschreibung

Objekt mit baseVal (DOMRect, veränderbar) und animVal (DOMRectReadOnly). Ist kein viewBox-Attribut gesetzt, enthalten beide ein Rechteck mit allen Werten 0.

Beispiele

viewBox eines Musters auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const pattern = document.createElementNS(svgNS, 'pattern');
pattern.setAttribute('viewBox', '0 0 10 10');

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

0 0 10 10

Muster per Skript zoomen

// HTML: <svg><defs><pattern id="dots" width="20" height="20" patternUnits="userSpaceOnUse" viewBox="0 0 10 10"><circle cx="5" cy="5" r="3"/></pattern></defs><rect width="200" height="200" fill="url(#dots)"/></svg>
const pattern = document.querySelector('#dots');
const box = pattern.viewBox.baseVal;

// Größeren Ausschnitt zeigen => Punkte wirken kleiner
box.width = 20;
box.height = 20;

console.log(pattern.getAttribute('viewBox'));

0 0 20 20

baseVal und animVal vergleichen

const pattern = document.querySelector('pattern');
const { baseVal, animVal } = pattern.viewBox;

const istAnimiert = baseVal.width !== animVal.width || baseVal.height !== animVal.height;
console.log(istAnimiert ? 'viewBox wird gerade animiert' : 'viewBox statisch');

viewBox statisch

// Wichtig · Fallstricke

pattern.viewBox = … hat keine Wirkung (bzw. wirft im Strict Mode einen TypeError) – ändern Sie stattdessen baseVal.x/y/width/height oder das Attribut per setAttribute('viewBox', …).
Fehlt das Attribut, liefert baseVal ein Nullrechteck; prüfen Sie ggf. mit hasAttribute('viewBox'), ob überhaupt eines gesetzt ist.
Negative oder null width/height sind ungültig und deaktivieren das Rendern des Musters.
Die Wirkung hängt von preserveAspectRatio sowie von patternUnits/patternContentUnits ab; bei gesetzter viewBox wird patternContentUnits ignoriert.
In allen modernen Browsern verfügbar; ältere Browser lieferten statt DOMRect ein SVGRect, das dieselben Felder hat.

Siehe auch

SVGPatternElement SVGPatternElement.preserveAspectRatio SVGAnimatedRect SVGSVGElement.viewBox SVGPatternElement.patternContentUnits SVGAElement.download