SVGFEImageElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGFEImageElement extends SVGElement

Beschreibung

SVGFEImageElement steht für das Element <feImage> innerhalb eines <filter>. Das Primitiv holt eine Grafik (PNG, JPEG, SVG-Datei oder ein Element aus demselben Dokument) und stellt sie als Bild-Ergebnis für nachfolgende Filterprimitive wie <feComposite>, <feBlend> oder <feDisplacementMap> bereit.

Die Schnittstelle erbt von SVGElement und bindet die Mixins SVGFilterPrimitiveStandardAttributes (x, y, width, height, result) und SVGURIReference (href) ein. Dazu kommen die eigenen Eigenschaften preserveAspectRatio und crossOrigin. Alle Eigenschaften sind animierte Werte (SVGAnimated…): Gelesen wird über .baseVal bzw. .animVal, geschrieben am einfachsten über setAttribute().

Typische Einsatzfälle sind Texturen und Muster für Filtereffekte, Verschiebungskarten (Displacement Maps) für Verzerrungen, Wasserzeichen oder das Überblenden eines Fotos mit einer Form. Da es sich um eine Schnittstelle handelt, wird sie nicht mit new erzeugt, sondern über document.createElementNS() mit dem SVG-Namensraum.

Parameter

Name	Typ	Default	Beschreibung
$href	SVGAnimatedString	—	Nur lesbar. Entspricht dem Attribut `href` (bzw. veraltet `xlink:href`) — URL des Bildes oder Fragmentverweis `#id`.
$preserveAspectRatio	SVGAnimatedPreserveAspectRatio	xMidYMid meet	Nur lesbar. Steuert, wie das Bild in den Filterbereich eingepasst wird.
$crossOrigin	SVGAnimatedString	—	Entspricht dem Attribut `crossorigin` (`anonymous` oder `use-credentials`) für CORS-Anfragen.
$x / y / width / height	SVGAnimatedLength	—	Nur lesbar. Teilbereich des Filterprimitivs (aus `SVGFilterPrimitiveStandardAttributes`).
$result	SVGAnimatedString	—	Nur lesbar. Name des Ergebnisses, auf das andere Primitive per `in`/`in2` verweisen.

Rückgabewert

Typ

SVGFEImageElement

Beschreibung

Instanzen erhält man über document.createElementNS('http://www.w3.org/2000/svg', 'feImage') oder per querySelector('feImage').

Beispiele

feImage per Skript erzeugen und in einen Filter einbauen

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

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

const feImage = document.createElementNS(SVG_NS, 'feImage');
feImage.setAttribute('href', '/img/papier.png');
feImage.setAttribute('preserveAspectRatio', 'xMidYMid slice');
feImage.setAttribute('result', 'bild');

const feComposite = document.createElementNS(SVG_NS, 'feComposite');
feComposite.setAttribute('in', 'bild');
feComposite.setAttribute('in2', 'SourceGraphic');
feComposite.setAttribute('operator', 'in');

filter.append(feImage, feComposite);
svg.querySelector('defs').append(filter);

document.querySelector('#logo').setAttribute('filter', 'url(#textur)');
console.log(feImage instanceof SVGFEImageElement);

true

Animierte Eigenschaften auslesen

// <feImage id="img" href="bild.png" x="10" y="20" width="200" height="100" result="foto"/>
const feImage = document.getElementById('img');

console.log(feImage.href.baseVal);
console.log(feImage.x.baseVal.value, feImage.width.baseVal.value);
console.log(feImage.result.baseVal);

const par = feImage.preserveAspectRatio.baseVal;
console.log(par.align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMIDYMID);

bild.png 10 200 foto true

Bildquelle dynamisch wechseln (Displacement Map)

const feImage = document.querySelector('#verzerrung feImage');
const karten = ['/maps/welle.png', '/maps/rauschen.png'];
let i = 0;

document.querySelector('#wechseln').addEventListener('click', () => {
  i = (i + 1) % karten.length;
  // href.baseVal ist beschreibbar, alternativ setAttribute('href', …)
  feImage.href.baseVal = karten[i];
  console.log('Aktive Karte:', feImage.href.baseVal);
});

Aktive Karte: /maps/rauschen.png

// Wichtig · Fallstricke

Firefox unterstützt in <feImage> keine Verweise auf Elemente im selben Dokument (href="#form") — nur externe Bilder bzw. Data-URLs. Für browserübergreifenden Code die Grafik als Datei oder data:-URL einbinden.
xlink:href ist veraltet; nutze href. Für sehr alte Safari-Versionen ggf. beide setzen (setAttributeNS('http://www.w3.org/1999/xlink', 'xlink:href', …)).
Elemente immer mit createElementNS() und SVG-Namensraum erzeugen — document.createElement('feImage') liefert ein wirkungsloses HTMLUnknownElement.
Fremd-Ursprungs-Bilder ohne CORS können den Filter bzw. ein darauf basierendes Canvas „verunreinigen“ (tainted). Die Eigenschaft crossOrigin ist relativ neu und nicht überall verfügbar.
Die Eigenschaften sind SVGAnimated…-Objekte: feImage.x = 5 hat keine Wirkung, korrekt ist feImage.x.baseVal.value = 5 oder setAttribute('x', 5).
Große Bilder in Filtern sind rechenintensiv; das Bild wird bei jeder Neuzeichnung gerastert.

Siehe auch

SVGImageElement SVGAnimateElement SVGFEMergeElement SVGFETileElement HTMLImageElement