SVGStringList.insertItemBefore() — Methode · JavaScript-Referenz

Signatur

SVGStringList.prototype.insertItemBefore(newItem, index)

Beschreibung

Mit insertItemBefore() fügst du eine neue Zeichenkette vor dem Element an Position index in eine SVGStringList ein. Alle folgenden Einträge rücken eine Position nach hinten. Mit dem Index 0 landet der neue Eintrag am Anfang der Liste.

Ist index größer als oder gleich numberOfItems, hängt der Browser den Eintrag einfach ans Ende an. Die Methode verhält sich dann wie appendItem(). Einen Fehler wegen eines zu großen Index gibt es hier also nicht, anders als bei getItem() oder replaceItem().

SVGStringList begegnet dir vor allem bei den bedingten Verarbeitungsattributen aus dem Interface SVGTests: element.systemLanguage und element.requiredExtensions. Die Liste ist live. Wenn du sie änderst, wird das zugehörige Attribut im DOM sofort mitgeändert. Bei systemLanguage werden die Einträge durch Kommas getrennt, bei requiredExtensions durch Leerzeichen. Das ist praktisch, wenn du Sprachvarianten in einem <switch>-Element per Skript steuern willst.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	string		Die Zeichenkette, die eingefügt werden soll, z. B. ein Sprachcode wie `"de"` oder eine Erweiterungs-URL. Werte, die keine Zeichenketten sind, werden nach den üblichen WebIDL-Regeln in einen String umgewandelt.
$index Pflicht	number		Die Position (ab 0), vor der eingefügt wird. `0` fügt am Anfang ein. Ist der Wert `>= numberOfItems`, wird am Ende angehängt. Der Wert wird als `unsigned long` interpretiert.

Rückgabewert

Typ

string

Beschreibung

Das eingefügte Element, also den Wert von newItem als Zeichenkette.

Beispiele

Bevorzugte Sprache an den Anfang von systemLanguage setzen

const svgNS = 'http://www.w3.org/2000/svg';
const text = document.createElementNS(svgNS, 'text');
text.setAttribute('systemLanguage', 'en, fr');

const langs = text.systemLanguage; // SVGStringList
const inserted = langs.insertItemBefore('de', 0);

console.log(inserted);
console.log(langs.numberOfItems);
console.log(text.getAttribute('systemLanguage'));

de 3 de, en, fr

Zu großer Index hängt am Ende an

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

// Index 99 liegt außerhalb der Liste, also wird am Ende angehängt
g.systemLanguage.insertItemBefore('es', 99);

const all = Array.from(
  { length: g.systemLanguage.numberOfItems },
  (_, i) => g.systemLanguage.getItem(i)
);
console.log(all);

["en", "es"]

Sprachvariante in einem <switch> nachträglich aktivieren

// <svg><switch id="greet">
//   <text systemLanguage="fr" y="20">Bonjour</text>
//   <text y="20">Hello</text>
// </switch></svg>
const frText = document.querySelector('#greet text[systemLanguage]');
const userLang = navigator.language.slice(0, 2); // z. B. "de"

const langs = frText.systemLanguage;
const exists = Array.from({ length: langs.numberOfItems }, (_, i) => langs.getItem(i))
  .includes(userLang);

if (!exists) {
  // Die Sprache des Nutzers wird vorne eingefügt, damit dieser Text greift
  langs.insertItemBefore(userLang, 0);
}
console.log(frText.getAttribute('systemLanguage'));

de, fr

// Wichtig · Fallstricke

Schreibgeschützte Listen: Wenn die Liste schreibgeschützt ist, wirft die Methode eine DOMException vom Typ NoModificationAllowedError.
Kein Fehler bei großem Index: Ein Index außerhalb der Liste führt nicht zu IndexSizeError, sondern zum Anhängen am Ende. Wenn du erwartest, dass ein falscher Index einen Fehler auslöst, prüfe ihn vorher selbst gegen numberOfItems.
Negative Indizes: Weil der Index als unsigned long umgewandelt wird, wird z. B. -1 zu einer sehr großen Zahl. Der Eintrag landet dann am Ende, nicht an der vorletzten Stelle.
Duplikate: Die Methode prüft nicht, ob ein Wert schon in der Liste steht. Gleiche Einträge können also mehrfach vorkommen.
Live-Liste: Jede Änderung schreibt das zugehörige Attribut sofort neu. Bei vielen Änderungen kann es schneller sein, das Attribut einmal mit setAttribute() zu setzen.
Kompatibilität: Wird von Chrome, Edge, Firefox und Safari unterstützt. SVGStringList hat keinen Iterator und keine Array-Methoden. Um die Einträge durchzugehen, brauchst du getItem() und numberOfItems bzw. length.

Siehe auch

SVGStringList SVGStringList.appendItem() SVGStringList.replaceItem() SVGStringList.removeItem() SVGStringList.getItem() SVGStringList.numberOfItems