DOMTokenList.values() — Methode · JavaScript-Referenz

Signatur

DOMTokenList.prototype.values()

Beschreibung

Die Methode values() einer DOMTokenList liefert einen Iterator, der alle enthaltenen Tokens in ihrer Reihenfolge als Strings zurückgibt. Eine DOMTokenList begegnet einem vor allem über element.classList, aber auch über relList von <a>, <link> und <form>, sandbox von <iframe> oder part.

Der Iterator folgt dem Iterationsprotokoll. Sie können ihn also mit for...of durchlaufen, mit der Spread-Syntax ([...]) oder mit Array.from() in ein Array umwandeln oder von Hand next() aufrufen. values() ist identisch mit DOMTokenList.prototype[Symbol.iterator]. Deshalb ist for (const c of el.classList) gleichwertig zu for (const c of el.classList.values()).

Nützlich ist values() vor allem dann, wenn Sie einen Iterator ausdrücklich weitergeben wollen, etwa an Funktionen, die ein Iterable erwarten, oder wenn Sie Tokens schrittweise verarbeiten möchten. Wenn Sie zusätzlich den Index brauchen, verwenden Sie entries(). Für einfache Prüfungen sind contains() oder forEach() oft die direktere Wahl.

Rückgabewert

Typ

Iterator<string>

Beschreibung

Ein Iterator (genauer: ein Array Iterator), der jedes Token der Liste als string liefert. Er ist selbst iterierbar.

Beispiele

Alle CSS-Klassen eines Elements ausgeben

const box = document.createElement('div');
box.className = 'card card--active shadow';

for (const cls of box.classList.values()) {
  console.log(cls);
}

card card--active shadow

Iterator manuell mit next() abfragen

const btn = document.createElement('button');
btn.classList.add('btn', 'primary');

const it = btn.classList.values();
console.log(it.next()); // erstes Token
console.log(it.next()); // zweites Token
console.log(it.next()); // fertig

{ value: 'btn', done: false } { value: 'primary', done: false } { value: undefined, done: true }

Modifier-Klassen filtern und entfernen (BEM)

const el = document.createElement('div');
el.className = 'menu menu--open menu--dark visible';

// Zuerst eine Kopie als Array anlegen, erst danach verändern
const modifiers = [...el.classList.values()].filter((c) => c.startsWith('menu--'));
el.classList.remove(...modifiers);

console.log(modifiers);
console.log(el.className);

['menu--open', 'menu--dark'] menu visible

rel-Werte eines Links als Set auswerten

const link = document.createElement('a');
link.rel = 'noopener noreferrer external';

const rels = new Set(link.relList.values());
console.log(rels.has('noopener'), rels.size);

true 3

// Wichtig · Fallstricke

Live-Liste: Eine DOMTokenList ist „live“, sie spiegelt Änderungen am Attribut also sofort wider. Wenn Sie beim Durchlaufen per values() gleichzeitig Tokens entfernen oder hinzufügen, werden Einträge übersprungen oder doppelt verarbeitet. Legen Sie vorher mit [...list.values()] oder Array.from(list) eine Kopie an.
Kein Array: Der Rückgabewert ist ein einmal verwendbarer Iterator. Ist er einmal durchlaufen, liefert er keine Werte mehr. Rufen Sie für einen neuen Durchlauf values() erneut auf.
Doppelte Tokens im Attribut (z. B. class="a a") werden beim Einlesen entfernt. Der Iterator liefert jedes Token also nur einmal.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Der Internet Explorer kennt die Methode nicht. Dort helfen nur Array.prototype.slice.call(list) oder eine Schleife über length und item().

Siehe auch

DOMTokenList DOMTokenList.entries() DOMTokenList.keys() DOMTokenList.forEach() DOMTokenList.contains() Element.classList for...of