SVGLengthList.insertItemBefore() — Methode · JavaScript-Referenz

Signatur

SVGLengthList.prototype.insertItemBefore(newItem, index)

Beschreibung

Die Methode insertItemBefore() des Interfaces SVGLengthList fügt ein neues Längenobjekt (SVGLength) vor dem Eintrag mit dem angegebenen Index ein. Alle Einträge ab diesem Index rücken um eine Position nach hinten. Mit dem Index 0 wird am Anfang eingefügt; ist der Index größer oder gleich numberOfItems, landet das Element am Ende der Liste.

Längenlisten tauchen in SVG vor allem bei den Attributen x, y, dx und dy von <text> und <tspan> auf. Über element.x.baseVal erhält man die veränderbare Liste; Änderungen daran werden sofort ins zugehörige Attribut zurückgeschrieben. So lassen sich einzelne Zeichen einer Textzeile gezielt positionieren, ohne das Attribut als Zeichenkette zusammenbauen und parsen zu müssen.

Ein neues SVGLength-Objekt erzeugt man über SVGSVGElement.createSVGLength() und legt dann Wert und Einheit mit newValueSpecifiedUnits() oder über die Eigenschaft value fest. Gehört das übergebene Objekt bereits zu einer anderen Liste, fügt die Methode nach SVG 2 eine Kopie ein – deshalb sollte man immer mit dem Rückgabewert weiterarbeiten.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGLength		Das einzufügende Längenobjekt, typischerweise erzeugt mit `svg.createSVGLength()`.
$index Pflicht	number		Position (ab `0`), vor der eingefügt wird. Werte ab `numberOfItems` hängen das Element ans Ende an. Wird zu einem vorzeichenlosen Ganzzahlwert (`unsigned long`) konvertiert.

Rückgabewert

Typ

SVGLength

Beschreibung

Das tatsächlich in die Liste eingefügte SVGLength-Objekt. Nach SVG 2 kann das eine Kopie von newItem sein, wenn dieses bereits zu einer Liste gehörte.

Beispiele

Länge am Anfang der x-Liste eines Textes einfügen

const NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(NS, 'svg');
const text = document.createElementNS(NS, 'text');
text.setAttribute('x', '20 30');
text.textContent = 'ABC';
svg.append(text);
document.body.append(svg);

const list = text.x.baseVal;
const len = svg.createSVGLength();
len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_NUMBER, 10);

list.insertItemBefore(len, 0);
console.log(list.numberOfItems);
console.log(text.getAttribute('x'));

3 10 20 30

Zu großer Index hängt ans Ende an

const NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(NS, 'svg');
const text = document.createElementNS(NS, 'text');
text.setAttribute('y', '5 15');
svg.append(text);

const len = svg.createSVGLength();
len.value = 25;

// Index 99 existiert nicht – das Element landet am Ende
const inserted = text.y.baseVal.insertItemBefore(len, 99);
console.log(inserted.value);
console.log(text.getAttribute('y'));

25 5 15 25

Zeichenpositionen schrittweise aufbauen

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

const list = text.x.baseVal;
list.clear();

// Fünf Positionen im Abstand von 12 px – jeweils vorne einfügen
for (let i = 4; i >= 0; i--) {
  const len = svg.createSVGLength();
  len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_NUMBER, 10 + i * 12);
  list.insertItemBefore(len, 0);
}

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

10 22 34 46 58

// Wichtig · Fallstricke

Nur auf baseVal anwenden: Die Liste animVal ist schreibgeschützt; ein Aufruf löst dort eine DOMException vom Typ NoModificationAllowedError aus.
Rückgabewert nutzen: Gehört newItem bereits zu einer anderen Liste, wurde es nach SVG 1.1 aus dieser entfernt. Nach SVG 2 (aktuelle Browser) wird dagegen eine Kopie eingefügt. Spätere Änderungen am ursprünglichen Objekt wirken sich dann nicht auf die Liste aus.
Wer ein Objekt übergibt, das kein SVGLength ist, bekommt einen TypeError.
Einheiten beeinflussen die Serialisierung: SVG_LENGTHTYPE_PX wird im Attribut als 10px geschrieben, SVG_LENGTHTYPE_NUMBER als 10.
Die Methode wird von allen modernen Browsern unterstützt. Die Eigenschaft length als Alias für numberOfItems kam erst mit SVG 2 hinzu und fehlt in sehr alten Engines.

Siehe auch

SVGLengthList SVGLengthList.appendItem() SVGLengthList.replaceItem() SVGLengthList.removeItem() SVGLengthList.getItem() SVGLength SVGSVGElement.createSVGLength()