SVGFEOffsetElement.dy — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEOffsetElement.dy

Beschreibung

Die Eigenschaft dy des Interfaces SVGFEOffsetElement spiegelt das Attribut dy eines <feOffset>-Filterprimitivs wider. Dieses Attribut legt fest, um wie viel das Eingangsbild (in) vertikal verschoben wird. Positive Werte verschieben nach unten, negative nach oben.

Der Rückgabewert ist ein SVGAnimatedNumber-Objekt. Die Eigenschaft selbst ist schreibgeschützt – man kann ihr kein neues Objekt zuweisen –, aber über dy.baseVal lässt sich der Wert lesen und ändern. dy.animVal liefert den aktuell wirksamen Wert, also inklusive laufender SMIL-Animationen (<animate>).

Typische Einsatzfälle sind Schlagschatten (Kombination aus feGaussianBlur, feOffset und feMerge), bei denen die Schattenrichtung per JavaScript dynamisch angepasst wird – etwa abhängig von Mausposition oder Scrollzustand. Das Gegenstück für die horizontale Verschiebung ist SVGFEOffsetElement.dx.

Der Wert wird in den Einheiten des Koordinatensystems interpretiert, das durch primitiveUnits des umgebenden <filter>-Elements festgelegt ist (Standard: userSpaceOnUse). Fehlt das Attribut, ist der Wert 0.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Objekt mit baseVal (änderbarer Basiswert aus dem Attribut) und animVal (schreibgeschützter, aktuell animierter Wert). Standardwert ist 0.

Beispiele

dy-Wert eines Schlagschatten-Filters auslesen

// <svg><filter id="schatten"><feOffset id="versatz" in="SourceAlpha" dx="4" dy="6"/></filter></svg>
const offset = document.getElementById('versatz');

console.log(offset.dy.baseVal);
console.log(offset.dy.animVal);
console.log(offset.dy instanceof SVGAnimatedNumber);

6 6 true

Vertikalen Versatz per JavaScript ändern

const offset = document.querySelector('#schatten feOffset');

// Schatten weiter nach unten verschieben
offset.dy.baseVal = 12;

// Das Attribut wird automatisch synchronisiert
console.log(offset.getAttribute('dy'));

12

Schattenrichtung an die Mausposition koppeln

const svg = document.querySelector('svg');
const offset = svg.querySelector('feOffset');

svg.addEventListener('pointermove', (event) => {
  const rect = svg.getBoundingClientRect();
  const mitteY = rect.top + rect.height / 2;
  // Schatten fällt von der Maus weg, max. ±10 Einheiten
  const faktor = (mitteY - event.clientY) / (rect.height / 2);
  offset.dy.baseVal = Math.round(faktor * 10);
});

Neues feOffset-Element erzeugen und dy setzen

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

const offset = document.createElementNS(SVG_NS, 'feOffset');
offset.setAttribute('in', 'SourceGraphic');
offset.dy.baseVal = -5; // nach oben verschieben
filter.append(offset);

console.log(offset.dy.baseVal, offset.getAttribute('dy'));

-5 -5

// Wichtig · Fallstricke

Nicht direkt zuweisen: offset.dy = 10 hat keine Wirkung (bzw. wirft im Strict-Mode einen TypeError). Immer offset.dy.baseVal = 10 verwenden.
animVal ist schreibgeschützt und spiegelt nur SMIL-Animationen wider; CSS-Animationen beeinflussen dy nicht, da dy keine CSS-Eigenschaft ist.
Elemente müssen mit document.createElementNS() im SVG-Namensraum erzeugt werden, sonst existiert die Eigenschaft nicht.
Die Einheit hängt von primitiveUnits ab: Bei objectBoundingBox ist dy="0.1" ein Anteil der Elementhöhe, nicht 0,1 Pixel.
Häufiges Ändern von Filterwerten (z. B. bei jedem pointermove) kann aufwendig neu gerendert werden; bei Bedarf mit requestAnimationFrame drosseln.
Kompatibilität: in allen modernen Browsern (Chrome, Firefox, Safari, Edge) seit Langem unterstützt.

Siehe auch

SVGFEOffsetElement SVGFEOffsetElement.dx SVGFEOffsetElement.in1 SVGAnimatedNumber SVGFEDropShadowElement.dy HTMLSourceElement.src SVGStyleElement.disabled