CustomStateSet.clear() — Methode · JavaScript-Referenz

Signatur

CustomStateSet.prototype.clear()

Beschreibung

Die Methode clear() des Interfaces CustomStateSet entfernt alle Einträge aus dem Set. Ein CustomStateSet erhältst du über ElementInternals.states. Dazu rufst du in einem autonomen Custom Element this.attachInternals() auf. Jeder Eintrag im Set ist ein eigener Zustand des Elements, den CSS mit der Pseudoklasse :state(name) abfragen kann.

Nach dem Aufruf von clear() passt keine :state()-Pseudoklasse mehr auf das Element. Die Stile aktualisiert der Browser sofort. Die Methode eignet sich, wenn ein Element in seinen Ausgangszustand zurückkehren soll, etwa beim Zurücksetzen eines Formulars (formResetCallback) oder bevor du mehrere sich gegenseitig ausschließende Zustände neu setzt.

CustomStateSet verhält sich wie ein Set mit Zeichenketten. clear() funktioniert daher genauso wie Set.prototype.clear(): Die Methode nimmt keine Argumente entgegen und gibt undefined zurück.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das Set wird direkt verändert.

Beispiele

Alle Zustände eines Custom Elements zurücksetzen

class StatusBadge extends HTMLElement {
  #internals = this.attachInternals();

  setStates(...names) {
    this.#internals.states.clear();
    names.forEach((n) => this.#internals.states.add(n));
  }

  reset() {
    this.#internals.states.clear();
  }

  get stateList() {
    return [...this.#internals.states];
  }
}
customElements.define('status-badge', StatusBadge);

const badge = document.createElement('status-badge');
badge.setStates('loading', 'highlighted');
console.log(badge.stateList);
badge.reset();
console.log(badge.stateList);

["loading", "highlighted"] []

Formular-Element beim Reset in den Ausgangszustand bringen

class RatingInput extends HTMLElement {
  static formAssociated = true;
  #internals = this.attachInternals();

  connectedCallback() {
    this.addEventListener('click', () => {
      this.#internals.states.add('touched');
      this.#internals.states.add('rated');
      this.#internals.setFormValue('5');
    });
  }

  // Wird beim Zurücksetzen des umgebenden Formulars aufgerufen
  formResetCallback() {
    this.#internals.states.clear();
    this.#internals.setFormValue('');
  }
}
customElements.define('rating-input', RatingInput);

/* CSS:
rating-input:state(rated) { color: gold; }
rating-input:state(touched) { outline: 1px solid gray; }
*/

Sich ausschließende Zustände umschalten

class TrafficLight extends HTMLElement {
  #internals = this.attachInternals();

  set color(value) {
    // Vorherige Farbe entfernen, danach genau eine setzen
    this.#internals.states.clear();
    this.#internals.states.add(value);
  }

  get size() {
    return this.#internals.states.size;
  }
}
customElements.define('traffic-light', TrafficLight);

const light = document.createElement('traffic-light');
light.color = 'red';
light.color = 'green';
console.log(light.size);

1

// Wichtig · Fallstricke

Nur in autonomen Custom Elements: attachInternals() funktioniert nur bei Klassen, die direkt von HTMLElement erben und registriert sind. Bei erweiterten Built-ins (is="...") wirft der Aufruf einen NotSupportedError.
Alte Syntax: Ältere Chromium-Versionen (vor 125) verlangten Zustandsnamen mit ---Präfix und die CSS-Syntax :--name. Die heutige Standardsyntax ist :state(name). Für ältere Browser musst du beide Varianten unterstützen.
Kapselung: Gib das ElementInternals-Objekt nicht nach außen. Wenn du es in einem privaten Feld (#internals) speicherst, kann fremder Code die Zustände nicht mit clear() löschen.
clear() löst kein Ereignis aus. Wenn andere Teile deiner Anwendung auf Zustandsänderungen reagieren sollen, musst du selbst ein CustomEvent auslösen.
Browserunterstützung: Die Methode ist seit 2024 in allen großen Browsern verfügbar. Prüfe sie bei Bedarf mit 'CustomStateSet' in window.

Siehe auch

Set.prototype.clear() CustomStateSet.delete() CustomStateSet.has() CustomStateSet.keys() CustomStateSet.add()