SVGFEDisplacementMapElement.y — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEDisplacementMapElement.y

Beschreibung

Die schreibgeschützte Eigenschaft y der Schnittstelle SVGFEDisplacementMapElement steht für das SVG-Attribut y des Elements <feDisplacementMap>. Zusammen mit x, width und height legt sie den Filter-Primitive-Teilbereich fest, also das Rechteck, auf das die Verschiebung (Displacement) wirkt und auf das ihr Ergebnis begrenzt wird.

Zurückgegeben wird ein SVGAnimatedLength-Objekt. Über baseVal kommt man an den statischen Wert aus dem Attribut. Diesen kann man lesen und auch ändern. animVal enthält den aktuellen Wert, falls gerade eine SMIL-Animation läuft, und kann nur gelesen werden. Beide sind SVGLength-Objekte mit value (in Benutzereinheiten), valueInSpecifiedUnits, unitType und valueAsString.

Wie der Wert gedeutet wird, hängt vom Attribut primitiveUnits des übergeordneten <filter> ab. Bei userSpaceOnUse (Standard) gilt er als Koordinate im Benutzerkoordinatensystem. Bei objectBoundingBox gilt er als Anteil bzw. Prozentsatz der Bounding-Box des gefilterten Elements. Fehlt das Attribut, ist der Standardwert 0%: Der Teilbereich beginnt dann oben am Filterbereich.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (lesbar und änderbar, SVGLength) und animVal (nur lesbar, SVGLength), das die vertikale Position des Filter-Primitive-Teilbereichs beschreibt.

Beispiele

y-Wert eines feDisplacementMap auslesen

// HTML: <svg><filter id="f"><feDisplacementMap id="dm" in="SourceGraphic" in2="noise" scale="20" y="10"/></filter></svg>
const dm = document.querySelector('#dm');

console.log(dm.y.baseVal.value);          // Wert in Benutzereinheiten
console.log(dm.y.baseVal.valueAsString);  // Wert als Zeichenkette
console.log(dm.y.baseVal.unitType === SVGLength.SVG_LENGTHTYPE_NUMBER);

10 "10" true

Vertikale Position per Skript ändern

const svgNS = 'http://www.w3.org/2000/svg';
const filter = document.createElementNS(svgNS, 'filter');
const dm = document.createElementNS(svgNS, 'feDisplacementMap');
filter.append(dm);

// Den Teilbereich 25 % tiefer beginnen lassen
dm.y.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 25);

console.log(dm.getAttribute('y'));
console.log(dm.y.baseVal.valueInSpecifiedUnits);

25% 25

Verzerrung nur auf die untere Hälfte anwenden (objectBoundingBox)

// HTML:
// <svg width="300" height="200">
//   <filter id="wave" primitiveUnits="objectBoundingBox">
//     <feTurbulence baseFrequency="0.05" result="noise"/>
//     <feDisplacementMap id="dm" in="SourceGraphic" in2="noise" scale="0.05" height="0.5"/>
//   </filter>
//   <rect width="300" height="200" fill="teal" filter="url(#wave)"/>
// </svg>
const dm = document.querySelector('#dm');

// Bei objectBoundingBox: 0.5 = halbe Höhe der Bounding-Box
dm.y.baseVal.value = 0.5;
console.log(dm.y.baseVal.value);

0.5

// Wichtig · Fallstricke

Die Eigenschaft selbst ist schreibgeschützt: dm.y = 10 wird ignoriert bzw. löst im Strict Mode einen Fehler aus. Ändern kann man den Wert nur über dm.y.baseVal oder mit setAttribute('y', …).
animVal kann nur gelesen werden. Einen Wert darauf zu setzen, löst eine NoModificationAllowedError-Ausnahme aus.
Ob der Wert als Benutzerkoordinate oder als Anteil der Bounding-Box gilt, entscheidet primitiveUnits am <filter>. Das wird leicht übersehen. Liegt der Teilbereich außerhalb des Filterbereichs (x/y/width/height des <filter>), wird er abgeschnitten.
Ein Wert wie baseVal.value bei Prozentangaben lässt sich nur dann zuverlässig in Benutzereinheiten umrechnen, wenn das Element im gerenderten Dokument hängt.
Wird von allen modernen Browsern (Chrome, Firefox, Safari, Edge) unterstützt. Das Verhalten entspricht den Eigenschaften y anderer Filterprimitiven wie SVGFEGaussianBlurElement.y.

Siehe auch

SVGFEDisplacementMapElement SVGFEDisplacementMapElement.x SVGFEDisplacementMapElement.width SVGFEDisplacementMapElement.height SVGFEDisplacementMapElement.scale SVGAnimatedLength SVGLength