ElementInternals.ariaColCount — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaColCount

Beschreibung

Die Eigenschaft ariaColCount der Schnittstelle ElementInternals spiegelt die ARIA-Semantik von aria-colcount wider. Damit wird angegeben, wie viele Spalten eine Tabelle (role="table"), ein Raster (role="grid") oder ein Baumraster (role="treegrid") insgesamt hat. Wichtig ist das vor allem dann, wenn nur ein Teil der Spalten im DOM steht, etwa bei virtualisierten Tabellen oder horizontalem Lazy Loading.

Anders als Element.ariaColCount setzt die Variante über ElementInternals kein Attribut im DOM. Sie legt nur die Standardsemantik eines Custom Elements fest. Setzt der Nutzer des Elements selbst ein aria-colcount-Attribut am Host-Element, hat dieses Vorrang. Die Kapselung bleibt also erhalten und das Markup sauber.

Der Wert ist ein String mit einer ganzen Zahl, zum Beispiel "12". Der Wert "-1" bedeutet, dass die Gesamtzahl der Spalten unbekannt ist. Mit null entfernen Sie die Standardsemantik wieder. Den Zugriff auf ElementInternals erhalten Sie im Konstruktor eines Custom Elements über this.attachInternals().

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: die Gesamtzahl der Spalten als String mit ganzer Zahl (z. B. `"8"`). `"-1"` steht für eine unbekannte Anzahl, `null` entfernt den Wert.

Rückgabewert

Typ

string | null

Beschreibung

Die aktuell gesetzte Standard-Spaltenanzahl als String oder null, wenn kein Wert gesetzt ist. Ein aria-colcount-Attribut am Host-Element wird hier nicht widergespiegelt.

Beispiele

Standardsemantik in einem Custom-Grid setzen

class DataGrid extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'grid';
    // Das Raster hat insgesamt 20 Spalten, auch wenn weniger gerendert werden
    this.#internals.ariaColCount = '20';
  }

  get colCount() {
    return this.#internals.ariaColCount;
  }
}

customElements.define('data-grid', DataGrid);

const grid = document.createElement('data-grid');
document.body.append(grid);
console.log(grid.colCount);
console.log(grid.hasAttribute('aria-colcount'));

20 false

Virtualisierte Tabelle: Spaltenanzahl nach dem Laden aktualisieren

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

  constructor() {
    super();
    this.#internals.role = 'table';
    // Gesamtzahl der Spalten noch unbekannt
    this.#internals.ariaColCount = '-1';
  }

  async connectedCallback() {
    // Simulierter Abruf der Spaltendefinitionen
    const columns = await Promise.resolve(['ID', 'Name', 'E-Mail', 'Ort', 'Status']);
    this.#internals.ariaColCount = String(columns.length);
    console.log('Spalten:', this.#internals.ariaColCount);
  }
}

customElements.define('virtual-table', VirtualTable);
document.body.append(document.createElement('virtual-table'));

Spalten: 5

Attribut des Nutzers hat Vorrang

class SimpleGrid extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'grid';
    this.internals.ariaColCount = '10';
  }
}
customElements.define('simple-grid', SimpleGrid);

const el = document.createElement('simple-grid');
// Überschreibt die Standardsemantik für Screenreader
el.setAttribute('aria-colcount', '12');
document.body.append(el);

console.log(el.internals.ariaColCount); // Standardwert bleibt unverändert
console.log(el.ariaColCount);           // gespiegeltes Attribut

10 12

Standardwert wieder entfernen

class ResetGrid extends HTMLElement {
  internals = this.attachInternals();
}
customElements.define('reset-grid', ResetGrid);

const g = new ResetGrid();
g.internals.ariaColCount = '4';
console.log(g.internals.ariaColCount);
g.internals.ariaColCount = null;
console.log(g.internals.ariaColCount);

4 null

// Wichtig · Fallstricke

Nur für Custom Elements: attachInternals() gibt es nur bei autonomen benutzerdefinierten Elementen. Pro Element darf es nur einmal aufgerufen werden, ein zweiter Aufruf wirft einen NotSupportedError.
Nur Gesamtzahl angeben, wenn Spalten fehlen: Stehen alle Spalten im DOM, ermittelt der Browser die Anzahl selbst. aria-colcount brauchen Sie nur, wenn Spalten ausgelassen werden. Dann sollten die Zellen zusätzlich aria-colindex tragen.
Wert ist ein String: Zahlen werden beim Setzen in Strings umgewandelt. Beim Lesen erhalten Sie immer einen String oder null, nie eine Zahl. Zum Rechnen daher Number() verwenden.
Passende Rolle nötig: Ohne die Rolle table, grid oder treegrid werten Hilfstechnologien die Eigenschaft nicht aus.
Keine Attribut-Spiegelung: Der Wert erscheint nicht als DOM-Attribut, CSS-Selektoren wie [aria-colcount] greifen also nicht.
Kompatibilität: Firefox unterstützt die ARIA-Spiegelung über ElementInternals erst ab Version 119. Für ältere Browser prüfen Sie die Unterstützung vorher, z. B. mit 'ariaColCount' in ElementInternals.prototype, und setzen ersatzweise das Attribut.

Siehe auch

ElementInternals.ariaAutoComplete ElementInternals.ariaRowCount ElementInternals.ariaColSpan ElementInternals.ariaColIndex ElementInternals.ariaCurrent