SVGGradientElement.gradientUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGGradientElement.gradientUnits

Beschreibung

Die Eigenschaft gradientUnits der Schnittstelle SVGGradientElement liefert ein SVGAnimatedEnumeration-Objekt, das den Wert des SVG-Attributs gradientUnits abbildet. Dieses Attribut legt fest, in welchem Koordinatensystem die Geometrie-Attribute des Verlaufs (x1, y1, x2, y2 bzw. cx, cy, r, fx, fy) interpretiert werden.

Der numerische Wert entspricht einer der Konstanten von SVGUnitTypes:

SVG_UNIT_TYPE_UNKNOWN (0) – ungültiger oder unbekannter Wert
SVG_UNIT_TYPE_USERSPACEONUSE (1) – userSpaceOnUse: Koordinaten beziehen sich auf das Benutzer-Koordinatensystem des Elements, das den Verlauf verwendet
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX (2) – objectBoundingBox (Standard): Koordinaten sind Bruchteile (0–1) der Bounding-Box des gefüllten Elements

Die Eigenschaft selbst ist schreibgeschützt, d. h. man kann ihr kein neues Objekt zuweisen. Über gradientUnits.baseVal lässt sich der Wert jedoch lesen und setzen; gradientUnits.animVal liefert den aktuell (ggf. durch SMIL-Animation) wirksamen Wert. Nützlich ist das z. B., wenn ein Skript Verläufe dynamisch umschaltet – etwa um einen Verlauf über mehrere Formen hinweg durchgehend (userSpaceOnUse) statt pro Form (objectBoundingBox) darzustellen.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Objekt mit baseVal (les- und schreibbar) und animVal (nur lesbar); beide enthalten eine Zahl gemäß SVGUnitTypes (0, 1 oder 2).

Beispiele

Einheitensystem eines Verlaufs auslesen

// <svg><defs><linearGradient id="verlauf" gradientUnits="userSpaceOnUse" x1="0" x2="200">...</linearGradient></defs></svg>
const gradient = document.getElementById('verlauf');

const namen = {
  [SVGUnitTypes.SVG_UNIT_TYPE_UNKNOWN]: 'unknown',
  [SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE]: 'userSpaceOnUse',
  [SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX]: 'objectBoundingBox'
};

console.log(gradient.gradientUnits.baseVal);
console.log(namen[gradient.gradientUnits.baseVal]);

1 userSpaceOnUse

Standardwert ohne gesetztes Attribut

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

// Kein Attribut gesetzt -> Standard objectBoundingBox
console.log(lg.gradientUnits.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX);
console.log(lg.hasAttribute('gradientUnits'));

true false

Verlauf per Button zwischen Einheitensystemen umschalten

const gradient = document.querySelector('#verlauf');
const button = document.querySelector('#umschalten');

button.addEventListener('click', () => {
  const units = gradient.gradientUnits;
  const istBBox = units.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX;

  if (istBBox) {
    // Koordinaten in Benutzereinheiten angeben
    gradient.setAttribute('x1', '0');
    gradient.setAttribute('x2', '400');
    units.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE;
  } else {
    gradient.setAttribute('x1', '0');
    gradient.setAttribute('x2', '1');
    units.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX;
  }

  console.log(gradient.getAttribute('gradientUnits'));
});

userSpaceOnUse (beim ersten Klick, danach abwechselnd objectBoundingBox)

// Wichtig · Fallstricke

Nur die Referenz ist schreibgeschützt: gradient.gradientUnits = 1 hat keine Wirkung (im Strict Mode TypeError). Zum Ändern gradientUnits.baseVal oder setAttribute('gradientUnits', …) verwenden.
Das Setzen von baseVal auf 0 (SVG_UNIT_TYPE_UNKNOWN) oder einen ungültigen Wert löst einen TypeError aus.
Beim Umschalten des Einheitensystems müssen die Koordinaten-Attribute (x1, x2, cx, r …) passend angepasst werden – Werte wie 1 bedeuten bei userSpaceOnUse nur 1 Benutzereinheit, sodass der Verlauf praktisch unsichtbar wird.
Bei objectBoundingBox werden Elemente ohne Ausdehnung (z. B. horizontale Linien mit Höhe 0) nicht mit dem Verlauf gefüllt – hier userSpaceOnUse verwenden.
Über href referenzierte Verläufe erben gradientUnits; die DOM-Eigenschaft spiegelt aber nur das Attribut des eigenen Elements wider.
Kompatibilität: in allen modernen Browsern unterstützt; animVal spiegelt SMIL-Animationen wider.

Siehe auch

SVGGradientElement SVGGradientElement.gradientTransform SVGGradientElement.spreadMethod SVGLinearGradientElement SVGRadialGradientElement SVGAnimatedEnumeration SVGUnitTypes