SVGPatternElement.patternContentUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGPatternElement.patternContentUnits

Beschreibung

Die Eigenschaft patternContentUnits des Interfaces SVGPatternElement gibt an, in welchem Koordinatensystem die Inhalte eines <pattern>-Elements (also die Kind-Elemente wie <rect> oder <circle>) interpretiert werden. Zurückgegeben wird ein SVGAnimatedEnumeration-Objekt, dessen Eigenschaft baseVal den im Attribut gesetzten Wert und animVal den aktuell (ggf. animierten) Wert enthält.

Mögliche Werte als numerische Konstanten von SVGUnitTypes:

SVG_UNIT_TYPE_UNKNOWN (0): unbekannter oder ungültiger Wert.
SVG_UNIT_TYPE_USERSPACEONUSE (1): entspricht userSpaceOnUse – Koordinaten beziehen sich auf das Benutzerkoordinatensystem des Elements, das das Muster verwendet. Dies ist der Standardwert.
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX (2): entspricht objectBoundingBox – Koordinaten sind Bruchteile (0 bis 1) der Bounding Box des gefüllten Elements.

Die Eigenschaft selbst ist schreibgeschützt, der Wert lässt sich aber über patternContentUnits.baseVal oder per setAttribute('patternContentUnits', …) ändern. Nützlich ist sie etwa, um in Skripten zu prüfen, ob Musterinhalte mit der Form skalieren, oder um Muster dynamisch zwischen festen und relativen Maßen umzuschalten.

Nicht zu verwechseln mit patternUnits: Diese Eigenschaft bestimmt das Koordinatensystem der Attribute x, y, width und height der Musterkachel selbst, während patternContentUnits nur die Inhalte betrifft.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Objekt mit baseVal (Attributwert, beschreibbar) und animVal (aktueller Wert, schreibgeschützt); die Werte entsprechen den Konstanten von SVGUnitTypes (0, 1 oder 2).

Beispiele

Einheitensystem eines Musters auslesen

// <svg><defs><pattern id="punkte" width="0.2" height="0.2" patternContentUnits="objectBoundingBox">
//   <circle cx="0.1" cy="0.1" r="0.05" fill="tomato"/></pattern></defs></svg>
const pattern = document.getElementById('punkte');
const { baseVal } = pattern.patternContentUnits;

const namen = {
  [SVGUnitTypes.SVG_UNIT_TYPE_UNKNOWN]: 'unbekannt',
  [SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE]: 'userSpaceOnUse',
  [SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX]: 'objectBoundingBox'
};

console.log(baseVal, namen[baseVal]);

2 objectBoundingBox

Standardwert ohne gesetztes Attribut

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

// Kein Attribut gesetzt → Standardwert userSpaceOnUse
console.log(pattern.patternContentUnits.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE);
console.log(pattern.getAttribute('patternContentUnits'));

true null

Musterinhalt dynamisch auf relative Einheiten umschalten

const pattern = document.querySelector('pattern#streifen');

const setzeRelativ = (relativ) => {
  pattern.patternContentUnits.baseVal = relativ
    ? SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX
    : SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE;
};

setzeRelativ(true);
// Das Attribut wird automatisch aktualisiert
console.log(pattern.getAttribute('patternContentUnits'));

objectBoundingBox

// Wichtig · Fallstricke

Schreibschutz: Die Eigenschaft selbst kann nicht neu zugewiesen werden (pattern.patternContentUnits = 2 bleibt wirkungslos bzw. wirft im Strict Mode einen TypeError). Ändern Sie stattdessen baseVal.
Das Setzen von baseVal auf 0 (SVG_UNIT_TYPE_UNKNOWN) oder einen ungültigen Wert löst einen TypeError aus.
Wirkungslos bei viewBox: Hat das <pattern> ein viewBox-Attribut, wird patternContentUnits ignoriert.
Bei objectBoundingBox müssen Inhalte in Bruchteilen (z. B. r="0.05") angegeben werden. Außerdem wirkt die Bounding Box auch auf Strichstärken – Linien können dadurch verzerrt oder unsichtbar werden. Bei Elementen ohne Fläche (z. B. horizontale Linien) wird das Muster nicht gerendert.
Über href geerbte Muster: baseVal spiegelt nur das eigene Attribut wider, nicht einen über eine Vorlage geerbten Wert.
Kompatibilität: in allen modernen Browsern unterstützt; die Konstanten stehen global über SVGUnitTypes zur Verfügung.

Siehe auch

SVGPatternElement SVGPatternElement.patternUnits SVGPatternElement.patternTransform SVGAnimatedEnumeration SVGUnitTypes SVGGradientElement.gradientUnits SVGPatternElement.href