SVGLengthList.appendItem() — Methode · JavaScript-Referenz

Signatur

SVGLengthList.prototype.appendItem(newItem)

Beschreibung

appendItem() fügt ein SVGLength-Objekt am Ende einer SVGLengthList ein. Solche Listen gibt es bei SVG-Attributen, die mehrere Längenwerte enthalten können, vor allem bei x, y, dx und dy von <text> und <tspan>. Über element.x.baseVal kommst du an die veränderbare Liste.

Wenn du die Liste änderst, schreibt der Browser das zugehörige Attribut automatisch neu. Nach appendItem() steht der neue Wert also sofort im DOM (z. B. x="10 30 50"). Das ist praktisch, wenn du einzelnen Zeichen eigene Positionen geben willst, ohne dafür Attribut-Strings selbst zusammenzubauen.

Das neue SVGLength erstellst du mit SVGSVGElement.createSVGLength(). Den Wert setzt du danach über value, valueAsString oder newValueSpecifiedUnits(). Nach SVG 2 wird eine Kopie eingefügt, falls das Objekt schon zu einer anderen Liste gehört. Verlass dich deshalb auf den Rückgabewert und nicht auf das Objekt, das du übergeben hast.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGLength		Das anzuhängende Längenobjekt, meist erzeugt mit `svg.createSVGLength()`.

Rückgabewert

Typ

SVGLength

Beschreibung

Das tatsächlich eingefügte SVGLength. Gehörte newItem schon zu einer Liste, kann das eine Kopie sein.

Beispiele

Weitere x-Position an ein Textelement anhängen

const svg = document.querySelector('svg');
const text = document.querySelector('text'); // <text x="10">ABC</text>

const len = svg.createSVGLength();
len.value = 30; // Einheit: Benutzereinheiten (px)

text.x.baseVal.appendItem(len);
console.log(text.getAttribute('x'));
console.log(text.x.baseVal.numberOfItems);

10 30 2

Jedes Zeichen einzeln positionieren (Wellen-Effekt)

const svg = document.querySelector('svg');
const text = document.querySelector('#wave'); // <text id="wave">Hallo Welt</text>
const xs = text.x.baseVal;
const ys = text.y.baseVal;
xs.clear();
ys.clear();

[...text.textContent].forEach((_, i) => {
  const x = svg.createSVGLength();
  x.value = 20 + i * 14;
  xs.appendItem(x);

  const y = svg.createSVGLength();
  y.value = 50 + Math.sin(i / 1.5) * 10;
  ys.appendItem(y);
});

console.log(xs.numberOfItems);

10

Wert mit Einheit anhängen

const svg = document.querySelector('svg');
const tspan = document.querySelector('tspan');

const len = svg.createSVGLength();
len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_EMS, 1.5);

const inserted = tspan.dx.baseVal.appendItem(len);
console.log(inserted.valueAsString);

1.5em

// Wichtig · Fallstricke

Nur baseVal ist veränderbar: Rufst du appendItem() auf animVal auf, wirft der Browser eine DOMException vom Typ NoModificationAllowedError.
Kopie oder dasselbe Objekt: In SVG 1.1 wurde ein Element, das schon in einer anderen Liste steckte, dort entfernt. Nach SVG 2 wird stattdessen eine Kopie eingefügt. Die Browser setzen das nicht ganz einheitlich um. Arbeite deshalb immer mit dem Rückgabewert weiter.
Relative Einheiten wie % oder em kann der Browser nur umrechnen, wenn das Element im gerenderten Dokument hängt. Sonst kann value ungenau sein oder eine Ausnahme auslösen.
Jeder Aufruf schreibt das Attribut neu. Bei sehr vielen Einträgen ist es oft schneller, das Attribut einmal direkt per setAttribute('x', ...) zu setzen.
Die Methode wird von allen aktuellen Browsern unterstützt. Das veraltete SVGLength.convertToSpecifiedUnits() und die Konstanten funktionieren weiterhin.

Siehe auch

SVGLengthList SVGLengthList.insertItemBefore() SVGLengthList.replaceItem() SVGLengthList.removeItem() SVGLengthList.clear() SVGLength SVGSVGElement.createSVGLength()