SVGStringList — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGStringList

Beschreibung

SVGStringList ist eine SVG-DOM-Schnittstelle für Attribute, deren Wert aus einer Liste von Zeichenketten besteht. Man erzeugt sie nie selbst. Stattdessen bekommt man sie über Eigenschaften der Schnittstelle SVGTests, die alle grafischen und Container-Elemente implementieren, etwa element.systemLanguage und element.requiredExtensions.

Die Liste ist live: Wenn Sie sie mit Methoden wie appendItem() oder removeItem() ändern, ändert sich sofort auch das zugehörige Attribut im Markup. Umgekehrt zeigt die Liste Änderungen am Attribut, etwa über setAttribute(), sofort an.

Die Schnittstelle bietet folgende Mitglieder:

length / numberOfItems – Anzahl der Einträge (nur lesbar)
clear() – entfernt alle Einträge
initialize(newItem) – leert die Liste und fügt dann newItem als einzigen Eintrag ein
getItem(index) – gibt den Eintrag an Position index zurück
insertItemBefore(newItem, index) – fügt vor der angegebenen Position ein
replaceItem(newItem, index) – ersetzt den Eintrag an der Position
removeItem(index) – entfernt den Eintrag und gibt ihn zurück
appendItem(newItem) – hängt am Ende an

Typische Einsatzfälle sind mehrsprachige SVG-Grafiken mit <switch> und systemLanguage sowie Werkzeuge, die solche Bedingungsattribute auslesen oder umschreiben.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	string		Die Zeichenkette, die mit `initialize()`, `appendItem()`, `insertItemBefore()` oder `replaceItem()` eingefügt wird.
$index Pflicht	number		Position in der Liste, beginnend bei 0. Wird bei `getItem()`, `replaceItem()` und `removeItem()` verwendet. Bei `insertItemBefore()` fügt ein zu großer Index am Ende ein.

Rückgabewert

Typ

string | void

Beschreibung

getItem(), initialize(), appendItem(), insertItemBefore(), replaceItem() und removeItem() geben jeweils die betroffene Zeichenkette zurück. clear() gibt nichts zurück (undefined).

Beispiele

systemLanguage eines Elements auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const text = document.createElementNS(svgNS, 'text');
text.setAttribute('systemLanguage', 'de, de-AT, de-CH');

// SVGStringList über die SVGTests-Eigenschaft holen
const langs = text.systemLanguage;
console.log(langs.numberOfItems);

for (let i = 0; i < langs.numberOfItems; i++) {
  console.log(langs.getItem(i));
}

3 de de-AT de-CH

Liste ändern – das Attribut wird automatisch angepasst

const svgNS = 'http://www.w3.org/2000/svg';
const g = document.createElementNS(svgNS, 'g');
const list = g.systemLanguage;

list.initialize('en');           // Liste: [en]
list.appendItem('fr');           // [en, fr]
list.insertItemBefore('de', 0);  // [de, en, fr]
list.replaceItem('es', 2);       // [de, en, es]
const removed = list.removeItem(1); // [de, es]

console.log(removed);
console.log(g.getAttribute('systemLanguage'));

en de, es

Mehrsprachiges SVG: Sprachvarianten per Skript ergänzen

// HTML: <svg><switch id="greeting">
//   <text systemLanguage="de" y="20">Hallo</text>
//   <text y="20">Hello</text>
// </switch></svg>
const germanText = document.querySelector('#greeting text[systemLanguage]');

// Österreich und Schweiz sollen die deutsche Variante auch sehen
const langs = germanText.systemLanguage;
['de-AT', 'de-CH'].forEach((code) => langs.appendItem(code));

console.log(germanText.getAttribute('systemLanguage'));

de, de-AT, de-CH

// Wichtig · Fallstricke

Index außerhalb des Bereichs: Bei einem ungültigen Index werfen getItem(), replaceItem() und removeItem() eine DOMException vom Typ IndexSizeError. Prüfen Sie deshalb vorher numberOfItems.
Kein echtes Array: SVGStringList hat kein map(), forEach() usw. SVG 2 legt zwar Zugriff per Index (list[0]) fest, sicherer und überall unterstützt ist aber getItem() mit einer klassischen for-Schleife.
Nur lesbare Listen: Ist die Liste schreibgeschützt, lösen Methoden, die sie ändern, einen NoModificationAllowedError aus.
Veraltete Attribute: requiredFeatures und die zugehörige Liste wurden in SVG 2 entfernt, und moderne Browser unterstützen sie nicht mehr. Verwenden Sie nur noch systemLanguage und requiredExtensions.
Browser-Kompatibilität: Die Methoden werden in allen aktuellen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Bei der Schreibweise des Attributs im Markup kann es kleine Unterschiede geben, z. B. bei Leerzeichen nach Kommas. Vergleichen Sie Einträge deshalb über die Liste und nicht über den Attributtext.

Siehe auch

SVGNumberList SVGLengthList SVGTransformList SVGPointList SVGGraphicsElement SVGSwitchElement