SVGLength.valueAsString — Eigenschaft · JavaScript-Referenz

Signatur

SVGLength.valueAsString

Beschreibung

Die Eigenschaft valueAsString des SVGLength-Interfaces gibt die Länge so zurück, wie sie in SVG-Attributen geschrieben wird: als Zahl mit der Einheit, die in unitType steht. Beispiele sind "20", "1.5em", "3cm" oder "50%".

Die Eigenschaft lässt sich auch schreiben. Wenn du eine Zeichenkette zuweist, parst der Browser sie. Danach passt er unitType, valueInSpecifiedUnits und value an. Hängt das SVGLength-Objekt an einem Attribut, zum Beispiel über circle.r.baseVal, ändert sich auch das Attribut im DOM. Mit einer einzigen Zuweisung änderst du so Wert und Einheit gleichzeitig.

Nützlich ist valueAsString vor allem, wenn du Längen serialisieren, protokollieren oder zwischen Elementen übertragen willst, ohne die Einheit zu verlieren. Für Berechnungen in Benutzereinheiten (Pixeln) nimmst du besser value. Um eine Einheit zu wechseln und den Wert dabei umzurechnen, gibt es convertToSpecifiedUnits().

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	string		Beim Schreiben: eine gültige SVG-Längenangabe, z. B. `"12px"`, `"2em"`, `"25%"` oder eine Zahl ohne Einheit wie `"40"`.

Rückgabewert

Typ

string

Beschreibung

Die Länge als Zeichenkette mit Einheit, passend zu unitType. Bei Längen ohne Einheit (SVG_LENGTHTYPE_NUMBER) nur die Zahl.

Beispiele

Radius eines Kreises als Zeichenkette auslesen

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

const r = circle.r.baseVal;
console.log(r.valueAsString);
console.log(r.unitType === SVGLength.SVG_LENGTHTYPE_MM);

10mm true

Wert und Einheit auf einmal setzen

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

width.valueAsString = '50%';

console.log(width.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);
console.log(width.valueInSpecifiedUnits);
console.log(rect.getAttribute('width'));

true 50 50%

Freistehende Länge mit createSVGLength() und Fehlerbehandlung

const svg = document.querySelector('svg');
const len = svg.createSVGLength();

const setLength = (length, input) => {
  try {
    length.valueAsString = input;
    return true;
  } catch (err) {
    console.warn(`Ungültige Länge "${input}": ${err.name}`);
    return false;
  }
};

setLength(len, '2.5cm');
console.log(len.valueAsString);
setLength(len, 'zehn Pixel');

2.5cm Ungültige Länge "zehn Pixel": SyntaxError

Nach Einheitenumrechnung serialisieren

const svg = document.querySelector('svg');
const len = svg.createSVGLength();
len.valueAsString = '1in';

len.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX);
console.log(len.valueAsString);

96px

// Wichtig · Fallstricke

Ungültige Zeichenketten: Wenn der Browser die Zuweisung nicht parsen kann, wirft er eine DOMException vom Typ SyntaxError. Nutzereingaben solltest du deshalb in try…catch setzen.
Nur lesbare Längen: Längen aus animVal (z. B. circle.r.animVal) kann man nicht ändern. Eine Zuweisung wirft NoModificationAllowedError. Schreib immer auf baseVal.
Zahlenformat: Wie die Zahl ausgegeben wird (Nachkommastellen, Rundung nach convertToSpecifiedUnits()), kann sich je nach Browser leicht unterscheiden. Vergleiche daher lieber valueInSpecifiedUnits und unitType statt die Zeichenketten direkt.
Relative Einheiten wie % oder em brauchen für die Umrechnung in value einen Kontext, also ein Element, das gerendert wird. valueAsString selbst behält die ursprüngliche Einheit.
Kompatibilität: Alle modernen Browser unterstützen die Eigenschaft seit Langem (SVG 1.1).

Siehe auch

SVGLength SVGLength.value SVGLength.valueInSpecifiedUnits SVGLength.unitType SVGLength.prototype.convertToSpecifiedUnits() SVGLength.prototype.newValueSpecifiedUnits() SVGSVGElement.prototype.createSVGLength() SVGAnimatedLength