SVGFilterElement.filterUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGFilterElement.filterUnits

Beschreibung

Die schreibgeschützte Eigenschaft filterUnits der Schnittstelle SVGFilterElement liefert ein SVGAnimatedEnumeration-Objekt. Es gibt an, in welchem Koordinatensystem die Attribute x, y, width und height des Filterbereichs interpretiert werden.

Mögliche Zahlenwerte von baseVal bzw. animVal:

0 – SVGUnitTypes.SVG_UNIT_TYPE_UNKNOWN: unbekannter oder ungültiger Wert
1 – SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE: userSpaceOnUse, die Werte gelten im aktuellen Benutzerkoordinatensystem des Elements, das den Filter referenziert
2 – SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX: objectBoundingBox (Standard), die Werte sind Bruchteile bzw. Prozentangaben der Bounding Box des gefilterten Elements

Die Eigenschaft selbst ist schreibgeschützt. Den Wert ändern Sie trotzdem, indem Sie filterUnits.baseVal setzen oder das Attribut per setAttribute('filterUnits', …) ändern. animVal enthält den aktuellen, eventuell per SMIL animierten Wert.

Nützlich ist die Eigenschaft vor allem dann, wenn Sie Filter dynamisch erzeugen oder Filterbereiche berechnen. Ein Beispiel ist ein Weichzeichner oder Schatten, der über die Bounding Box hinausragt und deshalb nicht abgeschnitten werden soll.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Ein Objekt mit baseVal (beschreibbar, number) und animVal (nur lesbar, number). Die Werte entsprechen den SVGUnitTypes-Konstanten (0, 1 oder 2).

Beispiele

Aktuellen Wert auslesen

// <svg><filter id="blur" filterUnits="userSpaceOnUse"><feGaussianBlur stdDeviation="4"/></filter></svg>
const filter = document.getElementById('blur');

const names = {
  0: 'unknown',
  1: 'userSpaceOnUse',
  2: 'objectBoundingBox'
};

console.log(filter.filterUnits.baseVal);
console.log(names[filter.filterUnits.baseVal]);

1 userSpaceOnUse

Standardwert ohne Attribut

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

// Ohne gesetztes Attribut gilt objectBoundingBox
console.log(filter.filterUnits.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX);

true

Filter dynamisch auf userSpaceOnUse umstellen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg');

const filter = document.createElementNS(SVG_NS, 'filter');
filter.id = 'shadow';

// Wert über baseVal setzen – das Attribut wird automatisch aktualisiert
filter.filterUnits.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE;
filter.setAttribute('x', '0');
filter.setAttribute('y', '0');
filter.setAttribute('width', '400');
filter.setAttribute('height', '300');

const shadow = document.createElementNS(SVG_NS, 'feDropShadow');
shadow.setAttribute('dx', '4');
shadow.setAttribute('dy', '4');
shadow.setAttribute('stdDeviation', '3');
filter.append(shadow);

svg.querySelector('defs')?.append(filter) ?? svg.prepend(filter);
document.querySelector('rect').setAttribute('filter', 'url(#shadow)');

console.log(filter.getAttribute('filterUnits'));

userSpaceOnUse

// Wichtig · Fallstricke

Schreibgeschützt heißt nicht unveränderlich: Sie können filter.filterUnits nicht durch ein anderes Objekt ersetzen, filter.filterUnits.baseVal aber schon setzen. Eine Zuweisung von 0 (unknown) wirft einen TypeError.
Bei objectBoundingBox sind x/y/width/height relativ zur Bounding Box. Der Standardwert ist -10%/-10%/120%/120%. Große Weichzeichner oder Schatten werden deshalb oft abgeschnitten. Vergrößern Sie dann den Filterbereich oder nutzen Sie userSpaceOnUse.
Elemente ohne Ausdehnung, zum Beispiel eine rein horizontale Linie mit der Höhe 0, haben eine leere Bounding Box. Mit objectBoundingBox wird der Filter dann nicht dargestellt. Hier hilft userSpaceOnUse.
Nicht zu verwechseln mit primitiveUnits: Diese Eigenschaft steuert die Koordinaten der einzelnen Filterprimitive, filterUnits dagegen nur den Filterbereich.
Die Eigenschaft wird von allen modernen Browsern unterstützt. SVG-Elemente müssen Sie mit createElementNS und dem SVG-Namensraum erzeugen, sonst existiert die Eigenschaft nicht.

Siehe auch

SVGFilterElement SVGFilterElement.primitiveUnits SVGAnimatedEnumeration SVGUnitTypes SVGFilterElement.x SVGFilterElement.width SVGFilterElement.href