SVGFETurbulenceElement.y — Eigenschaft · JavaScript-Referenz

Signatur

SVGFETurbulenceElement.y

Beschreibung

Die Eigenschaft y der Schnittstelle SVGFETurbulenceElement spiegelt das SVG-Attribut y des Elements <feTurbulence> wider. Sie gibt die vertikale Koordinate der oberen Kante des Teilbereichs an, in dem das Filter-Primitive sein Ergebnis erzeugt (filter primitive subregion).

Die Eigenschaft selbst ist schreibgeschützt: Man kann ihr kein neues Objekt zuweisen. Das zurückgegebene SVGAnimatedLength-Objekt stellt aber zwei Werte bereit: baseVal (der im Attribut gesetzte, änderbare Grundwert als SVGLength) und animVal (der aktuelle, ggf. durch SMIL-Animation veränderte, schreibgeschützte Wert).

Nützlich ist y vor allem, wenn man den Rauschbereich eines Turbulenz-Filters per Skript auslesen oder dynamisch verschieben will, etwa für animierte Texturen, Wolken- oder Wassereffekte. Fehlt das Attribut, gilt standardmäßig 0% relativ zur Filterregion.

Wie die Angabe interpretiert wird, hängt vom Attribut primitiveUnits des umschließenden <filter> ab: Bei userSpaceOnUse (Standard) sind es Benutzerkoordinaten, bei objectBoundingBox Bruchteile der Bounding-Box des gefilterten Elements.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Objekt mit baseVal (änderbare SVGLength des Attributwerts) und animVal (aktueller, animierter Wert, schreibgeschützt).

Beispiele

y-Wert eines feTurbulence-Elements auslesen

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

turb.setAttribute('type', 'fractalNoise');
turb.setAttribute('baseFrequency', '0.05');
turb.setAttribute('y', '20');

filter.append(turb);
svg.append(filter);
document.body.append(svg);

console.log(turb.y.baseVal.value);
console.log(turb.y.animVal.value);

20 20

Standardwert ohne gesetztes Attribut

const turb = document.createElementNS('http://www.w3.org/2000/svg', 'feTurbulence');
const { baseVal } = turb.y;

// SVGLength.SVG_LENGTHTYPE_PERCENTAGE === 2
console.log(baseVal.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);
console.log(baseVal.valueAsString);

true 0%

Rauschbereich per Skript vertikal verschieben

// HTML: <svg><filter id="noise"><feTurbulence id="t" baseFrequency="0.02" y="0" height="100"/></filter>...</svg>
const turb = document.querySelector('#t');
let offset = 0;

const animate = () => {
  offset = (offset + 1) % 200;
  // baseVal ist änderbar, die Eigenschaft y selbst nicht
  turb.y.baseVal.value = offset;
  requestAnimationFrame(animate);
};
requestAnimationFrame(animate);

Wert mit Einheit setzen

const turb = document.querySelector('feTurbulence');
// Prozentwert relativ zur Filterregion
turb.y.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 10);
console.log(turb.getAttribute('y'));

10%

// Wichtig · Fallstricke

Schreibgeschützt: turb.y = 10 hat keine Wirkung (im Strict Mode TypeError). Ändern Sie stattdessen turb.y.baseVal.value oder das Attribut per setAttribute('y', …).
animVal kann man nicht beschreiben. Ohne laufende SMIL-Animation entspricht es baseVal.
Bei primitiveUnits="objectBoundingBox" sind Werte wie 0.1 gemeint (Anteil der Bounding-Box), keine Pixel. Das führt schnell zu Verwirrung.
Prozentwerte lassen sich erst sinnvoll in Benutzereinheiten umrechnen (baseVal.value), wenn das Element im gerenderten Dokument hängt.
Häufiges Ändern von Filter-Attributen löst jedes Mal ein erneutes Rendern des Filters aus. feTurbulence ist rechenintensiv, also vorsichtig animieren.
Kompatibilität: wird in allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge).

Siehe auch

SVGFETurbulenceElement SVGFETurbulenceElement.x SVGFETurbulenceElement.width SVGFETurbulenceElement.height SVGAnimatedLength SVGLength Window.launchQueue