SVGFESpotLightElement.pointsAtZ — Eigenschaft · JavaScript-Referenz

Signatur

SVGFESpotLightElement.pointsAtZ

Beschreibung

Die Eigenschaft pointsAtZ der Schnittstelle SVGFESpotLightElement spiegelt das gleichnamige Attribut des <feSpotLight>-Elements wider. Sie gibt die Z-Koordinate des Zielpunkts an, auf den der Lichtkegel des Spotlichts gerichtet ist. Zusammen mit pointsAtX und pointsAtY legt sie die Richtung des Lichts fest, während x, y und z die Position der Lichtquelle bestimmen.

Der Rückgabewert ist ein SVGAnimatedNumber-Objekt. Über baseVal liest und schreibt man den im Attribut festgelegten Grundwert, über animVal den aktuellen, ggf. durch SMIL-Animation (<animate>) veränderten Wert. Die Eigenschaft selbst ist schreibgeschützt – man kann ihr also kein neues Objekt zuweisen, wohl aber baseVal ändern.

Typische Einsatzfälle sind interaktive Beleuchtungseffekte: etwa ein Spotlicht, das dem Mauszeiger folgt, oder das dynamische Anpassen der Lichttiefe in <feDiffuseLighting>- und <feSpecularLighting>-Filtern. Fehlt das Attribut, ist der Wert 0.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Objekt mit baseVal (Grundwert, beschreibbar, number) und animVal (aktueller animierter Wert, schreibgeschützt). Standardwert ist 0.

Beispiele

Wert von pointsAtZ auslesen

// SVG im Dokument:
// <svg width="200" height="200">
//   <filter id="licht">
//     <feDiffuseLighting in="SourceGraphic" diffuseConstant="1">
//       <feSpotLight id="spot" x="50" y="50" z="100"
//         pointsAtX="100" pointsAtY="100" pointsAtZ="0"
//         limitingConeAngle="30" />
//     </feDiffuseLighting>
//   </filter>
//   <rect width="200" height="200" fill="steelblue" filter="url(#licht)" />
// </svg>

const spot = document.getElementById('spot');
console.log(spot.pointsAtZ instanceof SVGAnimatedNumber);
console.log(spot.pointsAtZ.baseVal);
console.log(spot.pointsAtZ.animVal);

true 0 0

Zielpunkt dynamisch per baseVal ändern

const spot = document.querySelector('feSpotLight');

// Zielpunkt tiefer legen – Lichtkegel wirkt steiler
spot.pointsAtZ.baseVal = -50;

// Das Attribut wird automatisch synchronisiert
console.log(spot.getAttribute('pointsAtZ'));

-50

Spotlicht folgt der Maus, Tiefe per Mausrad

const svg = document.querySelector('svg');
const spot = svg.querySelector('feSpotLight');

svg.addEventListener('mousemove', (event) => {
  const rect = svg.getBoundingClientRect();
  spot.pointsAtX.baseVal = event.clientX - rect.left;
  spot.pointsAtY.baseVal = event.clientY - rect.top;
});

svg.addEventListener('wheel', (event) => {
  event.preventDefault();
  const neu = spot.pointsAtZ.baseVal - Math.sign(event.deltaY) * 10;
  spot.pointsAtZ.baseVal = Math.max(-200, Math.min(200, neu));
  console.log(`pointsAtZ: ${spot.pointsAtZ.baseVal}`);
}, { passive: false });

pointsAtZ: 10 (je nach Scrollrichtung)

// Wichtig · Fallstricke

Schreibgeschützt: spot.pointsAtZ = 10 hat keine Wirkung (im Strict Mode ggf. TypeError). Immer spot.pointsAtZ.baseVal setzen.
animVal ist nur lesbar und weicht nur während einer SMIL-Animation von baseVal ab.
Die Koordinaten beziehen sich auf das durch primitiveUnits des <filter> festgelegte Koordinatensystem. Bei primitiveUnits="objectBoundingBox" sind Werte als Bruchteile der Bounding-Box zu verstehen – die Umrechnung für Z ist dabei browserabhängig und oft überraschend.
Attributnamen in SVG sind case-sensitiv: getAttribute('pointsAtZ'), nicht pointsatz.
Häufige Filter-Neuberechnungen (z. B. bei mousemove) können auf großen Flächen teuer sein; ggf. per requestAnimationFrame drosseln.
Kompatibilität: In allen modernen Browsern (Chrome, Firefox, Safari, Edge) seit langem unterstützt.

Siehe auch

SVGFESpotLightElement SVGFESpotLightElement.pointsAtX SVGFESpotLightElement.pointsAtY SVGFESpotLightElement.z SVGFESpotLightElement.limitingConeAngle SVGAnimatedNumber