SVGFEFloodElement.y — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEFloodElement.y

Beschreibung

Die schreibgeschützte Eigenschaft y der Schnittstelle SVGFEFloodElement gibt das y-Attribut des zugehörigen <feFlood>-Elements als SVGAnimatedLength zurück. Zusammen mit x, width und height legt sie den Teilbereich (primitive subregion) fest, den die Filterprimitive mit Farbe füllt.

Das zurückgegebene Objekt hat zwei Eigenschaften: baseVal ist der im Attribut gesetzte Grundwert und lässt sich beschreiben, animVal ist der aktuelle Wert inklusive laufender SMIL-Animationen und nur lesbar. Beide sind SVGLength-Objekte mit value (in Benutzereinheiten), valueInSpecifiedUnits, unitType und Methoden wie convertToSpecifiedUnits().

Nützlich ist die Eigenschaft, wenn man Filterbereiche per Skript auswerten oder verändern will, etwa um eine Farbfläche nur über einen Teil des Elements zu legen oder ihre Position dynamisch zu animieren. Wie der Wert gedeutet wird, hängt vom Attribut primitiveUnits des übergeordneten <filter> ab: Bei userSpaceOnUse (Standard) gilt er als Benutzerkoordinate, bei objectBoundingBox als Bruchteil bzw. Prozentwert der Bounding-Box.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein SVGAnimatedLength-Objekt mit baseVal (beschreibbar) und animVal (nur lesbar), beide vom Typ SVGLength. Ist kein y-Attribut gesetzt, beträgt der Wert 0%, d. h. der Bereich beginnt am oberen Rand des Filterbereichs.

Beispiele

y-Wert eines feFlood-Elements auslesen

// HTML:
// <svg width="200" height="200">
//   <filter id="flut">
//     <feFlood id="flood" y="40" height="80" flood-color="tomato" />
//   </filter>
//   <rect width="200" height="200" filter="url(#flut)" />
// </svg>

const flood = document.getElementById('flood');
const y = flood.y;

console.log(y instanceof SVGAnimatedLength);
console.log(y.baseVal.value);
console.log(y.baseVal.unitType === SVGLength.SVG_LENGTHTYPE_NUMBER);

true 40 true

Position per Skript verändern

const flood = document.querySelector('feFlood');

// Grundwert direkt in Benutzereinheiten setzen
flood.y.baseVal.value = 100;
console.log(flood.getAttribute('y'));

// Oder mit expliziter Einheit (Prozent)
flood.y.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 25);
console.log(flood.getAttribute('y'));

100 25%

Farbstreifen von oben nach unten wandern lassen

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

const step = () => {
  pos = (pos + 2) % 200;
  flood.y.baseVal.value = pos;
  requestAnimationFrame(step);
};

requestAnimationFrame(step);

baseVal und animVal bei SMIL-Animation vergleichen

// <feFlood id="flood" y="0" height="50" flood-color="teal">
//   <animate attributeName="y" from="0" to="150" dur="3s" repeatCount="indefinite" />
// </feFlood>

const flood = document.getElementById('flood');

setTimeout(() => {
  console.log('Grundwert:', flood.y.baseVal.value);
  console.log('Animiert:', flood.y.animVal.value.toFixed(0));
}, 1500);

Grundwert: 0 Animiert: 75

// Wichtig · Fallstricke

Schreibgeschützt: flood.y = 10 hat keine Wirkung (im Strict-Modus gibt es einen TypeError). Ändern lässt sich der Wert nur über flood.y.baseVal.value, newValueSpecifiedUnits() oder setAttribute('y', …).
animVal ist nur lesbar: Schreibzugriffe darauf werfen einen NoModificationAllowedError.
Einheiten: baseVal.value liefert immer Benutzereinheiten. Bei Prozentwerten oder primitiveUnits="objectBoundingBox" sollte man mit valueInSpecifiedUnits und unitType arbeiten, damit man den Wert richtig deutet.
Clipping: Liegt der Bereich der Primitive außerhalb des Filterbereichs (Attribute x/y/width/height am <filter>), wird er abgeschnitten. Die Farbfläche ist dann nur teilweise oder gar nicht zu sehen.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Die Eigenschaft kommt aus dem gemeinsamen Mixin SVGFilterPrimitiveStandardAttributes und verhält sich bei allen SVGFE*Element-Schnittstellen gleich.

Siehe auch

SVGFEFloodElement SVGFEFloodElement.x SVGFEFloodElement.width SVGFEFloodElement.height SVGFEFloodElement.result SVGAnimatedLength SVGLength SVGFilterElement