SVGLengthList — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGLengthList

Beschreibung

SVGLengthList steht für eine geordnete Liste von Längenangaben (SVGLength). Man bekommt sie nicht per Konstruktor, sondern über die Eigenschaften baseVal und animVal eines SVGAnimatedLengthList-Objekts. Solche Objekte liefern zum Beispiel SVGTextPositioningElement.x, .y, .dx und .dy der Elemente <text> und <tspan>.

Die Liste hat eine eigene, an SVG angelehnte API:

Eigenschaften: length und numberOfItems (beide geben die Anzahl der Einträge an).
Methoden: clear(), initialize(newItem), getItem(index), insertItemBefore(newItem, index), replaceItem(newItem, index), removeItem(index) und appendItem(newItem).
Indexzugriff: In modernen Browsern geht auch list[index].

Die Liste ist live: Änderungen an baseVal schreiben sich sofort in das zugehörige Attribut zurück, und Änderungen am Attribut sieht man sofort in der Liste. Deshalb eignet sich die Schnittstelle gut, um Glyphen einzeln zu positionieren, ohne Attribut-Strings selbst zusammenzubauen oder zu zerlegen. Neue Einträge erzeugt man mit SVGSVGElement.prototype.createSVGLength().

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGLength		Wird von `initialize()`, `appendItem()`, `insertItemBefore()` und `replaceItem()` erwartet. Diesen Eintrag erzeugt man mit `svg.createSVGLength()`.
$index Pflicht	number		Wird von `getItem()`, `insertItemBefore()`, `replaceItem()` und `removeItem()` erwartet. Die Zählung beginnt bei 0. Ist der Index bei `insertItemBefore()` größer als die Liste, wird der Eintrag am Ende angehängt.

Rückgabewert

Typ

SVGLength | void

Beschreibung

getItem(), appendItem(), insertItemBefore(), replaceItem(), removeItem() und initialize() geben jeweils den betroffenen SVGLength-Eintrag zurück. clear() gibt undefined zurück.

Beispiele

x-Positionen eines Textes auslesen

// HTML: <svg id="grafik"><text id="t" x="10 25 40" y="50">ABC</text></svg>
const text = document.querySelector('#t');
const liste = text.x.baseVal; // SVGLengthList

console.log(liste.numberOfItems);
for (let i = 0; i < liste.numberOfItems; i++) {
  console.log(`Zeichen ${i}: ${liste.getItem(i).value}px`);
}

3 Zeichen 0: 10px Zeichen 1: 25px Zeichen 2: 40px

Neue Position anhängen und Eintrag ersetzen

const svg = document.querySelector('#grafik');
const text = document.querySelector('#t');
const liste = text.x.baseVal;

// Neue Länge in Pixeln erzeugen
const neu = svg.createSVGLength();
neu.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX, 55);
liste.appendItem(neu);

// Den ersten Eintrag durch eine Angabe in em ersetzen
const start = svg.createSVGLength();
start.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_EMS, 1);
liste.replaceItem(start, 0);

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

1em 25 40 55

Buchstaben gleichmäßig verteilen

const verteilen = (svg, text, startX, abstand) => {
  const liste = text.x.baseVal;
  liste.clear();
  [...text.textContent].forEach((_, i) => {
    const len = svg.createSVGLength();
    len.value = startX + i * abstand; // Einheit: Benutzereinheiten
    liste.appendItem(len);
  });
  return liste.length;
};

const anzahl = verteilen(
  document.querySelector('#grafik'),
  document.querySelector('#t'),
  10,
  20
);
console.log(anzahl, document.querySelector('#t').getAttribute('x'));

3 10 30 50

animVal ist schreibgeschützt

const text = document.querySelector('#t');
try {
  text.x.animVal.clear();
} catch (err) {
  console.log(err.name);
}

NoModificationAllowedError

// Wichtig · Fallstricke

Schreibschutz: Die Liste aus animVal ist nur lesbar. Jede Änderung wirft einen NoModificationAllowedError. Ändern Sie immer baseVal.
Ungültiger Index: getItem(), replaceItem() und removeItem() werfen einen IndexSizeError, wenn der Index nicht in der Liste liegt.
Einträge wiederverwenden: Ob ein SVGLength in die Liste kopiert oder aus einer anderen Liste herausgelöst wird, war in SVG 1.1 und SVG 2 unterschiedlich geregelt. Erzeugen Sie für jeden Eintrag am besten ein eigenes Objekt mit createSVGLength(), damit sich das Verhalten in allen Browsern gleicht.
Relative Einheiten: Bei % oder em hängt value vom Kontext ab, zum Beispiel vom Viewport oder von der Schriftgröße. Das Element muss dafür im Dokument hängen.
Kompatibilität: Die Methoden gibt es in allen aktuellen Browsern. Den Indexzugriff list[i] und die Eigenschaft length hat erst SVG 2 eingeführt. Für sehr alte Browser ist getItem() und numberOfItems der sichere Weg.
Keine Array-Methoden: Die Liste ist kein Array. Methoden wie map und forEach fehlen. Bei Bedarf wandeln Sie sie mit Array.from({ length: l.numberOfItems }, (_, i) => l.getItem(i)) um.

Siehe auch

SVGLength SVGAnimatedLengthList SVGTextPositioningElement SVGSVGElement.createSVGLength() SVGNumberList SVGPointList