SVGFilterElement.height — Eigenschaft · JavaScript-Referenz

Signatur

SVGFilterElement.height

Beschreibung

Die Eigenschaft height des Interfaces SVGFilterElement spiegelt das Attribut height eines <filter>-Elements wider. Gemeint ist die vertikale Ausdehnung des Filterbereichs (engl. filter region), also des Rechtecks, auf das der Filter wirkt und auf das sein Ergebnis zugeschnitten wird. Anders als die Kurzbeschreibung nahelegt, geht es nicht um eine einzelne Filterprimitive. Die Primitiven wie <feGaussianBlur> haben eigene height-Eigenschaften über SVGFilterPrimitiveStandardAttributes.

Zurückgegeben wird ein SVGAnimatedLength-Objekt mit zwei Werten:

baseVal: ein veränderbares SVGLength, das dem Attributwert entspricht. Eine Änderung schreibt das Attribut automatisch zurück.
animVal: ein schreibgeschütztes SVGLength mit dem aktuellen Wert, falls eine SMIL-Animation läuft.

Wie der Wert zu lesen ist, hängt von filterUnits ab. Beim Standard objectBoundingBox ist er ein Bruchteil oder Prozentwert der Bounding Box des gefilterten Elements. Bei userSpaceOnUse ist er eine Länge im Benutzerkoordinatensystem. Praktisch braucht man die Eigenschaft vor allem, um den Filterbereich per Skript zu vergrößern, etwa damit Schlagschatten, Weichzeichner oder Glow-Effekte nicht am Rand abgeschnitten werden.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (veränderbares SVGLength, entspricht dem Attribut) und animVal (schreibgeschütztes SVGLength, animierter Wert). Ohne gesetztes Attribut gilt der Standardwert 120%.

Beispiele

Höhe des Filterbereichs auslesen

const svgNS = "http://www.w3.org/2000/svg";
const filter = document.createElementNS(svgNS, "filter");
filter.setAttribute("height", "150%");

const h = filter.height.baseVal;
console.log(h.valueAsString);
console.log(h.valueInSpecifiedUnits);
console.log(h.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

150% 150 true

Filterbereich vergrößern, damit ein Schlagschatten nicht abgeschnitten wird

const svgNS = "http://www.w3.org/2000/svg";
const svg = document.createElementNS(svgNS, "svg");
const filter = document.createElementNS(svgNS, "filter");
filter.id = "schatten";

const shadow = document.createElementNS(svgNS, "feDropShadow");
shadow.setAttribute("dx", "0");
shadow.setAttribute("dy", "20");
shadow.setAttribute("stdDeviation", "8");
filter.append(shadow);
svg.append(filter);
document.body.append(svg);

// Großer vertikaler Versatz: Bereich nach unten erweitern
filter.y.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, -20);
filter.height.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 200);

console.log(filter.getAttribute("height"));

200%

Absolute Höhe bei filterUnits="userSpaceOnUse"

const svgNS = "http://www.w3.org/2000/svg";
const filter = document.createElementNS(svgNS, "filter");
filter.setAttribute("filterUnits", "userSpaceOnUse");

// Wert als Zahl in Benutzereinheiten setzen
filter.height.baseVal.value = 300;
console.log(filter.getAttribute("height"));

// Die Eigenschaft selbst ist schreibgeschützt
try {
  "use strict";
  (() => { "use strict"; filter.height = 500; })();
} catch (e) {
  console.log(e instanceof TypeError);
}

300 true

// Wichtig · Fallstricke

Schreibgeschützt heißt nur die Referenz: filter.height = … wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus (also auch in ES-Modulen) einen TypeError aus. Werte ändert man über filter.height.baseVal oder setAttribute("height", …).
Standardwert: Ohne Attribut gilt 120%, zusammen mit x/y = -10%. Das ist ein Rand von 10 % oben und unten. Für große Weichzeichnungsradien oder Versätze reicht das oft nicht, sodass der Effekt sichtbar abgeschnitten wird.
Einheiten hängen von filterUnits ab: Bei objectBoundingBox bedeutet 1.5 dasselbe wie 150%. Bei userSpaceOnUse ist 1.5 eine absolute Länge und damit meist viel zu klein.
Ein negativer Wert ist ein Fehler, und der Wert 0 schaltet das Rendern des gefilterten Elements ab.
animVal weicht nur bei SMIL-Animationen (<animate>) von baseVal ab. CSS-Animationen wirken sich hier nicht aus.
Die Eigenschaft wird von allen modernen Browsern unterstützt. Elemente müssen mit createElementNS im SVG-Namensraum erzeugt werden, sonst gibt es die Eigenschaft nicht.

Siehe auch

SVGFilterElement SVGFilterElement.width SVGFilterElement.x SVGFilterElement.y SVGFilterElement.filterUnits SVGAnimatedLength SVGLength