SVGUnitTypes — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGUnitTypes

Beschreibung

SVGUnitTypes ist ein reines Konstanten-Interface. Es hat weder Methoden noch veränderbare Eigenschaften und lässt sich nicht instanziieren. Es legt fest, welche Zahlenwerte die DOM-Eigenschaften zu Einheiten-Attributen wie gradientUnits, patternUnits, patternContentUnits, clipPathUnits, maskUnits, maskContentUnits, filterUnits und primitiveUnits annehmen.

Die Konstanten sind:

SVG_UNIT_TYPE_UNKNOWN (0): Der Typ ist keiner der vordefinierten Typen. Diesen Wert kann man nicht bewusst setzen.
SVG_UNIT_TYPE_USERSPACEONUSE (1): Entspricht userSpaceOnUse. Koordinaten beziehen sich auf das Benutzerkoordinatensystem des Elements, das den Verlauf, das Muster o. Ä. referenziert.
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX (2): Entspricht objectBoundingBox. Koordinaten sind Bruchteile (0–1) bzw. Prozentwerte der Bounding Box des referenzierenden Elements.

In der Praxis braucht man die Konstanten, wenn man die entsprechenden SVGAnimatedEnumeration-Eigenschaften ausliest oder ändert, etwa SVGLinearGradientElement.gradientUnits.baseVal oder SVGClipPathElement.clipPathUnits.baseVal. Mit den benannten Konstanten statt „magischer“ Zahlen bleibt der Code lesbar. Das ist besonders nützlich in Editoren, Diagramm-Bibliotheken oder Werkzeugen, die SVG-Grafiken verarbeiten oder umrechnen.

Rückgabewert

Typ

number

Beschreibung

Jede Konstante ist eine unveränderliche Ganzzahl (unsigned short): 0, 1 oder 2.

Beispiele

Konstanten auslesen

// SVGUnitTypes ist nicht instanziierbar, die Konstanten liegen direkt am Interface-Objekt
console.log(SVGUnitTypes.SVG_UNIT_TYPE_UNKNOWN);
console.log(SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE);
console.log(SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX);

try {
  new SVGUnitTypes();
} catch (err) {
  console.log(err instanceof TypeError);
}

0 1 2 true

Einheitensystem eines Verlaufs prüfen

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

// Ohne Attribut gilt der Standardwert objectBoundingBox
const units = gradient.gradientUnits.baseVal;

if (units === SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX) {
  console.log('Koordinaten relativ zur Bounding Box (0–1)');
} else if (units === SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE) {
  console.log('Koordinaten im Benutzerkoordinatensystem');
}

Koordinaten relativ zur Bounding Box (0–1)

Einheitensystem per DOM umschalten

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

// Standard bei clipPath: userSpaceOnUse
console.log(clip.clipPathUnits.baseVal);

// Auf objectBoundingBox umstellen – das Attribut wird automatisch aktualisiert
clip.clipPathUnits.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX;
console.log(clip.getAttribute('clipPathUnits'));

1 objectBoundingBox

Hilfsfunktion: Zahlenwert in Attributwert umwandeln

const unitName = (value) => ({
  [SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE]: 'userSpaceOnUse',
  [SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX]: 'objectBoundingBox'
})[value] ?? 'unknown';

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

console.log('patternUnits:', unitName(pattern.patternUnits.baseVal));
console.log('patternContentUnits:', unitName(pattern.patternContentUnits.baseVal));

patternUnits: objectBoundingBox patternContentUnits: userSpaceOnUse

// Wichtig · Fallstricke

Keine Instanzen: new SVGUnitTypes() löst einen TypeError aus. Man verwendet nur die statischen Konstanten, z. B. SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX.
Standardwerte beachten: Die Standardwerte unterscheiden sich je nach Attribut. gradientUnits, patternUnits, maskUnits und filterUnits sind standardmäßig objectBoundingBox (2). patternContentUnits, clipPathUnits, maskContentUnits und primitiveUnits sind standardmäßig userSpaceOnUse (1).
UNKNOWN nicht setzen: Wird baseVal auf 0 oder einen ungültigen Wert gesetzt, lösen moderne Browser einen TypeError aus bzw. ignorieren die Zuweisung.
baseVal vs. animVal: animVal ist schreibgeschützt und gibt den Wert wieder, der gerade durch eine SMIL-Animation gilt. Ändern kann man nur baseVal.
objectBoundingBox und Linien: Hat ein Element keine Fläche, etwa eine waagerechte Linie mit Bounding-Box-Höhe 0, wird ein Verlauf oder Clip mit objectBoundingBox nicht dargestellt. In diesem Fall userSpaceOnUse verwenden.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). In Node.js gibt es das Interface ohne DOM-Umgebung nicht. jsdom bildet es nur teilweise ab.

Siehe auch

DocumentType SVGAngle SVGNumber SVGPoint SVGPointList