SVGMaskElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGMaskElement extends SVGElement

Beschreibung

SVGMaskElement ist die DOM-Schnittstelle für das SVG-Element <mask>. Mit einer Maske legt man fest, welche Teile eines Elements wie stark sichtbar sind. Grundlage ist die Luminanz (Helligkeit) oder der Alphakanal des Maskeninhalts: Weiß heißt voll sichtbar, Schwarz unsichtbar, Grautöne ergeben Teiltransparenz. Angewendet wird die Maske über das Attribut bzw. die CSS-Eigenschaft mask="url(#id)".

Die Schnittstelle erbt von SVGElement (und damit von Element, Node und EventTarget) und hat folgende schreibgeschützte, animierbare Eigenschaften:

x, y, width, height – jeweils SVGAnimatedLength; beschreiben den Maskenbereich.
maskUnits – SVGAnimatedEnumeration; Koordinatensystem für x/y/width/height (userSpaceOnUse oder objectBoundingBox, Standard).
maskContentUnits – SVGAnimatedEnumeration; Koordinatensystem für den Inhalt der Maske (Standard userSpaceOnUse).

Jede animierte Eigenschaft hat einen baseVal (änderbarer Grundwert) und einen animVal (aktueller, ggf. animierter Wert, nur lesbar). Eigene Methoden definiert die Schnittstelle nicht. Man benutzt sie etwa, um Masken per Skript zu erzeugen, den Maskenbereich dynamisch anzupassen oder Übergänge und „Enthüllungs“-Effekte umzusetzen.

Rückgabewert

Typ

SVGMaskElement

Beschreibung

Instanzen entstehen über document.createElementNS("http://www.w3.org/2000/svg", "mask") oder durch Abfrage eines vorhandenen <mask>-Elements. Einen direkt aufrufbaren Konstruktor gibt es nicht.

Beispiele

Maske per Skript erzeugen und anwenden

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('width', '200');
svg.setAttribute('height', '200');

const defs = document.createElementNS(SVG_NS, 'defs');
const mask = document.createElementNS(SVG_NS, 'mask');
mask.id = 'kreisMaske';

// Weißer Kreis = sichtbarer Bereich
const circle = document.createElementNS(SVG_NS, 'circle');
circle.setAttribute('cx', '100');
circle.setAttribute('cy', '100');
circle.setAttribute('r', '60');
circle.setAttribute('fill', 'white');
mask.append(circle);
defs.append(mask);

const rect = document.createElementNS(SVG_NS, 'rect');
rect.setAttribute('width', '200');
rect.setAttribute('height', '200');
rect.setAttribute('fill', 'tomato');
rect.setAttribute('mask', 'url(#kreisMaske)');

svg.append(defs, rect);
document.body.append(svg);

console.log(mask instanceof SVGMaskElement);

true

Maskenbereich und Einheiten auslesen

// <mask id="m" x="-10%" y="-10%" width="120%" height="120%"> ... </mask>
const mask = document.querySelector('#m');

const { x, width, maskUnits, maskContentUnits } = mask;
console.log(x.baseVal.valueAsString);      // Grundwert als Text
console.log(width.baseVal.valueAsString);

const units = {
  [SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE]: 'userSpaceOnUse',
  [SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX]: 'objectBoundingBox'
};
console.log(units[maskUnits.baseVal]);
console.log(units[maskContentUnits.baseVal]);

-10% 120% objectBoundingBox userSpaceOnUse

Enthüllungs-Effekt durch Ändern des Maskenbereichs

// <mask id="reveal" maskUnits="userSpaceOnUse" x="0" y="0" width="0" height="200">
//   <rect width="400" height="200" fill="white"/>
// </mask>
const mask = document.querySelector('#reveal');
const ziel = 400;

const schritt = () => {
  const w = mask.width.baseVal;
  if (w.value < ziel) {
    w.value = Math.min(ziel, w.value + 8); // Maske wächst nach rechts
    requestAnimationFrame(schritt);
  }
};
requestAnimationFrame(schritt);

// Wichtig · Fallstricke

Namensraum: document.createElement('mask') erzeugt ein HTMLUnknownElement und kein SVGMaskElement. Immer createElementNS('http://www.w3.org/2000/svg', 'mask') nutzen.
Nur lesbare Eigenschaften: mask.width = 100 schlägt fehl bzw. hat keine Wirkung. Ändern kann man nur mask.width.baseVal.value oder das Attribut per setAttribute().
Standardbereich: Ohne Angabe gilt x=\"-10%\" y=\"-10%\" width=\"120%\" height=\"120%\" in objectBoundingBox. Hat das maskierte Element keine Fläche (z. B. eine waagerechte Linie mit einer Höhe von 0), wird es mit objectBoundingBox nicht dargestellt – verwende dann userSpaceOnUse.
Luminanz vs. Alpha: Standardmäßig wertet SVG die Luminanz aus. Farbiger Inhalt wirkt deshalb teiltransparent. Über die CSS-Eigenschaft mask-type: alpha lässt sich auf den Alphakanal umstellen.
Performance: Masken sind beim Rendern teurer als clipPath. Für harte Kanten ohne Transparenz ist SVGClipPathElement meist die bessere Wahl.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Die CSS-Eigenschaft mask auf HTML-Elementen brauchte in älteren WebKit-/Blink-Versionen das Präfix -webkit-.

Siehe auch

SVGAElement SVGDescElement SVGImageElement SVGMPathElement SVGMarkerElement