</> programmierung.net
Start · Sprachen · JavaScript · Referenz · SVGLength

SVGLength

Schnittstelle

Die Schnittstelle <code>SVGLength</code> steht für den SVG-Datentyp &lt;length&gt;, also einen Zahlenwert mit Einheit wie <code>px</code>, <code>%</code>, <code>em</code> oder <code>cm</code>.

seit JavaScript SVG 1.1 / Baseline: alle Browser Kategorie: webapi

Signatur

interface SVGLength

Beschreibung

SVGLength ist die Objektform des SVG-Datentyps <length>. Attribute wie width, height, x, y, r oder cx werden im DOM nicht als Zeichenkette, sondern als SVGAnimatedLength angeboten. Dessen Eigenschaften baseVal (der im Attribut gesetzte Wert) und animVal (der aktuelle, eventuell animierte Wert) sind jeweils ein SVGLength-Objekt.

Ein SVGLength speichert eine Zahl zusammen mit ihrer Einheit. Es bietet diese Eigenschaften:

  • unitType (nur lesbar): Konstante für die Einheit, z. B. SVGLength.SVG_LENGTHTYPE_PX (5) oder SVG_LENGTHTYPE_PERCENTAGE (2).
  • value: Wert in Benutzereinheiten (entspricht meist px). Beim Setzen wird die Einheit in eine Benutzereinheit umgewandelt.
  • valueInSpecifiedUnits: Zahl in der ursprünglich angegebenen Einheit.
  • valueAsString: Wert als Zeichenkette mit Einheit, z. B. "2.5cm". Lässt sich auch setzen.

Dazu kommen zwei Methoden: newValueSpecifiedUnits(unitType, valueInSpecifiedUnits) setzt Wert und Einheit auf einmal, und convertToSpecifiedUnits(unitType) rechnet den Wert in eine andere Einheit um, ohne dass sich die gezeichnete Länge ändert.

Einen Konstruktor gibt es nicht. Freistehende Instanzen erzeugt man mit SVGSVGElement.prototype.createSVGLength(). Meist greift man aber über element.width.baseVal usw. auf vorhandene Objekte zu. Die Schnittstelle ist dann nützlich, wenn man Einheiten sicher lesen, umrechnen oder ändern will, ohne Attribut-Zeichenketten selbst zu zerlegen.

Parameter

Name Typ Default Beschreibung
$unitType Pflicht number Wird von newValueSpecifiedUnits() und convertToSpecifiedUnits() verwendet. Eine der Konstanten SVG_LENGTHTYPE_NUMBER (1), PERCENTAGE (2), EMS (3), EXS (4), PX (5), CM (6), MM (7), IN (8), PT (9) oder PC (10).
$valueInSpecifiedUnits Pflicht number Wird nur von newValueSpecifiedUnits() verwendet: der neue Zahlenwert in der angegebenen Einheit.

Rückgabewert

Typ
SVGLength
Beschreibung
Ein Objekt mit unitType, value, valueInSpecifiedUnits und valueAsString. Beide Methoden geben undefined zurück.

Beispiele

Länge eines Attributs auslesen

const svg = document.querySelector('svg');
const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
rect.setAttribute('width', '2cm');
rect.setAttribute('height', '50');
svg.append(rect);

const width = rect.width.baseVal; // SVGLength
console.log(width.valueAsString);
console.log(width.unitType === SVGLength.SVG_LENGTHTYPE_CM);
console.log(width.valueInSpecifiedUnits);
console.log(Math.round(width.value)); // in Benutzereinheiten (px)
2cm true 2 76

Einheit umrechnen mit convertToSpecifiedUnits()

const circle = document.querySelector('circle'); // <circle r="96">
const r = circle.r.baseVal;

// 96 Benutzereinheiten in Zoll umrechnen (96px = 1in)
r.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_IN);
console.log(r.valueAsString);
console.log(circle.getAttribute('r')); // Attribut wird mitgeändert
1in 1in

Wert und Einheit gleichzeitig setzen

const rect = document.querySelector('rect');
const w = rect.width.baseVal;

// Breite auf 50 % des Viewports setzen
w.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 50);
console.log(rect.getAttribute('width'));

// Oder bequem über eine Zeichenkette
w.valueAsString = '12mm';
console.log(w.unitType === SVGLength.SVG_LENGTHTYPE_MM);
50% true

Freistehendes SVGLength über createSVGLength()

const svg = document.querySelector('svg');
const len = svg.createSVGLength();
len.valueAsString = '3pt';
console.log(len.value); // 3pt = 4px

// Eine Länge zu einer SVGLengthList hinzufügen (z. B. x-Werte eines <text>)
const text = document.querySelector('text');
text.x.baseVal.appendItem(len);
4

// Wichtig · Fallstricke

  • Kein Konstruktor: new SVGLength() löst einen TypeError aus. Neue Instanzen erzeugt man mit svgElement.createSVGLength().
  • animVal ist nur lesbar: Wer value oder valueAsString auf element.width.animVal setzt, bekommt eine NoModificationAllowedError. Änderungen gehören immer an baseVal.
  • Prozent und em/ex: Um sie in Benutzereinheiten umzurechnen, braucht der Browser einen Viewport bzw. eine Schriftgröße. Bei Elementen, die nicht im Dokument hängen, kann value deshalb falsch sein oder einen Fehler auslösen.
  • Moderne CSS-Einheiten wie rem, vw oder vh kennt SVGLength nicht. unitType ist dann SVG_LENGTHTYPE_UNKNOWN (0). Ungültige Einheiten-Konstanten führen zu einer NotSupportedError, ungültige Zeichenketten bei valueAsString zu einer SyntaxError.
  • Änderungen über SVGLength schreiben das zugehörige Attribut sofort zurück. Das kann MutationObserver auslösen.
  • Die Schnittstelle wird von allen aktuellen Browsern unterstützt. In SVG 2 wurden die Einheiten-Konstanten zusätzlich auf dem Interface-Objekt verfügbar gemacht (SVGLength.SVG_LENGTHTYPE_PX).

Siehe auch

SVGAngle SVGLengthList SVGRect Event SVGElement
← Vorheriger Eintrag SVGImageElement.y