SVGFEOffsetElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGFEOffsetElement extends SVGElement

Beschreibung

SVGFEOffsetElement steht im DOM für das Element <feOffset> innerhalb eines <filter>. Das Filterprimitiv verschiebt sein Eingabebild um einen festen Versatz in x- und y-Richtung. Meist kombiniert man es mit <feGaussianBlur>, <feFlood>/<feComposite> und <feMerge>, um Schlagschatten oder Prägeeffekte zu bauen.

Die Schnittstelle erbt von SVGElement und implementiert die Filterprimitiv-Standardattribute (x, y, width, height, result). Eigene Eigenschaften sind:

in1 (SVGAnimatedString): entspricht dem Attribut in, also der Eingabe, z. B. SourceGraphic, SourceAlpha oder das result eines vorherigen Primitivs.
dx (SVGAnimatedNumber): horizontaler Versatz.
dy (SVGAnimatedNumber): vertikaler Versatz.

Alle Eigenschaften sind animierte Werte. Den Wert, der im Attribut steht, liest und schreibt man über .baseVal. Den aktuell dargestellten Wert (etwa während einer SMIL-Animation) liefert .animVal, der nur gelesen werden kann. Beim Schreiben von baseVal wird das zugehörige Attribut automatisch aktualisiert.

Parameter

Name	Typ	Default	Beschreibung
$in1	SVGAnimatedString	leer (= Ergebnis des vorherigen Primitivs bzw. SourceGraphic)	Schreibgeschützte Eigenschaft, die das Attribut `in` widerspiegelt. Den Wert setzt man über `in1.baseVal`.
$dx	SVGAnimatedNumber	0	Horizontaler Versatz, entspricht dem Attribut `dx`. Er wird im Koordinatensystem gemessen, das `primitiveUnits` des Filters festlegt.
$dy	SVGAnimatedNumber	0	Vertikaler Versatz, entspricht dem Attribut `dy`.
$result	SVGAnimatedString		Name des Zwischenergebnisses, über den spätere Primitive mit `in`/`in2` darauf verweisen.
$x / y / width / height	SVGAnimatedLength	0% / 0% / 100% / 100%	Legen die Region des Filterprimitivs fest, auf die das Ergebnis beschnitten wird.

Rückgabewert

Typ

SVGFEOffsetElement

Beschreibung

Eine Instanz erhält man über document.createElementNS('http://www.w3.org/2000/svg', 'feOffset') oder indem man ein vorhandenes <feOffset>-Element im DOM abfragt. Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Schlagschatten-Filter per JavaScript erzeugen

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

const filter = document.createElementNS(SVG_NS, 'filter');
filter.id = 'schatten';

// 1. Alpha-Kanal weichzeichnen
const blur = document.createElementNS(SVG_NS, 'feGaussianBlur');
blur.setAttribute('in', 'SourceAlpha');
blur.setAttribute('stdDeviation', '3');
blur.setAttribute('result', 'blur');

// 2. Weichgezeichnetes Bild verschieben
const offset = document.createElementNS(SVG_NS, 'feOffset');
offset.in1.baseVal = 'blur';
offset.dx.baseVal = 4;
offset.dy.baseVal = 4;
offset.result.baseVal = 'versatz';

// 3. Schatten und Original zusammenführen
const merge = document.createElementNS(SVG_NS, 'feMerge');
for (const quelle of ['versatz', 'SourceGraphic']) {
  const node = document.createElementNS(SVG_NS, 'feMergeNode');
  node.setAttribute('in', quelle);
  merge.append(node);
}

filter.append(blur, offset, merge);
svg.querySelector('defs')?.append(filter) ?? svg.prepend(filter);
svg.querySelector('rect').setAttribute('filter', 'url(#schatten)');

console.log(offset instanceof SVGFEOffsetElement, offset.getAttribute('dx'));

true "4"

Vorhandenes feOffset auslesen und ändern

// <filter id="f"><feOffset id="off" in="SourceGraphic" dx="10" dy="5"/></filter>
const off = document.getElementById('off');

console.log(off.in1.baseVal);          // Eingabe
console.log(off.dx.baseVal, off.dy.baseVal);

off.dy.baseVal = -8;                   // Attribut wird mit aktualisiert
console.log(off.getAttribute('dy'));

SourceGraphic 10 5 -8

Schatten interaktiv an die Mausposition koppeln

const off = document.querySelector('#schatten feOffset');
const box = document.querySelector('svg');

const folgeMaus = (event) => {
  const rect = box.getBoundingClientRect();
  const cx = rect.left + rect.width / 2;
  const cy = rect.top + rect.height / 2;
  // Schatten zeigt von der "Lichtquelle" (Maus) weg, max. 10 Einheiten
  off.dx.baseVal = Math.max(-10, Math.min(10, (cx - event.clientX) / 20));
  off.dy.baseVal = Math.max(-10, Math.min(10, (cy - event.clientY) / 20));
};

window.addEventListener('pointermove', folgeMaus);

// Wichtig · Fallstricke

Namensraum: Mit document.createElement('feOffset') entsteht nur ein unbekanntes HTML-Element ohne Filterwirkung. Nötig ist immer createElementNS('http://www.w3.org/2000/svg', 'feOffset').
in1 statt in: in ist ein reserviertes Wort in JavaScript, deshalb heißt die DOM-Eigenschaft in1. Das Markup-Attribut heißt weiterhin in.
baseVal vs. animVal: animVal kann nur gelesen werden. Direkte Zuweisungen wie offset.dx = 5 bewirken nichts, man muss offset.dx.baseVal = 5 schreiben.
Einheiten: dx/dy hängen von primitiveUnits des Filters ab. Bei objectBoundingBox bedeutet dx=\"0.1\" 10 % der Elementbreite und nicht 0,1 Pixel.
Beschnitt: Große Versätze werden an der Filterregion abgeschnitten (Standard: −10 %/120 %). Bei Bedarf x, y, width und height des <filter> vergrößern.
Performance: Wenn man Filterattribute häufig ändert, z. B. bei pointermove, muss der Filter jedes Mal neu berechnet werden. Bei großen Flächen sollte man die Aufrufe drosseln oder requestAnimationFrame verwenden. Für einfache Fälle ist die CSS-Funktion drop-shadow() oft schneller.
Kompatibilität: Wird von allen aktuellen Browsern seit Langem unterstützt.

Siehe auch

SVGDefsElement SVGFEFloodElement SVGFEFuncAElement SVGFEFuncBElement SVGFEFuncGElement