SVGMaskElement.maskUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGMaskElement.maskUnits

Beschreibung

Die schreibgeschützte Eigenschaft maskUnits der Schnittstelle SVGMaskElement gibt ein SVGAnimatedEnumeration-Objekt zurück. Es spiegelt das Attribut maskUnits des <mask>-Elements wider. Dieses Attribut legt fest, in welchem Koordinatensystem die Attribute x, y, width und height der Maske ausgewertet werden, also wie groß der Maskenbereich ist.

Möglich sind zwei Werte, die als numerische Konstanten von SVGUnitTypes zurückgegeben werden:

SVG_UNIT_TYPE_USERSPACEONUSE (1): Die Werte gelten im Benutzerkoordinatensystem des Elements, das auf die Maske verweist.
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX (2): Die Werte sind Anteile der Bounding Box des maskierten Elements, z. B. entspricht 0.5 der halben Breite. Das ist der Standardwert.
SVG_UNIT_TYPE_UNKNOWN (0): Der Wert ist ungültig oder unbekannt.

Die Eigenschaft selbst kannst du nicht neu zuweisen. Über maskUnits.baseVal lässt sich der Attributwert aber per Skript lesen und ändern. maskUnits.animVal liefert den aktuell wirksamen Wert, also auch während einer SMIL-Animation. Verwechsle maskUnits nicht mit maskContentUnits: Letzteres bestimmt das Koordinatensystem für den Inhalt der Maske, nicht für ihren Bereich.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Ein Objekt mit baseVal (änderbarer Attributwert) und animVal (schreibgeschützter, aktuell wirksamer Wert). Beide sind Zahlen, die einer SVGUnitTypes-Konstante entsprechen: 0, 1 oder 2.

Beispiele

Koordinatensystem einer Maske auslesen

// HTML: <svg><defs><mask id="m" maskUnits="userSpaceOnUse"></mask></defs></svg>
const mask = document.getElementById('m');

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

console.log(mask.maskUnits.baseVal);
console.log(names[mask.maskUnits.baseVal]);

1 userSpaceOnUse

Standardwert ohne gesetztes Attribut

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

// Kein maskUnits-Attribut gesetzt → Standard objectBoundingBox
console.log(mask.maskUnits.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX);
console.log(mask.getAttribute('maskUnits'));

true null

Maskenbereich per Skript auf Benutzerkoordinaten umstellen

const mask = document.querySelector('mask#fade');

// baseVal ist beschreibbar und aktualisiert das Attribut
mask.maskUnits.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE;

// Passende absolute Maße setzen (vorher Anteile wie 0..1)
mask.x.baseVal.value = 0;
mask.y.baseVal.value = 0;
mask.width.baseVal.value = 300;
mask.height.baseVal.value = 200;

console.log(mask.getAttribute('maskUnits'));

userSpaceOnUse

Direktes Überschreiben der Eigenschaft wirkt nicht

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

try {
  mask.maskUnits = 1; // Getter-only-Eigenschaft
} catch (err) {
  console.log(err instanceof TypeError);
}
console.log(mask.maskUnits instanceof SVGAnimatedEnumeration);

true true

// Wichtig · Fallstricke

Nur lesbar: mask.maskUnits = … wird im nicht-strikten Modus ohne Meldung ignoriert und wirft im Strict Mode einen TypeError. Ändern lässt sich der Wert nur über maskUnits.baseVal oder setAttribute('maskUnits', …).
Einheiten passen nicht mehr: Stellst du von objectBoundingBox auf userSpaceOnUse um, werden bestehende Anteilswerte wie -10% oder 1.2 anders ausgewertet. Die Maske kann dann winzig klein werden, sodass das Element unsichtbar wird. Passe x/y/width/height immer mit an.
Standardbereich: Bei objectBoundingBox sind die Standardwerte x=-10%, y=-10%, width=120% und height=120%. Weichgezeichnete Masken können deshalb am Rand abgeschnitten werden.
Wird baseVal auf 0 (UNKNOWN) oder einen ungültigen Wert gesetzt, wirft das je nach Browser einen TypeError.
Die Eigenschaft wird von allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Ein Polyfill ist nicht nötig.

Siehe auch

SVGMaskElement SVGMaskElement.maskContentUnits SVGAnimatedEnumeration SVGUnitTypes SVGClipPathElement.clipPathUnits SVGGradientElement.gradientUnits PerformanceTiming.domainLookupEnd