SVGPatternElement.width — Eigenschaft · JavaScript-Referenz

Signatur

SVGPatternElement.width

Beschreibung

Die Eigenschaft width der Schnittstelle SVGPatternElement steht für das width-Attribut eines <pattern>-Elements. Sie gibt die Breite der Musterkachel an. Zusammen mit x, y und height legt sie fest, wo und wie groß die Kachel ist, die über die gefüllte Fläche wiederholt wird.

Die Eigenschaft selbst ist schreibgeschützt. Sie liefert ein SVGAnimatedLength-Objekt mit zwei Teilen: baseVal ist der statische Wert aus dem Attribut und lässt sich ändern. animVal ist der aktuelle Wert, auch während einer SMIL-Animation, und kann nur gelesen werden. Beide Teile sind SVGLength-Objekte mit value, valueInSpecifiedUnits, unitType und convertToSpecifiedUnits().

Wie der Wert gedeutet wird, hängt von patternUnits ab. Beim Standard objectBoundingBox ist er ein Anteil am Begrenzungsrahmen des gefüllten Elements, zum Beispiel 0.25 für ein Viertel der Breite. Bei userSpaceOnUse ist er eine Länge im Benutzerkoordinatensystem. Fehlt das Attribut, ist der Wert 0. Das Muster wird dann nicht gezeichnet.

Typische Anwendungen: die Kachelgröße per Skript anpassen, etwa für zoombare Raster, Schraffuren oder Hintergrundtexturen. Oder den aktuellen Wert auslesen, zum Beispiel während einer Animation.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (änderbares SVGLength, entspricht dem Attribut) und animVal (nur lesbares SVGLength, aktueller animierter Wert). Die Eigenschaft selbst lässt sich nicht neu zuweisen.

Beispiele

Breite der Musterkachel auslesen

// <svg><defs><pattern id="raster" width="20" height="20" patternUnits="userSpaceOnUse">...</pattern></defs></svg>
const pattern = document.getElementById('raster');

console.log(pattern.width.baseVal.value);    // Wert in Benutzereinheiten
console.log(pattern.width.baseVal.unitType === SVGLength.SVG_LENGTHTYPE_NUMBER);
console.log(pattern.width.animVal.value);    // aktueller (ggf. animierter) Wert

20 true 20

Rasterweite per Schieberegler ändern

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
svg.setAttribute('width', '300');
svg.setAttribute('height', '200');

const defs = document.createElementNS(svgNS, 'defs');
const pattern = document.createElementNS(svgNS, 'pattern');
pattern.id = 'gitter';
pattern.setAttribute('patternUnits', 'userSpaceOnUse');
pattern.setAttribute('width', '10');
pattern.setAttribute('height', '10');

const linie = document.createElementNS(svgNS, 'path');
linie.setAttribute('d', 'M 10 0 L 0 0 0 10');
linie.setAttribute('fill', 'none');
linie.setAttribute('stroke', '#999');
pattern.append(linie);
defs.append(pattern);

const rect = document.createElementNS(svgNS, 'rect');
rect.setAttribute('width', '100%');
rect.setAttribute('height', '100%');
rect.setAttribute('fill', 'url(#gitter)');
svg.append(defs, rect);
document.body.append(svg);

const regler = document.createElement('input');
regler.type = 'range';
regler.min = '5';
regler.max = '50';
regler.value = '10';
document.body.append(regler);

regler.addEventListener('input', () => {
  const groesse = Number(regler.value);
  // baseVal ändern – das Attribut wird automatisch mitgeändert
  pattern.width.baseVal.value = groesse;
  pattern.height.baseVal.value = groesse;
  console.log(pattern.getAttribute('width'));
});

z. B. "25" beim Verschieben des Reglers

Einheit mit newValueSpecifiedUnits festlegen

const pattern = document.querySelector('pattern');
pattern.setAttribute('patternUnits', 'objectBoundingBox');

// Kachelbreite = 25 % des Begrenzungsrahmens
pattern.width.baseVal.newValueSpecifiedUnits(
  SVGLength.SVG_LENGTHTYPE_NUMBER,
  0.25
);

console.log(pattern.getAttribute('width'));
console.log(pattern.width.baseVal.valueInSpecifiedUnits);

0.25 0.25

// Wichtig · Fallstricke

Schreibgeschützt: pattern.width = 50 hat keine Wirkung. Im Strict Mode wird ein TypeError geworfen. Ändern Sie stattdessen pattern.width.baseVal.value oder verwenden Sie setAttribute('width', …).
animVal ist nur lesbar: Schreibversuche lösen eine NoModificationAllowedError-DOMException aus.
Standardwert 0: Ohne width-Attribut (oder mit 0) wird das Muster gar nicht gezeichnet. Die Fläche bleibt dann leer und es gibt keine Fehlermeldung.
patternUnits beachten: Beim Standard objectBoundingBox bedeutet width="20" das 20-Fache des Begrenzungsrahmens, nicht 20 Pixel. Für feste Pixelgrößen muss patternUnits="userSpaceOnUse" gesetzt sein.
Prozentwerte: Bei Prozentangaben liefert baseVal.value einen umgerechneten Wert, der vom Viewport-Kontext abhängt. Wenn das Element noch nicht im gerenderten Dokument hängt, kann dieser Wert unerwartet ausfallen.
Vererbte Attribute: Über href kann ein Muster Attribute von einem anderen Muster übernehmen. width.baseVal gibt aber nur das eigene Attribut wieder, nicht den geerbten Wert.
Kompatibilität: Wird von allen modernen Browsern seit Langem unterstützt (Chrome, Firefox, Safari, Edge).

Siehe auch

SVGPatternElement SVGPatternElement.height SVGPatternElement.x SVGPatternElement.y SVGPatternElement.patternUnits SVGAnimatedLength SVGLength