ElementInternals.ariaSetSize — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaSetSize

Beschreibung

Über ElementInternals.ariaSetSize legt ein autonomes Custom Element die ARIA-Semantik aria-setsize fest, ohne ein sichtbares Attribut auf den Host zu schreiben. Der Wert ist ein String mit einer ganzen Zahl, der angibt, wie viele Elemente der aktuelle Satz insgesamt umfasst, z. B. die Einträge einer Liste, eines Listbox-Menüs oder einer Baumebene.

Das ist vor allem bei virtualisierten oder nachgeladenen Listen wichtig. Dort liegt nur ein Teil der Einträge im DOM, und Screenreader können die Gesamtzahl nicht selbst zählen. Zusammen mit ariaPosInSet kann die Hilfstechnik dann z. B. „Element 3 von 250“ ansagen. Ist die Gesamtzahl unbekannt, setzt man "-1".

Die Werte in ElementInternals sind Standardwerte. Setzt ein Nutzer der Komponente selbst das Attribut aria-setsize auf den Host, hat dieses Attribut Vorrang. Die Eigenschaft ist nur sinnvoll, wenn das Element eine passende Rolle hat, z. B. listitem, option, treeitem, row, tab, menuitem oder radio.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: ein String mit einer ganzen Zahl (z. B. `"12"`) oder `"-1"` für eine unbekannte Gesamtzahl. `null` entfernt den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell gesetzte Standardwert für aria-setsize als String, oder null, wenn keiner gesetzt ist.

Beispiele

Listeneintrag mit Standard-Semantik

class MyListItem extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'listitem';
  }

  // Position und Gesamtzahl von außen setzen
  setPosition(pos, total) {
    this.internals.ariaPosInSet = String(pos);
    this.internals.ariaSetSize = String(total);
  }
}
customElements.define('my-list-item', MyListItem);

const item = document.createElement('my-list-item');
item.textContent = 'Drittes Element';
document.body.append(item);
item.setPosition(3, 10);
console.log(item.internals.ariaSetSize);
console.log(item.hasAttribute('aria-setsize'));

10 false

Virtualisierte Listbox mit großer Datenmenge

class VirtualOption extends HTMLElement {
  #internals = this.attachInternals();
  constructor() {
    super();
    this.#internals.role = 'option';
  }
  update(index, total) {
    this.#internals.ariaPosInSet = String(index + 1);
    this.#internals.ariaSetSize = String(total);
    this.textContent = `Eintrag ${index + 1}`;
  }
}
customElements.define('virtual-option', VirtualOption);

const listbox = document.createElement('div');
listbox.setAttribute('role', 'listbox');
document.body.append(listbox);

// Nur 5 von 1000 Einträgen werden gerendert
const total = 1000;
for (let i = 0; i < 5; i++) {
  const opt = document.createElement('virtual-option');
  opt.update(i, total);
  listbox.append(opt);
}
console.log(listbox.children.length);

5

Unbekannte Gesamtzahl bei endlosem Nachladen

class FeedEntry extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'article';
  }
}
customElements.define('feed-entry', FeedEntry);

const entry = document.createElement('feed-entry');
// Gesamtzahl steht noch nicht fest
entry.internals.ariaSetSize = '-1';
console.log(entry.internals.ariaSetSize);

// Standardwert wieder entfernen
entry.internals.ariaSetSize = null;
console.log(entry.internals.ariaSetSize);

-1 null

// Wichtig · Fallstricke

Nur für autonome Custom Elements: attachInternals() wirft bei eingebauten Elementen und bei angepassten eingebauten Elementen (is="…") einen NotSupportedError. Pro Element darf die Methode nur einmal aufgerufen werden.
Der Wert ist ein String: Zahlen werden beim Setzen zwar in einen String umgewandelt, geprüft wird der Inhalt aber nicht. Ungültige Werte wie "abc" ignoriert die Hilfstechnik einfach.
Das Host-Attribut hat Vorrang: Ein explizit gesetztes aria-setsize-Attribut überschreibt den Standardwert aus ElementInternals.
Keine Spiegelung im DOM: Der Wert erscheint nicht als Attribut und lässt sich deshalb nicht mit CSS-Attributselektoren abfragen.
Werte konsistent halten: ariaSetSize sollte innerhalb eines Satzes für alle Elemente gleich sein und zu ariaPosInSet passen. Wenn Einträge hinzukommen oder wegfallen, müssen die Werte aktualisiert werden.
Browserunterstützung: Chromium ab 83, Safari ab 16.4, Firefox erst ab 119. In älteren Browsern vorher mit 'ariaSetSize' in ElementInternals.prototype prüfen und notfalls das Attribut setzen.

Siehe auch

ElementInternals ElementInternals.ariaPosInSet ElementInternals.role HTMLElement.attachInternals() Element.ariaSetSize ElementInternals.ariaLevel ElementInternals.ariaHasPopup