SVGFilterElement.primitiveUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGFilterElement.primitiveUnits

Beschreibung

Die schreibgeschützte Eigenschaft primitiveUnits der Schnittstelle SVGFilterElement gibt ein SVGAnimatedEnumeration-Objekt zurück. Es spiegelt das Attribut primitiveUnits des <filter>-Elements wider. Das Attribut bestimmt, in welchem Koordinatensystem Längenangaben innerhalb der Filterprimitive ausgewertet werden. Dazu gehören etwa x, y, width und height der Primitive-Unterregion, stdDeviation bei <feGaussianBlur> oder dx/dy bei <feOffset>.

Mögliche numerische Werte (Konstanten aus SVGUnitTypes):

0: SVG_UNIT_TYPE_UNKNOWN, ein unbekannter oder ungültiger Wert.
1: SVG_UNIT_TYPE_USERSPACEONUSE, entspricht userSpaceOnUse. Werte gelten im aktuellen Benutzerkoordinatensystem. Das ist der Standardwert.
2: SVG_UNIT_TYPE_OBJECTBOUNDINGBOX, entspricht objectBoundingBox. Werte sind Bruchteile oder Prozentangaben des Begrenzungsrahmens des gefilterten Elements.

Schreibgeschützt ist nur die Eigenschaft selbst. Über primitiveUnits.baseVal lässt sich der Wert ändern, und das Attribut wird dabei entsprechend aktualisiert. primitiveUnits.animVal enthält den aktuell wirksamen Wert, falls eine SMIL-Animation läuft. Die Eigenschaft hilft, wenn Filtereffekte unabhängig von der Elementgröße skalieren sollen (objectBoundingBox) oder feste Pixelwerte brauchen (userSpaceOnUse).

Verwechseln Sie sie nicht mit SVGFilterElement.filterUnits. Diese Eigenschaft gilt für den Filterbereich (x, y, width, height des <filter>-Elements selbst), nicht für die Primitive.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Ein Objekt mit baseVal (Wert des Attributs, beschreibbar) und animVal (animierter Wert, nur lesbar). Beide enthalten 0, 1 oder 2.

Beispiele

Aktuellen Wert auslesen

// <svg><filter id="blur" primitiveUnits="objectBoundingBox">
//   <feGaussianBlur stdDeviation="0.05"/></filter></svg>
const filter = document.getElementById('blur');

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

console.log(filter.primitiveUnits.baseVal);
console.log(unitNames[filter.primitiveUnits.baseVal]);

2 objectBoundingBox

Standardwert ohne gesetztes Attribut

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

// Kein primitiveUnits-Attribut gesetzt → Standard userSpaceOnUse
console.log(filter.primitiveUnits.baseVal);
console.log(filter.getAttribute('primitiveUnits'));

1 null

Einheitensystem per baseVal umschalten

const filter = document.querySelector('filter#shadow');

// Größenunabhängiger Schatten: Werte relativ zur Bounding Box
filter.primitiveUnits.baseVal = 2; // SVG_UNIT_TYPE_OBJECTBOUNDINGBOX
filter.querySelector('feOffset').setAttribute('dx', '0.03');

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

objectBoundingBox

Ungültigen Wert abfangen

const filter = document.querySelector('filter');

try {
  filter.primitiveUnits.baseVal = 0; // UNKNOWN ist nicht zuweisbar
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Die Eigenschaft ist schreibgeschützt. Ein direktes filter.primitiveUnits = … wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Ändern Sie den Wert über primitiveUnits.baseVal oder setAttribute('primitiveUnits', …).
Wird baseVal auf 0 (unbekannt) oder einen Wert außerhalb des Bereichs gesetzt, lösen aktuelle Browser einen TypeError aus.
Bei objectBoundingBox müssen Werte wie stdDeviation als Bruchteile angegeben werden (z. B. 0.05 statt 5). Sonst entstehen extrem starke Effekte. Hat das gefilterte Element keine Fläche (z. B. eine waagerechte Linie mit Breite oder Höhe 0), wird der Filter nicht angewendet.
Die Konstanten stammen aus SVGUnitTypes. Ob diese Schnittstelle als globales Objekt verfügbar ist, unterscheidet sich je nach Browser. Numerische Werte sind am robustesten.
Kompatibilität: Chrome, Firefox, Safari und Edge unterstützen die Eigenschaft seit vielen Jahren.

Siehe auch

SVGFilterElement SVGFilterElement.filterUnits SVGAnimatedEnumeration SVGUnitTypes SVGFEGaussianBlurElement CSSPrimitiveValue.primitiveType SVGFilterElement.href