SVGFEConvolveMatrixElement.width — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.width

Beschreibung

Die Eigenschaft width des Interfaces SVGFEConvolveMatrixElement gibt die horizontale Ausdehnung des Filterprimitiv-Teilbereichs (filter primitive subregion) eines <feConvolveMatrix>-Elements zurück. Sie spiegelt das SVG-Attribut width wider und stammt aus dem Mixin SVGFilterPrimitiveStandardAttributes, das auch x, y, height und result bereitstellt.

Der Rückgabewert ist ein SVGAnimatedLength-Objekt. Die Eigenschaft selbst ist schreibgeschützt, das Objekt aber nicht: Über width.baseVal lässt sich der Grundwert lesen und ändern (z. B. per value, valueAsString oder newValueSpecifiedUnits()), während width.animVal den aktuellen, ggf. durch SMIL-Animation veränderten Wert liefert.

Praktisch nutzt man die Eigenschaft, um den Wirkungsbereich einer Faltungsmatrix (Schärfen, Weichzeichnen, Kantenerkennung, Prägeeffekt) per Skript auszulesen oder dynamisch anzupassen, etwa damit der Effekt nur auf einen Teil der Grafik wirkt. Ist das Attribut nicht gesetzt, gilt als Standard 100% des Filterbereichs.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (veränderbarer Grundwert als SVGLength) und animVal (schreibgeschützter, animierter Wert als SVGLength).

Beispiele

Breite eines feConvolveMatrix-Elements auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
svg.innerHTML = `
  <filter id="schaerfen">
    <feConvolveMatrix id="conv" x="0" y="0" width="150" height="100"
      order="3" kernelMatrix="0 -1 0 -1 5 -1 0 -1 0" />
  </filter>`;
document.body.append(svg);

const conv = svg.querySelector('#conv');
console.log(conv.width instanceof SVGAnimatedLength);
console.log(conv.width.baseVal.value);
console.log(conv.width.animVal.value);

true 150 150

Breite per Skript ändern

const conv = document.querySelector('feConvolveMatrix');

// Grundwert direkt als Zahl (Benutzereinheiten) setzen
conv.width.baseVal.value = 200;
console.log(conv.getAttribute('width'));

// Wert mit Einheit setzen, z. B. Prozent
conv.width.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 50);
console.log(conv.getAttribute('width'));

200 50%

Wirkungsbereich des Filters per Schieberegler steuern

const conv = document.querySelector('#conv');
const slider = document.querySelector('#breite'); // <input type="range" min="0" max="100">

slider.addEventListener('input', () => {
  conv.width.baseVal.valueAsString = `${slider.value}%`;
  console.log(`Filterbreite: ${conv.width.baseVal.valueAsString}`);
});

Filterbreite: 42%

// Wichtig · Fallstricke

Schreibgeschützt: conv.width = 100 hat keine Wirkung (im strikten Modus ggf. TypeError). Ändern Sie stattdessen conv.width.baseVal oder nutzen Sie setAttribute('width', …).
animVal ist immer schreibgeschützt; Schreibversuche lösen eine DOMException (NoModificationAllowedError) aus.
Prozentwerte beziehen sich je nach primitiveUnits des umgebenden <filter> auf unterschiedliche Bezugsgrößen; bei primitiveUnits="objectBoundingBox" werden Werte als Bruchteile der Bounding Box interpretiert. baseVal.value kann für Prozentwerte ohne gerenderten Kontext unerwartete Ergebnisse liefern.
Ein Wert von 0 oder negativ deaktiviert den Effekt des Primitivs (negative Werte sind ein Fehler).
Browser-Kompatibilität: In allen modernen Browsern (Chrome, Firefox, Safari, Edge) unterstützt; SMIL-Animationen für animVal ebenfalls, im alten Internet Explorer jedoch nicht.

Siehe auch

SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.height SVGFEConvolveMatrixElement.x SVGFEConvolveMatrixElement.y SVGAnimatedLength SVGLength