SVGFESpotLightElement.z — Eigenschaft · JavaScript-Referenz

Signatur

SVGFESpotLightElement.z

Beschreibung

Die Eigenschaft z der Schnittstelle SVGFESpotLightElement steht für das Attribut z des SVG-Elements <feSpotLight>. Sie gibt die Position der Spotlicht-Quelle auf der Z-Achse an, also wie weit sie „über“ der Zeichenfläche liegt. Zusammen mit x und y legt sie die Position der Lichtquelle im Koordinatensystem fest, das über primitiveUnits des umgebenden <filter>-Elements bestimmt wird.

Der Rückgabewert ist ein SVGAnimatedNumber-Objekt. Über baseVal liest und setzt man den statischen Attributwert, animVal liefert den aktuellen (ggf. per SMIL animierten) Wert und ist schreibgeschützt. Die Eigenschaft z selbst lässt sich nicht neu zuweisen.

Man nutzt z vor allem, um Licht-Effekte in <feDiffuseLighting> oder <feSpecularLighting> dynamisch zu steuern, z. B. um die Lichtquelle interaktiv anzuheben oder abzusenken. Ein größerer Z-Wert führt zu flacherem, gleichmäßigerem Licht, ein kleiner Wert zu einem stärker streifenden Lichteinfall.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Objekt mit baseVal (lesbar/schreibbar, number) und animVal (nur lesbar, number). Standardwert des Attributs ist 0.

Beispiele

Z-Position einer Spotlicht-Quelle auslesen

// HTML: <svg><filter id="licht"><feSpecularLighting><feSpotLight id="spot" x="50" y="50" z="120"/></feSpecularLighting></filter></svg>
const spot = document.querySelector('#spot');
console.log(spot.z.baseVal);
console.log(spot.z.animVal);

120 120

Lichtquelle per Schieberegler anheben

const spot = document.querySelector('#spot');
const regler = document.querySelector('#hoehe'); // <input type="range" min="10" max="400">

regler.addEventListener('input', () => {
  // baseVal setzen aktualisiert das Attribut z sofort
  spot.z.baseVal = Number(regler.value);
  console.log(spot.getAttribute('z'));
});

z. B. "250" nach Verschieben des Reglers

Spotlicht komplett per Skript erzeugen

const NS = 'http://www.w3.org/2000/svg';
const lighting = document.querySelector('feDiffuseLighting');
const spot = document.createElementNS(NS, 'feSpotLight');

spot.x.baseVal = 100;
spot.y.baseVal = 80;
spot.z.baseVal = 200;
spot.pointsAtZ.baseVal = 0;

lighting.append(spot);
console.log(spot.z.baseVal, spot.getAttribute('z'));

200 "200"

// Wichtig · Fallstricke

spot.z = 100 hat keine Wirkung (bzw. wirft im Strict Mode einen TypeError) – immer spot.z.baseVal setzen.
animVal ist schreibgeschützt; bei laufender SMIL-Animation weicht es von baseVal ab.
Die Einheit hängt von primitiveUnits des Filters ab: Bei objectBoundingBox ist z ein Bruchteil der Elementgröße – Werte wie 100 wirken dann völlig anders als erwartet.
Das Element muss mit createElementNS im SVG-Namensraum erzeugt werden, sonst existiert die Eigenschaft nicht.
In allen modernen Browsern unterstützt; Licht-Filter können bei großen Flächen rechenintensiv sein und Animationen verlangsamen.

Siehe auch

SVGFESpotLightElement SVGFESpotLightElement.x SVGFESpotLightElement.y SVGFESpotLightElement.pointsAtZ SVGAnimatedNumber SVGFEPointLightElement.z WorkerNavigator.gpu