SVGMaskElement.maskContentUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGMaskElement.maskContentUnits

Beschreibung

Die Eigenschaft maskContentUnits des SVGMaskElement-Interfaces spiegelt das gleichnamige SVG-Attribut wider. Das Attribut legt fest, in welchem Koordinatensystem die Kindelemente der Maske (z. B. <rect>, <circle>) interpretiert werden.

Es gibt zwei gültige Werte:

userSpaceOnUse (Standard, numerisch 1): Koordinaten beziehen sich auf das Benutzerkoordinatensystem des Elements, das die Maske verwendet.
objectBoundingBox (numerisch 2): Koordinaten sind Bruchteile der Bounding Box des maskierten Elements (0 bis 1). So lässt sich eine Maske für Elemente unterschiedlicher Größe wiederverwenden.

Die Eigenschaft selbst ist schreibgeschützt, gibt aber ein SVGAnimatedEnumeration-Objekt zurück. Über dessen baseVal kann man den Wert lesen und setzen; animVal liefert den aktuell (ggf. animierten) wirksamen Wert und ist nur lesbar. Nicht verwechseln mit maskUnits, das sich auf die Maskenregion (x, y, width, height) bezieht.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Objekt mit baseVal und animVal. Mögliche Zahlenwerte: 0 (SVG_UNIT_TYPE_UNKNOWN), 1 (SVG_UNIT_TYPE_USERSPACEONUSE), 2 (SVG_UNIT_TYPE_OBJECTBOUNDINGBOX) – definiert in SVGUnitTypes.

Beispiele

Aktuellen Wert auslesen

// HTML: <svg><defs><mask id="m" maskContentUnits="objectBoundingBox"><rect width="0.5" height="1" fill="white"/></mask></defs></svg>
const mask = document.getElementById('m');

const units = mask.maskContentUnits;
console.log(units.baseVal);
console.log(units.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX);

2 true

Standardwert ohne gesetztes Attribut

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

// Kein Attribut gesetzt → Standard userSpaceOnUse
console.log(mask.maskContentUnits.baseVal);
console.log(mask.getAttribute('maskContentUnits'));

1 null

Maske per Skript auf relative Koordinaten umstellen

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

// Wert über baseVal setzen – die Eigenschaft selbst ist nicht zuweisbar
mask.maskContentUnits.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX;

const rect = document.createElementNS(svgNS, 'rect');
rect.setAttribute('width', '1');
rect.setAttribute('height', '0.5');
rect.setAttribute('fill', 'white');
mask.append(rect);

// Das Attribut wird automatisch synchronisiert
console.log(mask.getAttribute('maskContentUnits'));

objectBoundingBox

// Wichtig · Fallstricke

Nicht direkt zuweisbar: mask.maskContentUnits = 2 wird ignoriert (im Strict-Mode TypeError). Stattdessen maskContentUnits.baseVal setzen oder setAttribute('maskContentUnits', …) verwenden.
Wird baseVal auf 0 oder einen ungültigen Wert gesetzt, lösen Browser einen TypeError aus bzw. ignorieren die Zuweisung.
Bei objectBoundingBox müssen Kindkoordinaten im Bereich 0–1 liegen; Werte wie width=\"100\" erzeugen dann eine riesige Maske. Außerdem funktioniert die Maske nicht bei Elementen ohne Ausdehnung (z. B. horizontale Linien mit Bounding-Box-Höhe 0).
Nicht mit maskUnits verwechseln (Standard dort: objectBoundingBox).
Die Konstanten liegen in SVG 2 auf SVGUnitTypes; von allen modernen Browsern unterstützt.

Siehe auch

SVGMaskElement SVGMaskElement.maskUnits SVGAnimatedEnumeration SVGUnitTypes SVGClipPathElement.clipPathUnits MediaStreamTrack.contentHint PushManager.supportedContentEncodings