SVGMaskElement.width — Eigenschaft · JavaScript-Referenz

Signatur

SVGMaskElement.width

Beschreibung

Die Eigenschaft width der Schnittstelle SVGMaskElement bildet das width-Attribut eines <mask>-Elements ab. Zusammen mit x, y und height legt sie den rechteckigen Bereich fest, in dem die Maske wirkt. Alles außerhalb dieses Bereichs wird vollständig ausgeblendet.

Die Eigenschaft selbst ist schreibgeschützt, man kann ihr also kein neues Objekt zuweisen. Sie liefert aber ein SVGAnimatedLength-Objekt mit zwei Teilen:

baseVal: ein SVGLength mit dem Wert aus dem Attribut. Dieser Wert ist beschreibbar, und Änderungen daran landen direkt im Attribut.
animVal: der aktuell dargestellte Wert, der sich z. B. durch SMIL-Animationen ändern kann. Dieser Wert ist nur lesbar.

Wie der Wert zu verstehen ist, hängt von maskUnits ab. Beim Standardwert objectBoundingBox bezieht sich die Breite auf den Begrenzungsrahmen (Bounding Box) des maskierten Elements. Ein Wert von 1 oder 100% entspricht dann genau dessen Breite. Bei userSpaceOnUse gilt der Wert im Koordinatensystem des Elements, das die Maske verwendet, also z. B. in Pixeln. Fehlt das Attribut, gilt die Vorgabe 120%.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (beschreibbares SVGLength mit dem Attributwert) und animVal (nur lesbares SVGLength mit dem aktuell dargestellten Wert).

Beispiele

Breite einer vorhandenen Maske auslesen

// HTML:
// <svg width="200" height="200">
//   <mask id="fade" width="80%" height="100%">
//     <rect width="100%" height="100%" fill="white" />
//   </mask>
// </svg>
const mask = document.getElementById('fade');
const { baseVal } = mask.width;

console.log(baseVal.valueAsString);        // Text wie im Attribut
console.log(baseVal.valueInSpecifiedUnits); // Zahl ohne Einheit
console.log(baseVal.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

80% 80 true

Breite zur Laufzeit ändern (z. B. Reveal-Effekt)

const mask = document.getElementById('fade');
const slider = document.querySelector('input[type=range]');

slider.addEventListener('input', () => {
  // baseVal ist beschreibbar – das Attribut wird automatisch angepasst
  mask.width.baseVal.newValueSpecifiedUnits(
    SVGLength.SVG_LENGTHTYPE_PERCENTAGE,
    Number(slider.value)
  );
  console.log(mask.getAttribute('width'));
});

z. B. 45%

Maske mit userSpaceOnUse per Skript erzeugen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg');

const mask = document.createElementNS(SVG_NS, 'mask');
mask.id = 'box-mask';
mask.setAttribute('maskUnits', 'userSpaceOnUse');
mask.setAttribute('x', '0');
mask.setAttribute('y', '0');
mask.setAttribute('width', '150');
mask.setAttribute('height', '100');
svg.append(mask);

console.log(mask.width.baseVal.value);  // Wert in Benutzereinheiten
console.log(mask.width.animVal.value);  // ohne Animation identisch

150 150

// Wichtig · Fallstricke

Keine direkte Zuweisung: mask.width = 100 hat keine Wirkung, im Strict Mode wird ein TypeError geworfen. Ändern Sie stattdessen mask.width.baseVal.value, verwenden Sie newValueSpecifiedUnits() oder rufen Sie setAttribute('width', …) auf.
Einheiten hängen von maskUnits ab: Bei objectBoundingBox bedeutet width="1" die volle Breite des Begrenzungsrahmens und nicht 1 Pixel. Das führt leicht zu unerwarteten Ergebnissen.
Prozentwerte und value: Die Umrechnung von Prozentwerten über baseVal.value in Benutzereinheiten kann zwischen Browsern abweichen. valueInSpecifiedUnits und valueAsString sind hier zuverlässiger.
Standardwert: Ohne width-Attribut ist der Maskenbereich 120 % breit (mit x = -10%). Das gibt Platz für Effekte wie Weichzeichner, die über den Rahmen hinausreichen.
Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt. In CSS kann mask dagegen auch andere Maskenquellen verwenden (z. B. mask-image), die nicht über diese Schnittstelle zugänglich sind.

Siehe auch

SVGMaskElement.height SVGMaskElement.x SVGMaskElement.y SVGMaskElement.maskUnits SVGMaskElement.maskContentUnits