SVGFEGaussianBlurElement.setStdDeviation() — Methode · JavaScript-Referenz

Signatur

SVGFEGaussianBlurElement.prototype.setStdDeviation(stdDeviationX, stdDeviationY)

Beschreibung

Die Methode setStdDeviation() der Schnittstelle SVGFEGaussianBlurElement legt die Stärke eines Gaußschen Weichzeichners fest. Sie setzt beide Werte des Attributs stdDeviation auf einmal: den horizontalen (X) und den vertikalen (Y) Anteil. Je größer der Wert, desto stärker die Unschärfe.

Das ist praktisch, wenn man Unschärfe per Skript animieren oder an Benutzereingaben koppeln will, etwa bei einem Schieberegler, einem Hover-Effekt oder einem Fokus-Effekt, bei dem der Hintergrund verschwimmt. Mit unterschiedlichen Werten für X und Y lassen sich auch gerichtete Unschärfen erzeugen, zum Beispiel ein Bewegungseffekt nur in horizontaler Richtung.

Nach dem Aufruf stehen die Werte auch in den animierten Eigenschaften stdDeviationX.baseVal und stdDeviationY.baseVal. Wer lieber mit Attributen arbeitet, kann dasselbe mit setAttribute("stdDeviation", "x y") erreichen.

Parameter

Name	Typ	Default	Beschreibung
$stdDeviationX Pflicht	number		Standardabweichung in X-Richtung, also horizontal, in Einheiten des Filter-Koordinatensystems (`primitiveUnits`). Muss 0 oder größer sein.
$stdDeviationY Pflicht	number		Standardabweichung in Y-Richtung, also vertikal. Muss 0 oder größer sein. Für eine gleichmäßige Unschärfe übergibt man denselben Wert wie bei `stdDeviationX`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Gleichmäßige Unschärfe setzen

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
svg.setAttribute('width', '200');
svg.setAttribute('height', '120');

const filter = document.createElementNS(svgNS, 'filter');
filter.id = 'weich';
const blur = document.createElementNS(svgNS, 'feGaussianBlur');
blur.setAttribute('in', 'SourceGraphic');
filter.append(blur);

const rect = document.createElementNS(svgNS, 'rect');
rect.setAttribute('x', '40');
rect.setAttribute('y', '20');
rect.setAttribute('width', '120');
rect.setAttribute('height', '80');
rect.setAttribute('fill', 'tomato');
rect.setAttribute('filter', 'url(#weich)');

svg.append(filter, rect);
document.body.append(svg);

// Unschärfe in beide Richtungen gleich stark
blur.setStdDeviation(4, 4);
console.log(blur.getAttribute('stdDeviation'));
console.log(blur.stdDeviationX.baseVal, blur.stdDeviationY.baseVal);

4 4 4 4

Horizontale Bewegungsunschärfe

// Annahme: <feGaussianBlur id="blur"> steht in einem <filter> im Dokument
const blur = document.querySelector('#blur');

// Nur in X-Richtung weichzeichnen, dadurch entsteht ein Bewegungseffekt
blur.setStdDeviation(10, 0);
console.log(blur.stdDeviationX.baseVal, blur.stdDeviationY.baseVal);

10 0

Unschärfe über einen Schieberegler steuern

// HTML: <input type="range" id="staerke" min="0" max="20" value="0">
const slider = document.querySelector('#staerke');
const blur = document.querySelector('#blur');

slider.addEventListener('input', () => {
  const wert = Number(slider.value);
  blur.setStdDeviation(wert, wert);
});

// Wichtig · Fallstricke

Negative Werte sind ein Fehler: Das Filterprimitiv wird dann abgeschaltet und in den meisten Browsern gar nicht mehr dargestellt. Prüfe Benutzereingaben deshalb vorher, zum Beispiel mit Math.max(0, wert).
Ein Wert von 0 in einer Richtung schaltet die Unschärfe nur in dieser Richtung ab. Sind beide Werte 0, wird das Bild unverändert durchgereicht.
Performance: Große Werte und häufige Änderungen, etwa in einer Animation mit requestAnimationFrame, sind teuer zu berechnen, besonders bei großen Flächen. Bei reinen HTML-Elementen ist CSS filter: blur() oft schneller.
Die Methode schreibt auf das Attribut, also auf baseVal. Läuft gleichzeitig eine SMIL-Animation (<animate>) auf stdDeviation, bestimmt diese den sichtbaren Wert (animVal).
Kompatibilität: Die Methode gehört zu SVG 1.1 und wird von allen aktuellen Browsern unterstützt. Sie funktioniert nur an Elementen, die mit createElementNS im SVG-Namensraum erzeugt wurden.

Siehe auch

SVGFEGaussianBlurElement SVGFEGaussianBlurElement.stdDeviationX SVGFEGaussianBlurElement.stdDeviationY SVGFilterElement Element.setAttribute()