SVGFEColorMatrixElement.y — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEColorMatrixElement.y

Beschreibung

Die Eigenschaft y des Interfaces SVGFEColorMatrixElement gibt das y-Attribut des zugehörigen <feColorMatrix>-Elements als SVGAnimatedLength-Objekt zurück. Dieses Attribut legt die obere Kante des Filter-Primitive-Teilbereichs fest, also des Rechtecks, auf das die Farbmatrix wirkt und auf das ihr Ergebnis beschnitten wird.

Die Eigenschaft selbst ist schreibgeschützt: Man kann ihr kein neues Objekt zuweisen. Den Wert ändert man stattdessen über y.baseVal, zum Beispiel über baseVal.value, baseVal.valueAsString oder baseVal.newValueSpecifiedUnits(). y.animVal enthält den aktuell wirksamen, eventuell durch SMIL-Animation veränderten Wert und kann nur gelesen werden.

Wie der Wert zu verstehen ist, hängt vom Attribut primitiveUnits des übergeordneten <filter> ab. Bei userSpaceOnUse (Standard) ist es eine Länge im Benutzerkoordinatensystem. Bei objectBoundingBox ist es ein Bruchteil der Bounding-Box des gefilterten Elements. Fehlt das Attribut, beträgt der Standardwert 0% des Filterbereichs.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (veränderbare SVGLength, entspricht dem Attributwert) und animVal (schreibgeschützte SVGLength mit dem aktuell animierten Wert).

Beispiele

y-Position auslesen

// <svg><filter id="grau"><feColorMatrix id="cm" type="saturate" values="0" y="20"/></filter></svg>
const cm = document.getElementById('cm');

console.log(cm.y instanceof SVGAnimatedLength);
console.log(cm.y.baseVal.value);
console.log(cm.y.animVal.value);

true 20 20

Nur die untere Bildhälfte entsättigen

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

const filter = document.createElementNS(svgNS, 'filter');
filter.id = 'untenGrau';
filter.setAttribute('primitiveUnits', 'objectBoundingBox');

const cm = document.createElementNS(svgNS, 'feColorMatrix');
cm.setAttribute('type', 'saturate');
cm.setAttribute('values', '0');

// Teilbereich beginnt bei 50 % der Höhe
cm.y.baseVal.valueAsString = '0.5';
cm.height.baseVal.valueAsString = '0.5';

filter.append(cm);
svg.append(filter);
svg.querySelector('image').setAttribute('filter', 'url(#untenGrau)');

console.log(cm.getAttribute('y'));

0.5

Einheit mit newValueSpecifiedUnits wechseln

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

// y auf 25 % setzen
cm.y.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 25);
console.log(cm.y.baseVal.valueAsString);
console.log(cm.getAttribute('y'));

25% 25%

Falsch: direkte Zuweisung wirkt nicht

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

cm.y = 100; // wird ignoriert (im Strict Mode: TypeError)
console.log(cm.y instanceof SVGAnimatedLength);

// Richtig:
cm.y.baseVal.value = 100;
console.log(cm.getAttribute('y'));

true 100

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie el.y = 10 hat keine Wirkung. In Modulen und im Strict Mode löst sie einen TypeError aus. Werte ändert man über el.y.baseVal oder setAttribute('y', …).
animVal ist nur lesbar: Wer animVal.value setzt, bekommt einen NoModificationAllowedError.
Einheiten: Bei primitiveUnits="objectBoundingBox" sind Werte wie 0.5 Bruchteile der Bounding-Box. Prozentangaben verhalten sich dort je nach Browser unterschiedlich, deshalb am besten Dezimalbrüche verwenden.
Liegt der Teilbereich außerhalb der Filterregion (<filter> mit x/y/width/height), wird das Ergebnis zusätzlich beschnitten.
Elemente müssen mit createElementNS und dem SVG-Namensraum erzeugt werden. Sonst gibt es keine y-Eigenschaft.
Kompatibilität: wird von allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Die Eigenschaft stammt aus SVGFilterPrimitiveStandardAttributes.

Siehe auch

SVGFEColorMatrixElement SVGFEColorMatrixElement.x SVGFEColorMatrixElement.width SVGFEColorMatrixElement.height SVGAnimatedLength SVGLength SVGFilterElement