SVGFilterElement.width — Eigenschaft · JavaScript-Referenz

Signatur

SVGFilterElement.width

Beschreibung

Die Eigenschaft SVGFilterElement.width spiegelt das Attribut width eines <filter>-Elements wider. Dieses Attribut legt die Breite des Filterbereichs fest. Das ist das Rechteck, in dem der Browser die Filterprimitiven (z. B. <feGaussianBlur>) berechnet und zeichnet. Alles außerhalb dieses Bereichs wird abgeschnitten. Zusammen mit x, y und height beschreibt width also den Bereich, in dem der Filter wirkt.

Der Rückgabewert ist ein SVGAnimatedLength-Objekt. Es hat zwei Bestandteile: baseVal ist der im Markup oder per Skript gesetzte Grundwert, animVal ist der aktuelle Wert während einer SMIL-Animation. Die Eigenschaft selbst ist schreibgeschützt. Den Wert ändern Sie über baseVal, zum Beispiel mit baseVal.value, baseVal.valueAsString oder baseVal.newValueSpecifiedUnits().

Wie ein Wert gedeutet wird, hängt vom Attribut filterUnits ab. Bei objectBoundingBox (Standard) ist die Breite ein Anteil oder Prozentwert des Begrenzungsrahmens des gefilterten Elements. Bei userSpaceOnUse ist sie eine absolute Länge im Benutzerkoordinatensystem. Ohne gesetztes Attribut gilt laut Spezifikation 120%. So bleibt links und rechts je 10 % Platz, etwa für Weichzeichner oder Schatten.

Typische Einsätze: Den Filterbereich per Skript vergrößern, wenn ein starker Weichzeichner oder <feDropShadow> am Rand abgeschnitten wird. Oder die aktuelle Breite auslesen, um Filter dynamisch an Inhalte anzupassen.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (veränderbares SVGLength, Grundwert des Attributs width) und animVal (schreibgeschütztes SVGLength, aktuell animierter Wert).

Beispiele

Breite des Filterbereichs auslesen

const SVG_NS = 'http://www.w3.org/2000/svg';
const filter = document.createElementNS(SVG_NS, 'filter');
filter.setAttribute('width', '150%');

const { baseVal } = filter.width;
console.log(baseVal.valueAsString);
console.log(baseVal.valueInSpecifiedUnits);
console.log(baseVal.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

150% 150 true

Abgeschnittenen Weichzeichner reparieren

// <svg><defs><filter id="blur"><feGaussianBlur stdDeviation="20"/></filter></defs>
//   <rect width="100" height="100" filter="url(#blur)"/></svg>
const filter = document.querySelector('#blur');

// Filterbereich horizontal auf 200 % vergrößern und zentrieren
filter.width.baseVal.valueAsString = '200%';
filter.x.baseVal.valueAsString = '-50%';

console.log(filter.getAttribute('width'));
console.log(filter.getAttribute('x'));

200% -50%

Absolute Breite im Benutzerkoordinatensystem setzen

const filter = document.querySelector('#blur');
filter.setAttribute('filterUnits', 'userSpaceOnUse');

// Breite auf 300 Pixel setzen
filter.width.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX, 300);

console.log(filter.getAttribute('width'));
console.log(filter.width.baseVal.value);

300px 300

Direkte Zuweisung schlägt fehl

'use strict';
const filter = document.createElementNS('http://www.w3.org/2000/svg', 'filter');

try {
  filter.width = '200%'; // Eigenschaft hat nur einen Getter
} catch (err) {
  console.log(err instanceof TypeError);
}

// Richtig: über baseVal
filter.width.baseVal.valueAsString = '200%';
console.log(filter.getAttribute('width'));

true 200%

// Wichtig · Fallstricke

Schreibgeschützt: filter.width = … wird ohne Strict-Modus stillschweigend ignoriert. Im Strict-Modus wirft die Zuweisung einen TypeError. Ändern Sie den Wert immer über filter.width.baseVal oder setAttribute('width', …).
Einheiten hängen von filterUnits ab: Bei objectBoundingBox bedeutet 1.5 das 1,5-Fache der Breite des Begrenzungsrahmens, nicht 1,5 Pixel. Wenn Sie filterUnits wechseln, ohne width anzupassen, ist das Ergebnis oft unerwartet.
Filterbereich zu klein: Der Standardwert 120% reicht für einen starken Weichzeichner oder große Schatten oft nicht aus. Dann erscheinen harte Kanten. Die Lösung ist, width und x zu vergrößern.
Eine Breite von 0 schaltet den Filter ab: Das Element wird dann gar nicht gezeichnet. Negative Werte sind ein Fehler.
animVal weicht nur während einer SMIL-Animation (<animate>) von baseVal ab. CSS-Animationen wirken sich darauf nicht aus.
Browser-Kompatibilität: Alle aktuellen Browser unterstützen die Eigenschaft seit Langem. Mit baseVal.value ausgelesene Prozentwerte können sich zwischen Browsern leicht unterscheiden. Verlässlicher sind valueInSpecifiedUnits und valueAsString.

Siehe auch

SVGFilterElement SVGFilterElement.height SVGFilterElement.x SVGFilterElement.y SVGFilterElement.filterUnits SVGAnimatedLength SVGLength