SVGMaskElement.y — Eigenschaft · JavaScript-Referenz

Signatur

SVGMaskElement.y

Beschreibung

Die Eigenschaft y von SVGMaskElement ist die Schnittstelle zum y-Attribut eines <mask>-Elements. Das Attribut legt die obere Kante des Maskenbereichs fest, also die y-Koordinate des Rechtecks, außerhalb dessen die Maske alles ausblendet.

Zurückgegeben wird kein einfacher Zahlenwert, sondern ein SVGAnimatedLength-Objekt. Über baseVal kommt man an den im Markup gesetzten Grundwert, über animVal an den aktuellen, eventuell per SMIL animierten Wert. Beide sind SVGLength-Objekte mit den Eigenschaften value (in Benutzereinheiten), valueInSpecifiedUnits, valueAsString und unitType.

Wie der Wert zu verstehen ist, hängt von maskUnits ab. Beim Standardwert objectBoundingBox ist y ein Bruchteil bzw. Prozentwert der Bounding Box des maskierten Elements. Voreingestellt ist -10%. Bei userSpaceOnUse ist y eine Koordinate im Benutzerkoordinatensystem des referenzierenden Elements.

Typische Einsatzfälle: den Maskenbereich per Skript auslesen, ihn dynamisch verschieben (z. B. für Einblende-Effekte) oder prüfen, ob eine Maske das Zielobjekt vollständig abdeckt.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (Grundwert, änderbar) und animVal (aktueller animierter Wert, schreibgeschützt), jeweils vom Typ SVGLength.

Beispiele

y-Wert einer Maske auslesen

// <svg><defs><mask id="m" x="0" y="20" width="100" height="60" maskUnits="userSpaceOnUse">…</mask></defs></svg>
const mask = document.getElementById('m');

console.log(mask.y.baseVal.value);         // Benutzereinheiten
console.log(mask.y.baseVal.valueAsString);
console.log(mask.y.animVal.value);

20 "20" 20

Standardwert und Einheit prüfen

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

// Ohne y-Attribut gilt der Standardwert -10 %
const len = mask.y.baseVal;
console.log(len.valueAsString);
console.log(len.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

"-10%" true

Maskenbereich per Skript verschieben (Einblende-Effekt)

const mask = document.querySelector('#reveal-mask');
mask.setAttribute('maskUnits', 'userSpaceOnUse');

let y = 200;
const step = () => {
  y -= 4;
  // baseVal ist änderbar, obwohl die Eigenschaft y selbst schreibgeschützt ist
  mask.y.baseVal.value = y;
  if (y > 0) requestAnimationFrame(step);
};
requestAnimationFrame(step);

console.log(mask.getAttribute('y')); // wird mitgeführt

Wert in bestimmter Einheit setzen

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

mask.y.baseVal.newValueSpecifiedUnits(
  SVGLength.SVG_LENGTHTYPE_PERCENTAGE,
  5
);
console.log(mask.getAttribute('y'));

"5%"

// Wichtig · Fallstricke

Schreibgeschützt heißt nur die Referenz: mask.y = 10 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Ändern lässt sich der Wert über mask.y.baseVal.value oder setAttribute('y', …).
animVal ist schreibgeschützt. Er unterscheidet sich von baseVal nur, solange eine SMIL-Animation (<animate>) läuft.
Einheiten hängen von maskUnits ab: Bei objectBoundingBox ist ein Wert wie 0.2 ein Anteil der Bounding Box, keine Pixelangabe. Bei Prozentwerten kann baseVal.value je nach Kontext 0 oder einen relativ zum Viewport berechneten Wert liefern. Genauer ist dann valueInSpecifiedUnits.
Nicht verwechseln mit maskContentUnits: Dieses Attribut betrifft nur das Koordinatensystem des Maskeninhalts, nicht x/y/width/height.
Die Eigenschaft wird seit vielen Jahren von allen gängigen Browsern unterstützt. Die Elemente müssen mit createElementNS im SVG-Namensraum erzeugt werden, sonst gibt es kein SVGMaskElement.

Siehe auch

SVGMaskElement SVGMaskElement.x SVGMaskElement.width SVGMaskElement.height SVGMaskElement.maskUnits SVGAnimatedLength SVGLength