SVGFEMergeElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGFEMergeElement extends SVGElement

Beschreibung

SVGFEMergeElement steht im DOM für das SVG-Element <feMerge>. Dieser Filterbaustein legt mehrere Zwischenergebnisse eines Filters übereinander. Dafür nutzt er die normale Alpha-Überblendung (source-over). Welche Ebenen zusammengefügt werden, legen die Kindelemente <feMergeNode> fest (Schnittstelle SVGFEMergeNodeElement). Jedes davon verweist mit dem Attribut in auf eine Eingabe. Die Reihenfolge im Dokument bestimmt die Stapelung: Der erste Knoten liegt ganz unten, der letzte ganz oben.

Typische Anwendungen sind Schlagschatten, Leuchteffekte oder Konturen, bei denen das Original über einen bearbeiteten Hintergrund gelegt wird – etwa ein weichgezeichnetes, verschobenes Alpha-Bild unter der SourceGraphic. Genau das ginge zwar auch mit mehreren <feComposite>-Schritten, <feMerge> ist dafür aber deutlich kürzer und übersichtlicher.

Die Schnittstelle hat keine eigenen Methoden. Sie erbt von SVGElement und bindet die Eigenschaften aus SVGFilterPrimitiveStandardAttributes ein:

x, y, width, height – jeweils SVGAnimatedLength (schreibgeschützt). Sie begrenzen den Bereich, in dem der Filterbaustein wirkt.
result – SVGAnimatedString (schreibgeschützt). Unter diesem Namen können spätere Filterbausteine das Ergebnis weiterverwenden.

Instanzen erzeugt man nicht mit einem Konstruktor, sondern mit document.createElementNS("http://www.w3.org/2000/svg", "feMerge"). Alternativ holt man sie aus bereits vorhandenem SVG-Markup.

Rückgabewert

Typ

SVGFEMergeElement

Beschreibung

Das Elementobjekt, das createElementNS(..., "feMerge") oder eine DOM-Abfrage wie querySelector("feMerge") liefert.

Beispiele

Schlagschatten per Skript erzeugen und zusammenfügen

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

// Filter anlegen
const filter = document.createElementNS(SVG_NS, "filter");
filter.id = "schatten";

const blur = document.createElementNS(SVG_NS, "feGaussianBlur");
blur.setAttribute("in", "SourceAlpha");
blur.setAttribute("stdDeviation", "3");
blur.setAttribute("result", "weich");

const offset = document.createElementNS(SVG_NS, "feOffset");
offset.setAttribute("in", "weich");
offset.setAttribute("dx", "4");
offset.setAttribute("dy", "4");
offset.setAttribute("result", "versetzt");

// feMerge: Schatten unten, Original oben
const merge = document.createElementNS(SVG_NS, "feMerge");
for (const quelle of ["versetzt", "SourceGraphic"]) {
  const node = document.createElementNS(SVG_NS, "feMergeNode");
  node.setAttribute("in", quelle);
  merge.append(node);
}

filter.append(blur, offset, merge);
const defs = svg.querySelector("defs") ?? svg.insertBefore(document.createElementNS(SVG_NS, "defs"), svg.firstChild);
defs.append(filter);

svg.querySelector("rect").setAttribute("filter", "url(#schatten)");
console.log(merge instanceof SVGFEMergeElement);

true

Vorhandenes feMerge auslesen

// Markup: <filter id="glow"><feGaussianBlur stdDeviation="2" result="b"/>
//   <feMerge result="fertig"><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge></filter>
const merge = document.querySelector("#glow feMerge");

console.log(merge.result.baseVal);
console.log(merge.width.baseVal.valueAsString);

const ebenen = [...merge.querySelectorAll("feMergeNode")]
  .map((node) => node.in1.baseVal);
console.log(ebenen);

fertig 120% ["b", "SourceGraphic"]

Stapelreihenfolge zur Laufzeit umkehren

const merge = document.querySelector("#glow feMerge");

// Wenn man den ersten Knoten ans Ende hängt, landet er ganz oben
const umkehren = () => merge.append(merge.firstElementChild);

document.querySelector("#toggle").addEventListener("click", umkehren);

// Wichtig · Fallstricke

Eigenschaften nur lesbar: x, y, width, height und result sind animierte Objekte. Ändern kann man sie über merge.result.baseVal = "neu" oder über setAttribute(). Eine direkte Zuweisung wie merge.result = "neu" bewirkt nichts.
Namensraum beachten: document.createElement("feMerge") erzeugt nur ein unbekanntes HTML-Element und keine SVGFEMergeElement-Instanz. Nötig ist immer createElementNS mit dem SVG-Namensraum.
Standardbereich: Fehlen x/y/width/height, gilt der Filterbereich, standardmäßig -10 %/-10 %/120 %/120 %. Große Unschärfen oder Verschiebungen werden dann abgeschnitten. In dem Fall den Bereich am <filter> vergrößern.
Leeres feMerge: Ohne <feMergeNode>-Kinder ist das Ergebnis vollständig transparent.
Performance: SVG-Filter werden oft auf der CPU berechnet. Viele gefilterte Elemente oder Animationen können deshalb teuer werden. Für einfache Schatten ist CSS filter: drop-shadow() oft schneller.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt, auch seit Langem von älteren Versionen.

Siehe auch

SVGFEMergeNodeElement SVGFilterElement SVGFECompositeElement SVGFEGaussianBlurElement SVGFEOffsetElement SVGElement Document.createElementNS()