SVGLength.convertToSpecifiedUnits() — Methode · JavaScript-Referenz

Signatur

SVGLength.prototype.convertToSpecifiedUnits(unitType)

Beschreibung

Die Methode convertToSpecifiedUnits() ändert die Einheit einer SVG-Länge, ohne ihre tatsächliche Größe zu ändern. Aus 1in wird nach der Umrechnung in Pixel zum Beispiel 96px. Danach enthalten unitType, valueInSpecifiedUnits und valueAsString die neuen Werte. value (die Länge in Benutzereinheiten, also px) bleibt gleich.

Nützlich ist das, wenn Sie Attributwerte in eine einheitliche Einheit bringen wollen, etwa zum Rechnen, Speichern oder Anzeigen. Ein Beispiel: Ein Editor soll alle Koordinaten in Millimetern anzeigen, auch wenn sie im Markup in cm, in oder px stehen.

Der Einheitstyp wird als numerische Konstante übergeben, z. B. SVGLength.SVG_LENGTHTYPE_PX, SVG_LENGTHTYPE_MM oder SVG_LENGTHTYPE_PERCENTAGE. Bei relativen Einheiten (%, em, ex) braucht der Browser einen Bezugskontext: das Element muss also im Dokument hängen, damit der Viewport bzw. die Schriftgröße bekannt ist.

Ändern Sie eine animierbare Basislänge (element.width.baseVal), wird das Attribut im DOM direkt auf die neue Einheit umgeschrieben.

Parameter

Name	Typ	Default	Beschreibung
$unitType Pflicht	number		Einheitstyp-Konstante von `SVGLength`: `SVG_LENGTHTYPE_NUMBER` (1), `PERCENTAGE` (2), `EMS` (3), `EXS` (4), `PX` (5), `CM` (6), `MM` (7), `IN` (8), `PT` (9), `PC` (10). `SVG_LENGTHTYPE_UNKNOWN` (0) ist ungültig.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Das SVGLength-Objekt wird direkt verändert.

Beispiele

Zoll in Pixel umrechnen

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

const length = svg.createSVGLength();
length.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_IN, 1);
console.log(length.valueAsString); // "1in"

length.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX);
console.log(length.valueAsString);        // "96px"
console.log(length.valueInSpecifiedUnits); // 96
console.log(length.unitType === SVGLength.SVG_LENGTHTYPE_PX); // true

1in 96px 96 true

Attribut eines Rechtecks auf Millimeter umstellen

// &lt;svg&gt;&lt;rect id="box" width="2cm" height="1in"/&gt;&lt;/svg&gt;
const rect = document.getElementById('box');

const w = rect.width.baseVal;
const h = rect.height.baseVal;

w.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_MM);
h.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_MM);

console.log(rect.getAttribute('width'));  // "20mm"
console.log(h.valueInSpecifiedUnits.toFixed(1)); // "25.4"

20mm 25.4

Hilfsfunktion: beliebige Länge in Pixel auslesen

const toPx = (svgLength) => {
  // Kopie, damit das Original unverändert bleibt
  const svg = document.querySelector('svg');
  const copy = svg.createSVGLength();
  copy.valueAsString = svgLength.valueAsString;
  copy.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX);
  return copy.valueInSpecifiedUnits;
};

const circle = document.querySelector('circle'); // r="12pt"
console.log(toPx(circle.r.baseVal)); // 16

16

// Wichtig · Fallstricke

Eingriff ins DOM: Auf baseVal angewendet, schreibt die Methode das Attribut sofort um (z. B. aus width="2cm" wird width="20mm"). Wenn Sie nur einen Wert auslesen wollen, arbeiten Sie mit einer Kopie aus createSVGLength().
Nur lesbar: animVal und schreibgeschützte Längen werfen bei Aufruf einen NoModificationAllowedError.
Ungültiger Typ: SVG_LENGTHTYPE_UNKNOWN oder ein Wert außerhalb 1–10 löst einen NotSupportedError aus (in älteren Browsern auch TypeError).
Relative Einheiten: %, em und ex hängen vom Kontext ab (Viewport, Schriftgröße). Bei Elementen außerhalb des Dokuments oder bei freistehenden Längen kann das Ergebnis falsch sein oder die Umrechnung fehlschlagen.
Rundung: Bei der Umrechnung entstehen Fließkommawerte (z. B. 25.4 mm). Runden Sie vor der Anzeige.
Die Methode wird von allen modernen Browsern unterstützt. Die Konstanten sind in SVG 2 weiterhin gültig.

Siehe auch

SVGLength SVGLength.newValueSpecifiedUnits() SVGLength.valueInSpecifiedUnits SVGLength.unitType SVGSVGElement.createSVGLength() SVGAnimatedLength