SVGFEPointLightElement.z — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEPointLightElement.z

Beschreibung

Die Eigenschaft z des Interfaces SVGFEPointLightElement entspricht dem Attribut z eines <fePointLight>-Elements. Sie gibt an, wie weit die Punktlichtquelle „über“ der Zeichenfläche liegt. Die Werte gelten im Koordinatensystem, das über primitiveUnits des umgebenden <filter>-Elements festgelegt ist. Ein positiver Wert bedeutet, dass das Licht in Richtung des Betrachters vor der Fläche steht.

Die Eigenschaft selbst ist schreibgeschützt. Sie liefert ein SVGAnimatedNumber-Objekt mit zwei Werten: baseVal ist der im Attribut gesetzte Grundwert und lässt sich beschreiben. animVal ist der aktuelle, eventuell per SMIL-Animation (<animate>) veränderte Wert und nur lesbar. Um die Lichtposition per Skript zu ändern, setzt man also z.baseVal oder nutzt setAttribute('z', …).

Typische Anwendungen sind interaktive Beleuchtungseffekte mit <feDiffuseLighting> oder <feSpecularLighting>, etwa eine Lichtquelle, die dem Mauszeiger folgt. Dabei steuert z, wie flach oder steil das Licht auf die Oberfläche fällt. Kleine Werte ergeben einen engen, harten Lichtkegel, große Werte eine breite, gleichmäßige Ausleuchtung.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Ein Objekt mit baseVal (beschreibbarer Grundwert des Attributs z, Standard 0) und animVal (schreibgeschützter, aktuell animierter Wert).

Beispiele

Z-Wert einer Punktlichtquelle auslesen

// HTML:
// <svg width="200" height="200">
//   <filter id="licht">
//     <feDiffuseLighting in="SourceGraphic" lighting-color="white">
//       <fePointLight id="punkt" x="100" y="100" z="50" />
//     </feDiffuseLighting>
//   </filter>
//   <rect width="200" height="200" fill="steelblue" filter="url(#licht)" />
// </svg>

const light = document.getElementById('punkt');
console.log(light.z instanceof SVGAnimatedNumber);
console.log(light.z.baseVal);
console.log(light.z.animVal);

true 50 50

Lichthöhe per Schieberegler steuern

// <input type="range" id="hoehe" min="5" max="300" value="50">
const light = document.querySelector('fePointLight');
const slider = document.getElementById('hoehe');

slider.addEventListener('input', () => {
  // baseVal ist beschreibbar, z selbst nicht
  light.z.baseVal = Number(slider.value);
  console.log(`Neue Lichthöhe: ${light.getAttribute('z')}`);
});

Neue Lichthöhe: 120

Licht folgt der Maus, Höhe bleibt konstant

const svg = document.querySelector('svg');
const light = svg.querySelector('fePointLight');
light.z.baseVal = 80;

svg.addEventListener('pointermove', (event) => {
  const rect = svg.getBoundingClientRect();
  light.x.baseVal = event.clientX - rect.left;
  light.y.baseVal = event.clientY - rect.top;
});

console.log(light.z.baseVal);

80

Direkte Zuweisung an z schlägt fehl

'use strict';
const light = document.querySelector('fePointLight');
try {
  light.z = 100; // nur ein Getter – im Strict Mode TypeError
} catch (err) {
  console.log(err instanceof TypeError);
}
light.z.baseVal = 100; // richtig
console.log(light.z.baseVal);

true 100

// Wichtig · Fallstricke

Schreibschutz: element.z = 10 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Schreiben Sie stattdessen element.z.baseVal.
animVal vs. baseVal: Läuft eine SMIL-Animation auf z, liefert animVal den aktuellen Wert. Änderungen an baseVal sind dann womöglich nicht sichtbar, bis die Animation endet.
Koordinatensystem: Mit primitiveUnits="objectBoundingBox" auf dem <filter> wird z relativ zur Bounding Box interpretiert. Werte wie 50 sind dann viel zu groß, sinnvoll sind Bruchteile wie 0.5.
Standardwert: Fehlt das Attribut, ist der Wert 0. Das Licht liegt dann in der Zeichenebene, und die Fläche wirkt fast unbeleuchtet.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Die Beleuchtungsfilter können bei großen Flächen und häufigen Updates, etwa bei pointermove, viel Rechenleistung kosten. Bündeln Sie Updates in solchen Fällen mit requestAnimationFrame.

Siehe auch

SVGFEPointLightElement SVGFEPointLightElement.x SVGFEPointLightElement.y SVGAnimatedNumber SVGFESpotLightElement SVGFEDiffuseLightingElement SVGFESpecularLightingElement