CustomStateSet.entries() — Methode · JavaScript-Referenz

Signatur

CustomStateSet.prototype.entries()

Beschreibung

Die Methode entries() von CustomStateSet gibt einen Iterator zurück, der alle aktuell gesetzten benutzerdefinierten Zustände eines Custom Elements durchläuft. Das CustomStateSet erreichen Sie über ElementInternals.states, also über das Objekt, das this.attachInternals() in der Klasse Ihres Custom Elements zurückgibt.

Ein CustomStateSet verhält sich wie ein Set (setlike) und hat deshalb keine eigenen Schlüssel. Damit es trotzdem dieselbe Schnittstelle wie Map bietet, liefert entries() jeden Wert zweimal als Paar [value, value]. Das entspricht genau dem Verhalten von Set.prototype.entries(). Die Zustände erscheinen in der Reihenfolge, in der sie mit add() hinzugefügt wurden.

In der Praxis brauchen Sie entries() vor allem zur Fehlersuche, zum Protokollieren oder für generischen Code, der mit Maps und Sets gleichermaßen arbeiten soll. Wenn Sie nur die Zustandsnamen brauchen, sind values(), keys() oder eine direkte for...of-Schleife über das Set meist einfacher und besser lesbar.

Rückgabewert

Typ

Iterator<[string, string]>

Beschreibung

Ein neuer Set-Iterator. Jeder Schritt liefert ein Array mit zwei Elementen [state, state], wobei state der Name eines benutzerdefinierten Zustands ist.

Beispiele

Zustände eines Custom Elements mit entries() ausgeben

class ToggleButton extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
  }
  get states() {
    return this.#internals.states;
  }
}
customElements.define('toggle-button', ToggleButton);

const btn = document.createElement('toggle-button');
btn.states.add('checked');
btn.states.add('focused-by-keyboard');

for (const [key, value] of btn.states.entries()) {
  console.log(key, value);
}

checked checked focused-by-keyboard focused-by-keyboard

Iterator manuell mit next() weiterschalten

class StatusBadge extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.states.add('loading');
  }
}
customElements.define('status-badge', StatusBadge);

const badge = new StatusBadge();
const it = badge.internals.states.entries();
console.log(it.next());
console.log(it.next());

{ value: ['loading', 'loading'], done: false } { value: undefined, done: true }

Zustände als Objekt für Debug-Logs serialisieren

class DataRow extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
  }
  debugStates() {
    // Object.fromEntries akzeptiert den Iterator direkt
    return Object.fromEntries(this.internals.states.entries());
  }
}
customElements.define('data-row', DataRow);

const row = new DataRow();
row.internals.states.add('selected');
row.internals.states.add('dirty');
console.log(JSON.stringify(row.debugStates()));

{"selected":"selected","dirty":"dirty"}

// Wichtig · Fallstricke

Doppelte Werte sind Absicht: Weil ein Set keine Schlüssel kennt, sind beide Elemente des Paars identisch. Wenn Sie nur die Namen brauchen, nehmen Sie values() oder for (const s of states).
Live-Iterator: Zustände, die Sie während der Iteration mit add() hinzufügen, werden noch mit durchlaufen. Mit delete() entfernte Zustände, die noch nicht erreicht waren, werden übersprungen. Für einen stabilen Schnappschuss verwenden Sie [...states.entries()].
Kapselung: ElementInternals sollte privat bleiben, zum Beispiel in einem #internals-Feld. Legen Sie es in Produktivcode nicht öffentlich offen, sonst kann fremder Code die Zustände verändern.
Browser-Kompatibilität: Die CSS-Pseudoklasse :state(name) und CustomStateSet sind seit 2024 in allen großen Browsern verfügbar. Chrome vor Version 125 unterstützte nur die veraltete Syntax mit doppeltem Bindestrich (states.add('--checked') bzw. :--checked). Diese Syntax sollten Sie nicht mehr verwenden.
attachInternals() funktioniert nur bei autonomen Custom Elements, die mit customElements.define() registriert wurden, und darf pro Element nur einmal aufgerufen werden.

Siehe auch

CustomStateSet CustomStateSet.values() CustomStateSet.keys() CustomStateSet.forEach() CustomStateSet.add() ElementInternals.states Set.prototype.entries()