SVGFEColorMatrixElement.x — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEColorMatrixElement.x

Beschreibung

Die Eigenschaft x der Schnittstelle SVGFEColorMatrixElement gibt das Attribut x des zugehörigen <feColorMatrix>-Elements als SVGAnimatedLength-Objekt zurück. Zusammen mit y, width und height legt es den Teilbereich des Filterprimitivs fest, also das Rechteck, auf das die Farbmatrix-Operation angewendet und in dem ihr Ergebnis abgeschnitten wird.

Die Eigenschaft selbst ist schreibgeschützt: Man kann ihr kein neues Objekt zuweisen. Der enthaltene Wert lässt sich aber über x.baseVal (ein SVGLength) lesen und ändern, etwa mit baseVal.value, baseVal.valueAsString oder baseVal.newValueSpecifiedUnits(). x.animVal liefert den aktuellen, eventuell durch SMIL-Animation veränderten Wert und ist nur lesbar.

Ist kein x-Attribut gesetzt, gilt der Standardwert 0% relativ zur Filterregion. Wie der Wert gedeutet wird, hängt vom Attribut primitiveUnits des übergeordneten <filter> ab: Bei userSpaceOnUse (Standard) sind es Benutzerkoordinaten, bei objectBoundingBox Bruchteile der Begrenzungsbox des gefilterten Elements.

Brauchen wird man die Eigenschaft vor allem, wenn man Filterbereiche per Skript auslesen, verschieben oder animieren will. Ein Beispiel ist ein Graustufen-Effekt, der nur auf einen Teil einer Grafik wirken soll.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (änderbarer SVGLength, entspricht dem Attributwert) und animVal (schreibgeschützter, aktuell animierter Wert).

Beispiele

x-Position eines feColorMatrix auslesen

document.body.insertAdjacentHTML('beforeend', `
<svg width="200" height="100">
  <filter id="grau">
    <feColorMatrix id="cm" type="saturate" values="0" x="20" y="0" width="100" height="100"/>
  </filter>
</svg>`);

const cm = document.getElementById('cm');
console.log(cm.x instanceof SVGAnimatedLength);
console.log(cm.x.baseVal.value);
console.log(cm.x.baseVal.valueAsString);

true 20 20

Filterbereich per Skript verschieben

const cm = document.querySelector('feColorMatrix');

// Nicht erlaubt: cm.x = 50; (Eigenschaft ist schreibgeschützt)
cm.x.baseVal.value = 50;

// Das Attribut ist jetzt aktualisiert
console.log(cm.getAttribute('x'));

50

Wert in Prozent setzen und Einheit prüfen

const cm = document.querySelector('feColorMatrix');
const len = cm.x.baseVal;

len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 25);
console.log(len.valueAsString);
console.log(len.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

25% true

Graustufen-Streifen animiert über ein Bild laufen lassen

const cm = document.querySelector('#cm');
let pos = 0;

const tick = () => {
  pos = (pos + 2) % 200;
  cm.x.baseVal.value = pos;
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

// Wichtig · Fallstricke

Schreibschutz: Wer element.x = 10 zuweist, erreicht nichts; im Strict Mode gibt es einen TypeError. Werte werden immer über x.baseVal geändert oder direkt mit setAttribute('x', …).
animVal: x.animVal ist nur lesbar. Ein Schreibversuch löst eine NoModificationAllowedError-Ausnahme aus.
Einheiten: baseVal.value gibt immer Benutzereinheiten zurück. Bei Prozentangaben hängt das Ergebnis vom Kontext ab und kann 0 sein, solange das Element nicht gerendert ist. Für den exakten Attributwert eignet sich valueAsString.
primitiveUnits: Steht beim <filter> primitiveUnits="objectBoundingBox", bedeutet x="0.2" 20 % der Breite der Begrenzungsbox.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Die Eigenschaft ist Teil der gemeinsamen Schnittstelle SVGFilterPrimitiveStandardAttributes und daher bei allen SVGFE*Element-Typen gleich vorhanden.

Siehe auch

SVGFEColorMatrixElement.y SVGFEColorMatrixElement.width SVGFEColorMatrixElement.height SVGFEColorMatrixElement SVGAnimatedLength SVGLength VideoColorSpace.fullRange