SVGPatternElement.patternUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGPatternElement.patternUnits

Beschreibung

Die Eigenschaft patternUnits spiegelt das gleichnamige Attribut eines <pattern>-Elements wider. Das Attribut legt fest, in welchem Koordinatensystem die Attribute x, y, width und height der Musterkachel gelesen werden. Es bestimmt also, wo die Kachel liegt und wie groß sie ist.

Zurückgegeben wird ein SVGAnimatedEnumeration-Objekt. Dessen baseVal enthält den im Markup gesetzten Wert, animVal den aktuell animierten Wert. Beide sind Zahlen, die den Konstanten aus SVGUnitTypes entsprechen:

SVG_UNIT_TYPE_UNKNOWN (0): unbekannter oder ungültiger Wert
SVG_UNIT_TYPE_USERSPACEONUSE (1): userSpaceOnUse, das heißt Werte in Benutzereinheiten des Elements, das auf das Muster verweist
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX (2): objectBoundingBox, das heißt Werte als Bruchteile bzw. Prozente der Bounding-Box des gefüllten Elements (Standardwert)

Die Eigenschaft selbst ist schreibgeschützt: Du kannst ihr kein neues Objekt zuweisen. Über patternUnits.baseVal lässt sich der Wert aber ändern, und das Attribut wird dabei automatisch aktualisiert. Das ist praktisch, wenn Muster dynamisch zwischen relativer Kachelgröße (skaliert mit der Form) und absoluter Kachelgröße (feste Pixelgröße) umgeschaltet werden sollen.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Objekt mit baseVal (änderbar, Zahl 0–2) und animVal (schreibgeschützt). Die Werte entsprechen den Konstanten von SVGUnitTypes. Fehlt das Attribut, ist der Wert 2 (objectBoundingBox).

Beispiele

Wert eines vorhandenen Musters auslesen

// HTML: <svg><defs><pattern id="punkte" patternUnits="userSpaceOnUse" width="20" height="20"><circle cx="10" cy="10" r="4"/></pattern></defs></svg>
const pattern = document.getElementById('punkte');

console.log(pattern.patternUnits.baseVal);
console.log(pattern.patternUnits.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE);

1 true

Standardwert bei fehlendem Attribut

const SVG_NS = 'http://www.w3.org/2000/svg';
const pattern = document.createElementNS(SVG_NS, 'pattern');

// Kein Attribut gesetzt, daher gilt objectBoundingBox
console.log(pattern.getAttribute('patternUnits'));
console.log(pattern.patternUnits.baseVal);

null 2

Zwischen relativer und absoluter Kachelgröße umschalten

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
svg.innerHTML = `
  <defs>
    <pattern id="raster" width="0.25" height="0.25">
      <rect width="10" height="10" fill="tomato"/>
    </pattern>
  </defs>
  <rect width="200" height="100" fill="url(#raster)"/>`;
document.body.append(svg);

const pattern = svg.querySelector('#raster');

const setzeAbsolut = (px) => {
  pattern.patternUnits.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE;
  pattern.setAttribute('width', px);
  pattern.setAttribute('height', px);
};

setzeAbsolut(20);
console.log(pattern.getAttribute('patternUnits'));

userSpaceOnUse

Zahlenwert in lesbaren Namen umwandeln

const einheitName = (wert) => ({
  [SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE]: 'userSpaceOnUse',
  [SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX]: 'objectBoundingBox'
}[wert] ?? 'unbekannt');

document.querySelectorAll('pattern').forEach((p) => {
  console.log(`${p.id}: ${einheitName(p.patternUnits.animVal)}`);
});

raster: userSpaceOnUse

// Wichtig · Fallstricke

Nicht mit patternContentUnits verwechseln: patternUnits gilt nur für x, y, width und height der Kachel. Für den Inhalt des Musters ist patternContentUnits zuständig, und dessen Standardwert ist userSpaceOnUse, also genau umgekehrt.
Beim Standardwert objectBoundingBox bedeutet width=\"20\" „20-fache Bounding-Box“ und nicht 20 Pixel. Genau das führt häufig zu Mustern, die scheinbar nicht angezeigt werden.
Die Eigenschaft ist schreibgeschützt: Eine Zuweisung wie pattern.patternUnits = 1 wird ignoriert bzw. wirft im Strict Mode einen TypeError. Ändere stattdessen baseVal oder nutze setAttribute('patternUnits', …).
Wird baseVal auf 0 (SVG_UNIT_TYPE_UNKNOWN) oder einen ungültigen Wert gesetzt, werfen aktuelle Browser einen TypeError.
Über xlink:href/href referenzierte Muster erben patternUnits. Die DOM-Eigenschaft zeigt aber nur das Attribut des eigenen Elements an und nicht den geerbten Wert.
Kompatibilität: Die Eigenschaft wird in allen modernen Browsern seit Langem unterstützt.

Siehe auch

SVGPatternElement SVGPatternElement.patternContentUnits SVGPatternElement.patternTransform SVGAnimatedEnumeration SVGUnitTypes SVGGradientElement.gradientUnits SVGPathElement.pathLength