SVGLength.newValueSpecifiedUnits() — Methode · JavaScript-Referenz

Signatur

SVGLength.prototype.newValueSpecifiedUnits(unitType, valueInSpecifiedUnits)

Beschreibung

newValueSpecifiedUnits() weist einem SVGLength-Objekt in einem Schritt einen Zahlenwert und eine Einheit zu. Die Einheit ist eine der Konstanten SVGLength.SVG_LENGTHTYPE_*, zum Beispiel SVG_LENGTHTYPE_PX, SVG_LENGTHTYPE_CM oder SVG_LENGTHTYPE_PERCENTAGE. Danach sind alle Eigenschaften des Objekts auf dem gleichen Stand: unitType, valueInSpecifiedUnits, valueAsString und der Wert in Benutzereinheiten (value).

Die Methode eignet sich, wenn du Längenangaben in SVG-Elementen wie r, width, x oder stroke-width gezielt mit Einheit setzen willst und dafür keinen String zusammenbauen möchtest. Wenn du Attribute über element.r.baseVal änderst, wird das zugehörige Attribut im DOM sofort aktualisiert.

Sie ist das Gegenstück zu convertToSpecifiedUnits(). Diese Methode behält die physische Länge bei und wechselt nur die Einheit. newValueSpecifiedUnits() setzt dagegen Wert und Einheit komplett neu.

Parameter

Name	Typ	Default	Beschreibung
$unitType Pflicht	number		Einheit als `SVGLength`-Konstante: `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 nicht erlaubt.
$valueInSpecifiedUnits Pflicht	number		Der neue Zahlenwert in der angegebenen Einheit, z. B. `2` für `2cm`.

Rückgabewert

Typ

undefined

Beschreibung

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

Beispiele

Kreisradius in Zentimetern setzen

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

const r = circle.r.baseVal;
r.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_CM, 2);

console.log(r.unitType);              // 6 (CM)
console.log(r.valueInSpecifiedUnits); // 2
console.log(r.valueAsString);         // "2cm"
console.log(r.value.toFixed(2));      // Wert in px
console.log(circle.getAttribute('r'));

6 2 "2cm" "75.59" "2cm"

Freistehende SVGLength erzeugen und setzen

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

len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_IN, 1);
console.log(len.valueAsString, len.value); // 1in = 96px

len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PT, 12);
console.log(len.valueAsString, len.value); // 12pt = 16px

1in 96 12pt 16

Breite eines Rechtecks prozentual setzen

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

// Fortschrittsbalken: 42 % der Viewport-Breite
const setProgress = (percent) => {
  rect.width.baseVal.newValueSpecifiedUnits(
    SVGLength.SVG_LENGTHTYPE_PERCENTAGE,
    percent
  );
};

setProgress(42);
console.log(rect.getAttribute('width'));

42%

// Wichtig · Fallstricke

Wenn unitType SVG_LENGTHTYPE_UNKNOWN (0) oder ein unbekannter Wert ist, wird ein NotSupportedError (DOMException) ausgelöst.
animVal ist nur lesbar. Ein Aufruf auf element.r.animVal löst NoModificationAllowedError aus. Ändere daher immer baseVal.
Nicht endliche Werte wie NaN oder Infinity führen zu einem TypeError.
Relative Einheiten (%, em, ex) brauchen einen Kontext, damit value in Pixel umgerechnet werden kann. Bei freistehenden Objekten, die mit createSVGLength() erzeugt wurden, kann das Lesen von value deshalb fehlschlagen oder ungenau sein.
Neuere Einheiten wie rem oder vw haben keine SVG_LENGTHTYPE_*-Konstante. Für sie verwendest du valueAsString oder setAttribute().
Die Methode wird von allen aktuellen Browsern unterstützt.

Siehe auch

SVGLength SVGAnimatedLength SVGLength.convertToSpecifiedUnits() SVGAngle.newValueSpecifiedUnits() SVGAngle.convertToSpecifiedUnits()