SVGMaskElement.x — Eigenschaft · JavaScript-Referenz

Signatur

SVGMaskElement.x

Beschreibung

Die Eigenschaft x des Interfaces SVGMaskElement gibt die x-Koordinate der linken oberen Ecke des Maskenbereichs zurück, also des Rechtecks, außerhalb dessen die Maske nichts durchlässt. Der Wert entspricht dem Attribut x des <mask>-Elements.

Die Eigenschaft selbst ist schreibgeschützt: Sie liefert immer dasselbe SVGAnimatedLength-Objekt. Über dessen baseVal (ein SVGLength) kann der Wert aber gelesen und geändert werden. animVal enthält den aktuellen, ggf. durch SMIL-Animation veränderten Wert, und lässt sich nur lesen.

Wie der Wert zu verstehen ist, hängt von maskUnits ab: Beim Standard objectBoundingBox ist x ein Bruchteil bzw. Prozentsatz der Bounding-Box des maskierten Elements (Standardwert -10%). Bei userSpaceOnUse ist es eine Koordinate im Nutzerkoordinatensystem.

Typische Einsatzfälle sind das dynamische Verschieben oder Vergrößern eines Maskenbereichs per Skript, zum Beispiel für Einblend-Effekte oder interaktive Hervorhebungen.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Objekt mit baseVal (änderbares SVGLength) und animVal (schreibgeschützter, animierter Wert) für das x-Attribut der Maske.

Beispiele

x-Wert einer Maske auslesen

// <svg><defs><mask id="m" x="10" y="10" width="80" height="80" maskUnits="userSpaceOnUse">...</mask></defs></svg>
const mask = document.getElementById('m');
const { baseVal } = mask.x;
console.log(baseVal.value);          // Zahlenwert in Nutzereinheiten
console.log(baseVal.valueAsString);  // Attribut-Schreibweise
console.log(baseVal.unitType === SVGLength.SVG_LENGTHTYPE_NUMBER);

10 "10" true

Standardwert bei objectBoundingBox

const svgNS = 'http://www.w3.org/2000/svg';
const mask = document.createElementNS(svgNS, 'mask');
// Kein x-Attribut gesetzt, daher gilt der Standardwert -10 %
console.log(mask.x.baseVal.valueAsString);
console.log(mask.x.baseVal.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

"-10%" true

Maskenbereich per Slider verschieben

const mask = document.querySelector('#spotlight-mask');
const slider = document.querySelector('#pos');

slider.addEventListener('input', () => {
  // baseVal ist beschreibbar, das Attribut wird automatisch aktualisiert
  mask.x.baseVal.value = Number(slider.value);
  console.log(mask.getAttribute('x'));
});

z. B. "42"

Wert mit Einheit setzen

const mask = document.querySelector('mask');
// Setzt x auf 25 % – newValueSpecifiedUnits erlaubt eine explizite Einheit
mask.x.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 25);
console.log(mask.getAttribute('x'));

"25%"

// Wichtig · Fallstricke

Nicht direkt zuweisen: mask.x = 20 hat keine Wirkung, ändern Sie stattdessen mask.x.baseVal.value oder nutzen Sie setAttribute('x', …).
Einheiten beachten: Bei Prozentwerten kann das Lesen von baseVal.value (also in Nutzereinheiten umgerechnet) je nach Browser 0 liefern oder eine Exception auslösen, wenn kein Bezugs-Viewport ermittelt werden kann. Sicherer sind valueInSpecifiedUnits bzw. valueAsString.
Die Bedeutung des Werts hängt von maskUnits ab. Nicht zu verwechseln mit maskContentUnits, das nur das Koordinatensystem des Masken-Inhalts festlegt.
animVal ist schreibgeschützt. Ein Schreibversuch löst einen NoModificationAllowedError aus.
Wird die Maske mit document.createElement('mask') statt mit createElementNS erzeugt, entsteht kein SVGMaskElement, und x ist dann undefined.
Die Eigenschaft wird von allen modernen Browsern unterstützt.

Siehe auch

SVGMaskElement SVGMaskElement.y SVGMaskElement.width SVGMaskElement.height SVGMaskElement.maskUnits SVGAnimatedLength SVGLength