SVGFEConvolveMatrixElement.x — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.x

Beschreibung

Die Eigenschaft x der Schnittstelle SVGFEConvolveMatrixElement gibt das Attribut x des Elements <feConvolveMatrix> zurück. Sie legt die linke Kante des Filterprimitiv-Teilbereichs fest. Das ist der rechteckige Bereich, auf den die Faltung (zum Beispiel zum Schärfen, Weichzeichnen oder Prägen) beschränkt wird. Zusammen mit y, width und height bestimmt sie diesen Bereich.

Die Eigenschaft selbst ist schreibgeschützt, denn sie liefert immer dasselbe SVGAnimatedLength-Objekt. Den Wert ändern Sie über x.baseVal (ein SVGLength-Objekt), zum Beispiel mit baseVal.value, baseVal.valueInSpecifiedUnits oder baseVal.newValueSpecifiedUnits(). Alternativ geht auch setAttribute("x", …). Der Wert x.animVal enthält den gerade gültigen Wert, wenn eine SMIL-Animation läuft. Ohne Animation entspricht er baseVal.

Wie der Wert ausgelegt wird, hängt vom Attribut primitiveUnits des umgebenden <filter>-Elements ab. Beim Standard userSpaceOnUse ist der Wert eine Koordinate im Benutzerkoordinatensystem. Bei objectBoundingBox ist er ein Bruchteil bzw. Prozentsatz der Bounding Box des gefilterten Elements. Fehlt das Attribut, gilt standardmäßig 0%, das Primitiv beginnt dann also an der linken Kante des Filterbereichs.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein SVGAnimatedLength-Objekt mit baseVal (das statische Attribut, veränderbar) und animVal (der aktuell animierte Wert, nur lesbar). Beide sind SVGLength-Objekte.

Beispiele

x-Position eines feConvolveMatrix auslesen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
svg.innerHTML = `
  <filter id="schaerfen">
    <feConvolveMatrix id="conv" x="10" y="5" width="80" height="60"
      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.x instanceof SVGAnimatedLength);
console.log(conv.x.baseVal.value);
console.log(conv.x.animVal.value);

true 10 10

Position per baseVal ändern

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

// Nicht möglich: conv.x = 20 (die Eigenschaft ist schreibgeschützt)
conv.x.baseVal.value = 20;

// Das Attribut wird automatisch angepasst
console.log(conv.getAttribute('x'));

20

Prozentwert mit Einheit setzen

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

// Einheit und Wert gemeinsam setzen
conv.x.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 25);

console.log(conv.getAttribute('x'));
console.log(conv.x.baseVal.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);
console.log(conv.x.baseVal.valueInSpecifiedUnits);

25% true 25

Wirkungsbereich des Filters verschieben (Animation mit JavaScript)

const conv = document.querySelector('feConvolveMatrix');
let pos = 0;

const schritt = () => {
  pos = (pos + 1) % 200;
  conv.x.baseVal.value = pos; // Scharfzeichnung wandert horizontal
  requestAnimationFrame(schritt);
};
requestAnimationFrame(schritt);

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie element.x = 10 hat keine Wirkung, im Strict Mode wirft sie einen TypeError. Ändern Sie den Wert immer über x.baseVal oder setAttribute().
Einheiten: Mit primitiveUnits="objectBoundingBox" ist ein Wert wie 0.1 gemeint, also 10 % der Bounding Box, und keine Pixelangabe. Bei Prozentwerten ist baseVal.value ein vom Browser umgerechneter Wert. Sicherer sind hier valueInSpecifiedUnits und unitType.
Kein Einfluss ohne Teilbereich: Wird x gesetzt, aber width nicht, reicht der Teilbereich bis zum rechten Rand des Filterbereichs. Pixel außerhalb des Teilbereichs sind im Ergebnis des Primitivs transparent.
animVal ist nur lesbar. Wer darauf schreibt, löst eine NoModificationAllowedError-Ausnahme aus.
Kompatibilität: Die Eigenschaft wird in allen aktuellen Browsern (Chrome, Firefox, Safari, Edge) unterstützt. Sie stammt aus der gemeinsamen Schnittstelle SVGFilterPrimitiveStandardAttributes und verhält sich deshalb bei allen fe*-Elementen gleich.
Leistung: Faltungsfilter sind rechenintensiv. Wenn der Wert in jedem Frame geändert wird, wird der Filter jedes Mal neu berechnet. Das kann auf großen Flächen spürbar ruckeln.

Siehe auch

SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.y SVGFEConvolveMatrixElement.width SVGFEConvolveMatrixElement.height SVGAnimatedLength SVGLength SVGFilterElement