</> programmierung.net
Start · Sprachen · JavaScript · Referenz · DOMTokenList

DOMTokenList

Schnittstelle

Die Schnittstelle <code>DOMTokenList</code> ist eine Menge von durch Leerzeichen getrennten Tokens, z. B. die von <code>Element.classList</code> oder <code>relList</code>.

seit JavaScript Baseline: alle Browser (replace() und supports() s Kategorie: webapi

Signatur

interface DOMTokenList

Beschreibung

DOMTokenList ist eine live aktualisierte, geordnete Menge von Tokens. Sie gehört immer zu einem Attribut, dessen Wert aus durch Leerzeichen getrennten Wörtern besteht. Die bekanntesten Vertreter sind Element.classList (Attribut class), HTMLLinkElement.relList, HTMLAnchorElement.relList, HTMLIFrameElement.sandbox und HTMLOutputElement.htmlFor. Ändert man die Liste, ändert sich das Attribut sofort – und umgekehrt.

Die wichtigsten Mitglieder:

  • length – Anzahl der Tokens; value – das Attribut als Zeichenkette (lesbar und schreibbar).
  • item(index) bzw. list[index] – Token an einer Position oder null.
  • contains(token) – prüft, ob ein Token vorhanden ist.
  • add(...tokens) / remove(...tokens) – fügt Tokens hinzu oder entfernt sie; Duplikate werden ignoriert.
  • toggle(token, force?) – schaltet ein Token um und gibt true zurück, wenn es danach vorhanden ist.
  • replace(alt, neu) – ersetzt ein Token und gibt true zurück, wenn es ersetzt wurde.
  • supports(token) – prüft bei Listen mit festen erlaubten Werten (z. B. relList, sandbox), ob das Token unterstützt wird.
  • entries(), keys(), values(), forEach() sowie for...of, da die Liste iterierbar ist.

Nimm DOMTokenList immer dann, wenn du einzelne Klassen oder Link-Beziehungen ändern willst, ohne selbst Zeichenketten zu zerlegen. Mit className += " aktiv" bekommst du leicht doppelte Leerzeichen oder doppelte Einträge; classList.add("aktiv") passiert das nicht.

Rückgabewert

Typ
DOMTokenList
Beschreibung
Man erzeugt keine Instanz selbst. Du bekommst sie über Eigenschaften wie element.classList oder link.relList.

Beispiele

Instanz über classList holen und Klassen bearbeiten

const box = document.createElement('div');
box.className = 'karte schatten';

const klassen = box.classList; // DOMTokenList
klassen.add('aktiv', 'gross');
klassen.remove('schatten');

console.log(klassen.length);
console.log(klassen.value);
console.log(klassen.contains('aktiv'));
console.log(box.getAttribute('class'));
3 karte aktiv gross true karte aktiv gross

toggle() mit force für einen Menü-Schalter

const menue = document.createElement('nav');
const istOffen = (offen) => menue.classList.toggle('offen', offen);

console.log(menue.classList.toggle('offen')); // ein
console.log(menue.classList.toggle('offen')); // aus
console.log(istOffen(true));  // erzwingt vorhanden
console.log(istOffen(true));  // bleibt vorhanden
console.log(menue.className);
true false true true offen

replace() und Iteration für Theme-Wechsel

const root = document.createElement('html');
root.classList.add('theme-hell', 'schrift-normal');

const ersetzt = root.classList.replace('theme-hell', 'theme-dunkel');
console.log(ersetzt);

for (const token of root.classList) {
  console.log(token);
}
console.log([...root.classList].filter((k) => k.startsWith('theme-')));
true theme-dunkel schrift-normal ["theme-dunkel"]

supports() mit relList zur Feature-Erkennung

const link = document.createElement('link');

if (link.relList.supports('preload')) {
  link.rel = 'preload';
  link.as = 'style';
  link.href = '/css/haupt.css';
  document.head.append(link);
  console.log('Preload wird unterstützt');
} else {
  console.log('Kein Preload – normales Stylesheet laden');
}
Preload wird unterstützt

// Wichtig · Fallstricke

  • Live-Liste: Die Liste ändert sich sofort mit dem Attribut. Wenn du beim Durchlaufen Tokens entfernst, werden Einträge übersprungen. Lege vorher mit [...el.classList] eine Kopie an.
  • Leerzeichen im Token: add('a b') wirft einen InvalidCharacterError und add('') einen SyntaxError. Übergib mehrere Tokens als einzelne Argumente: add('a', 'b').
  • Groß- und Kleinschreibung: Tokens werden mit Unterscheidung von Groß- und Kleinschreibung verglichen. 'Aktiv' und 'aktiv' sind also verschiedene Tokens.
  • supports(): Das funktioniert nur bei Listen mit festen erlaubten Werten. Bei classList wirft der Aufruf einen TypeError.
  • Leeres Attribut: Wenn du alle Tokens entfernst, bleibt ein leeres class=""-Attribut stehen. Zum vollständigen Entfernen nimmst du removeAttribute('class').
  • Kompatibilität: Grundfunktionen gibt es in allen aktuellen Browsern. Mehrere Argumente bei add()/remove(), das zweite Argument von toggle(), replace() und supports() fehlen im Internet Explorer. Bei SVG-Elementen im alten IE gibt es auch kein classList.

Siehe auch

Element.classList Element.className DOMTokenList.prototype.toggle() DOMTokenList.prototype.replace() DOMTokenList.prototype.supports() HTMLLinkElement.relList Element.setAttribute()
← Vorheriger Eintrag DOMStringMap