SVGSVGElement.createSVGLength() — Methode · JavaScript-Referenz

Signatur

SVGSVGElement.prototype.createSVGLength()

Beschreibung

Die Methode createSVGLength() des SVGSVGElement erzeugt ein neues SVGLength-Objekt, das außerhalb jedes Dokumentbaums existiert. Es gehört also zu keinem Attribut und keinem Element. Das neue Objekt hat den Wert 0 und den Einheitentyp SVGLength.SVG_LENGTHTYPE_NUMBER (reine Benutzereinheiten ohne Einheit).

Gebraucht wird die Methode vor allem mit Längenlisten (SVGLengthList), wie sie die Attribute x, y, dx und dy von <text> und <tspan> liefern. Mit appendItem(), insertItemBefore() oder replaceItem() braucht man ein fertiges SVGLength, und das bekommt man über createSVGLength(). Außerdem eignet sich ein solches Objekt gut, um Einheiten umzurechnen, etwa von Millimetern in Pixel. Dafür nutzt man newValueSpecifiedUnits() und convertToSpecifiedUnits().

Man ruft die Methode an einem beliebigen <svg>-Element auf. Das Element muss dafür nicht im Dokument eingehängt sein. Das zurückgegebene Objekt wirkt sich erst auf die Darstellung aus, wenn man es in eine Längenliste eines Elements einfügt.

Rückgabewert

Typ

SVGLength

Beschreibung

Ein neues, keinem Element zugeordnetes SVGLength-Objekt mit value === 0 und unitType === SVGLength.SVG_LENGTHTYPE_NUMBER (Wert 1).

Beispiele

Länge erzeugen und mit Einheit belegen

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

console.log(len.value, len.unitType); // Standardwerte

// 2,5 Zentimeter setzen
len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_CM, 2.5);
console.log(len.valueAsString);
console.log(len.value.toFixed(2)); // in Benutzereinheiten (px)

0 1 2.5cm 94.49

x-Positionen eines <text> Zeichen für Zeichen setzen

const svg = document.querySelector('svg');
const text = svg.querySelector('text');
const xList = text.x.baseVal; // SVGLengthList

xList.clear();
[10, 30, 55, 90].forEach((pos) => {
  const len = svg.createSVGLength();
  len.value = pos; // Benutzereinheiten
  xList.appendItem(len);
});

console.log(text.getAttribute('x'));

10 30 55 90

Einheiten umrechnen: Millimeter in Pixel

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

const mmToPx = (mm) => {
  const len = svg.createSVGLength();
  len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_MM, mm);
  len.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX);
  return len.valueInSpecifiedUnits;
};

console.log(mmToPx(10).toFixed(3));
console.log(mmToPx(25.4)); // genau 1 Zoll

37.795 96

// Wichtig · Fallstricke

Keine Parameter: Die Methode nimmt keinen Startwert entgegen. Den Wert setzt man danach über value, valueAsString oder newValueSpecifiedUnits().
Relative Einheiten: Ein Objekt, das keinem Element zugeordnet ist, hat keinen Bezugsrahmen. Prozentwerte, em und ex lassen sich deshalb nicht zuverlässig in Benutzereinheiten umrechnen. Je nach Browser liefert value dann falsche Werte oder convertToSpecifiedUnits() wirft eine NotSupportedError-Ausnahme. Absolute Einheiten wie mm, cm, in, pt, pc und px sind dagegen unproblematisch.
Einfügen in Listen: In SVG 2 wird ein Objekt direkt eingefügt, solange es noch in keiner Liste steckt. Ist es schon Teil einer Liste, fügt man eine Kopie ein. Spätere Änderungen am ursprünglichen Objekt wirken sich dann womöglich nicht mehr auf das Element aus. Am sichersten ist es, für jeden Eintrag ein eigenes Objekt zu erzeugen.
Nur auf <svg>: Die Methode gibt es nur auf SVGSVGElement, nicht auf anderen SVG-Elementen. Bei Bedarf kommt man über element.ownerSVGElement an das nächste <svg>-Element.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Die Formatierung von valueAsString und die Rundung bei Umrechnungen können sich zwischen den Browsern leicht unterscheiden.

Siehe auch

SVGLength SVGLengthList SVGSVGElement SVGSVGElement.createSVGNumber() SVGSVGElement.createSVGPoint() SVGSVGElement.createSVGAngle()