SVGAnimatedEnumeration — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimatedEnumeration

Beschreibung

SVGAnimatedEnumeration ist das Wrapper-Objekt, das SVG-DOM-Eigenschaften zurückgeben, wenn das zugehörige Attribut nur einen von wenigen festgelegten Schlüsselwörtern annehmen darf, zum Beispiel gradientUnits="userSpaceOnUse", spreadMethod="reflect" oder lengthAdjust="spacingAndGlyphs". Statt der Zeichenkette liefert das DOM eine Ganzzahl (unsigned short), die einer Konstanten des jeweiligen Interfaces entspricht, etwa SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE (Wert 1).

Das Interface hat genau zwei Eigenschaften:

baseVal – der Wert, wie er im Attribut steht (ohne laufende Animation). Du kannst ihn lesen und schreiben; beim Schreiben wird das Attribut im Markup mit dem passenden Schlüsselwort aktualisiert.
animVal – nur lesbar; der aktuelle Wert, wenn gerade eine SMIL-Animation (<animate>, <set>) läuft. Ohne Animation ist er gleich baseVal.

Typische Stellen, an denen du auf SVGAnimatedEnumeration triffst: SVGGradientElement.gradientUnits und .spreadMethod, SVGClipPathElement.clipPathUnits, SVGMaskElement.maskUnits, SVGFilterElement.filterUnits, SVGMarkerElement.markerUnits und .orientType, SVGTextContentElement.lengthAdjust, SVGFEBlendElement.mode oder SVGFETurbulenceElement.type.

Nutze das Interface, wenn du solche Attribute typsicher auswerten oder ändern willst, ohne Zeichenketten zu vergleichen. Wenn dir lesbare Schlüsselwörter wichtiger sind, sind getAttribute()/setAttribute() oft einfacher.

Beispiele

Einheitensystem eines Farbverlaufs auslesen

const SVG_NS = 'http://www.w3.org/2000/svg';
const grad = document.createElementNS(SVG_NS, 'linearGradient');
grad.setAttribute('gradientUnits', 'userSpaceOnUse');

const units = grad.gradientUnits; // SVGAnimatedEnumeration
console.log(units instanceof SVGAnimatedEnumeration);
console.log(units.baseVal);
console.log(units.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE);

true 1 true

baseVal setzen – Attribut wird automatisch aktualisiert

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

// Standardwert ohne Attribut: pad
console.log(grad.spreadMethod.baseVal === SVGGradientElement.SVG_SPREADMETHOD_PAD);

grad.spreadMethod.baseVal = SVGGradientElement.SVG_SPREADMETHOD_REFLECT;
console.log(grad.getAttribute('spreadMethod'));

true reflect

Zahl in lesbares Schlüsselwort übersetzen

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

const describeUnits = (el, prop) => {
  const { baseVal, animVal } = el[prop];
  return `${prop}: basis=${unitNames[baseVal]}, animiert=${unitNames[animVal]}`;
};

const clip = document.createElementNS('http://www.w3.org/2000/svg', 'clipPath');
clip.setAttribute('clipPathUnits', 'objectBoundingBox');
console.log(describeUnits(clip, 'clipPathUnits'));

clipPathUnits: basis=objectBoundingBox, animiert=objectBoundingBox

Ungültigen Wert abfangen

const text = document.createElementNS('http://www.w3.org/2000/svg', 'text');
try {
  text.lengthAdjust.baseVal = 0; // 0 = UNKNOWN, darf nicht gesetzt werden
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

animVal ist schreibgeschützt: Eine Zuweisung wird still ignoriert oder wirft im Strict Mode einen Fehler. Ändere immer baseVal.
Ungültige Werte: Laut SVG 2 wirft das Setzen von 0 (die *_UNKNOWN-Konstante) oder einer Zahl außerhalb der Aufzählung einen TypeError. Ältere Browser warfen stattdessen eine DOMException oder ignorierten den Wert. Fange Zuweisungen deshalb bei Bedarf mit try…catch ab.
Unbekannte Schlüsselwörter im Markup (z. B. Tippfehler wie gradientUnits="userspace") ergeben meist den Standardwert des Attributs, nicht 0. Prüfe im Zweifel zusätzlich mit getAttribute().
animVal und Animationen: Nur SMIL-Animationen wirken auf animVal. CSS-Animationen und die Web Animations API ändern diese Attribute nicht, weil es keine CSS-Eigenschaften sind. Je nach Browser kann sich die Aktualisierung von animVal während einer SMIL-Animation unterschiedlich verhalten.
Neuere Aufzählungen: In SVG 2 sind einige Attribute (z. B. Blend-Modi von <feBlend>) um Schlüsselwörter erweitert worden, für die es keine numerische Konstante gibt. baseVal liefert dann 0. Nutze in diesem Fall getAttribute().
Das Interface ist seit SVG 1.1 in allen modernen Browsern verfügbar. Das Objekt ist „live“: Es spiegelt spätere Änderungen am Attribut sofort wider.

Siehe auch

SVGAnimatedBoolean SVGAnimatedInteger SVGAnimatedLength SVGAnimatedString SVGUnitTypes SVGGradientElement SVGClipPathElement SVGMarkerElement