SVGFEConvolveMatrixElement.preserveAlpha — Eigenschaft · JavaScript-Referenz

Signatur

get SVGFEConvolveMatrixElement.preserveAlpha

Beschreibung

Die schreibgeschützte Eigenschaft preserveAlpha der Schnittstelle SVGFEConvolveMatrixElement gibt ein SVGAnimatedBoolean-Objekt zurück. Es spiegelt das SVG-Attribut preserveAlpha des Filterprimitivs <feConvolveMatrix> wider. Das Attribut legt fest, ob die Faltungsmatrix auch auf den Alphakanal angewendet wird.

false (Standard): Die Faltung wirkt auf alle Kanäle, also auf Rot, Grün, Blau und Alpha.
true: Die Faltung wirkt nur auf die Farbkanäle. Der Alphakanal der Eingabe bleibt unverändert.

Über preserveAlpha.baseVal liest oder setzt du den Grundwert. Beim Setzen wird das Attribut im DOM mit aktualisiert. preserveAlpha.animVal ist nur lesbar und enthält den aktuellen Wert, auch während einer SMIL-Animation. Nur die Eigenschaft selbst, also die Objektreferenz, ist schreibgeschützt. Der Wert lässt sich über baseVal sehr wohl ändern.

Praktisch nutzt du die Eigenschaft, wenn du Effekte wie Schärfen, Kantenerkennung oder Prägung per Skript umschaltest. Mit preserveAlpha = true vermeidest du ungewollt ausgefranste oder halbtransparente Ränder, zum Beispiel bei Text oder Icons mit transparentem Hintergrund.

Rückgabewert

Typ

SVGAnimatedBoolean

Beschreibung

Objekt mit den Eigenschaften baseVal (boolean, les- und schreibbar) und animVal (boolean, nur lesbar). Fehlt das Attribut, ist der Wert false.

Beispiele

Aktuellen Wert auslesen

// <svg><filter id="sharpen"><feConvolveMatrix id="conv" order="3"
//   kernelMatrix="0 -1 0 -1 5 -1 0 -1 0" preserveAlpha="true"/></filter></svg>
const conv = document.getElementById('conv');

console.log(conv.preserveAlpha instanceof SVGAnimatedBoolean);
console.log(conv.preserveAlpha.baseVal);
console.log(conv.preserveAlpha.animVal);

true true true

Alphakanal per Checkbox schützen oder freigeben

const conv = document.querySelector('#sharpen feConvolveMatrix');
const toggle = document.querySelector('#keep-alpha');

toggle.addEventListener('change', () => {
  // baseVal setzen aktualisiert auch das DOM-Attribut
  conv.preserveAlpha.baseVal = toggle.checked;
  console.log(conv.getAttribute('preserveAlpha'));
});

"true" bzw. "false" je nach Checkbox-Zustand

Prägefilter dynamisch erzeugen

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

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

const conv = document.createElementNS(SVG_NS, 'feConvolveMatrix');
conv.setAttribute('order', '3');
conv.setAttribute('kernelMatrix', '-2 -1 0 -1 1 1 0 1 2');

console.log('Standard:', conv.preserveAlpha.baseVal);
conv.preserveAlpha.baseVal = true; // transparente Ränder erhalten

filter.append(conv);
svg.querySelector('defs').append(filter);
document.querySelector('#logo').setAttribute('filter', 'url(#emboss)');

Standard: false

// Wichtig · Fallstricke

Nicht direkt zuweisen: el.preserveAlpha = true hat keine Wirkung. Im Strict Mode, also auch in ES-Modulen, wirft die Zuweisung sogar einen TypeError. Setze stattdessen immer el.preserveAlpha.baseVal.
animVal ist nur lesbar. Ein Schreibversuch wird ignoriert bzw. wirft im Strict Mode einen Fehler.
Im Markup sind nur die Attributwerte "true" und "false" gültig. Andere Werte gelten als Fehler, dann greift der Standardwert false.
Bei preserveAlpha="false" werden die Farbwerte vorher vormultipliziert (premultiplied alpha) verarbeitet. Das kann bei halbtransparenten Pixeln zu anderen Farben führen als erwartet.
Faltungsfilter sind rechenintensiv. Häufiges Umschalten auf großen Flächen kann die Darstellung spürbar bremsen.
Wird von allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge).

Siehe auch

SVGFEConvolveMatrixElement SVGAnimatedBoolean SVGFEConvolveMatrixElement.kernelMatrix SVGFEConvolveMatrixElement.edgeMode SVGFEConvolveMatrixElement.divisor SVGFilterElement