ElementInternals.ariaColIndexText — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaColIndexText

Beschreibung

Die Eigenschaft ariaColIndexText des Interfaces ElementInternals entspricht dem ARIA-Attribut aria-colindextext. Damit kann ein autonomes Custom Element Hilfstechnologien wie Screenreadern eine verständliche Spaltenbezeichnung liefern, zum Beispiel „Spalte B“ oder „Mittwoch“ statt der reinen Zahl aus aria-colindex.

Der Unterschied zu Element.ariaColIndexText: Über ElementInternals legt die Komponente ihre Standard-Semantik intern fest. Am Element erscheint dabei kein sichtbares Attribut im DOM. Setzt jemand, der die Komponente verwendet, selbst ein aria-colindextext-Attribut am Element, hat dieses Vorrang. So bleibt das Markup sauber und lässt sich trotzdem überschreiben.

Sinnvoll ist das bei eigenen Tabellen-, Grid- oder Treegrid-Komponenten, in denen Zellen (role="gridcell", "cell", "columnheader") als Custom Elements umgesetzt sind. Die Eigenschaft soll ariaColIndex ergänzen, nicht ersetzen. Ein numerischer Spaltenindex sollte also immer mit angegeben werden.

Rückgabewert

Typ

string | null

Beschreibung

Die gesetzte Textalternative als String oder null, wenn keine gesetzt ist. Wird null zugewiesen, entfernt das die Standard-Semantik.

Beispiele

Grid-Zelle als Custom Element mit lesbarem Spaltennamen

class DataCell extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'gridcell';
  }

  static get observedAttributes() {
    return ['col'];
  }

  attributeChangedCallback(name, _alt, neu) {
    if (name !== 'col') return;
    const index = Number(neu);
    // Numerischer Index plus lesbare Alternative (1 → "A", 2 → "B" …)
    this.#internals.ariaColIndex = String(index);
    this.#internals.ariaColIndexText = `Spalte ${String.fromCharCode(64 + index)}`;
  }

  get colIndexText() {
    return this.#internals.ariaColIndexText;
  }
}

customElements.define('data-cell', DataCell);

const zelle = document.createElement('data-cell');
zelle.setAttribute('col', '3');
document.body.append(zelle);
console.log(zelle.colIndexText);
console.log(zelle.hasAttribute('aria-colindextext'));

Spalte C false

Wochentage als Spaltentext in einem Kalender-Grid

const tage = ['Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag', 'Sonntag'];

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

  connectedCallback() {
    // Spalte aus der Position in der Zeile berechnen
    const spalte = [...this.parentElement.children].indexOf(this) + 1;
    this.#internals.role = 'gridcell';
    this.#internals.ariaColIndex = String(spalte);
    this.#internals.ariaColIndexText = tage[spalte - 1];
    console.log(`${spalte}: ${this.#internals.ariaColIndexText}`);
  }
}

customElements.define('calendar-day', CalendarDay);

const zeile = document.createElement('div');
zeile.setAttribute('role', 'row');
document.body.append(zeile);
for (let i = 0; i < 3; i++) zeile.append(document.createElement('calendar-day'));

1: Montag 2: Dienstag 3: Mittwoch

Feature-Erkennung und Zurücksetzen

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

  setColumnText(text) {
    if ('ariaColIndexText' in this.#internals) {
      this.#internals.ariaColIndexText = text;
    } else {
      // Fallback für ältere Browser: sichtbares Attribut setzen
      this.setAttribute('aria-colindextext', text ?? '');
    }
  }

  get text() {
    return this.#internals.ariaColIndexText ?? null;
  }
}

customElements.define('safe-cell', SafeCell);

const c = new SafeCell();
c.setColumnText('Umsatz 2024');
console.log(c.text);
c.setColumnText(null); // Standard-Semantik entfernen
console.log(c.text);

Umsatz 2024 null

// Wichtig · Fallstricke

Nur für autonome Custom Elements: attachInternals() gibt es nur für eigene Elemente, die direkt von HTMLElement erben. Pro Element darf die Methode nur einmal aufgerufen werden, ein zweiter Aufruf löst eine NotSupportedError aus.
Attribut hat Vorrang: Ein vom Nutzer gesetztes aria-colindextext-Attribut überschreibt den Wert aus ElementInternals. Das Attribut taucht außerdem nie im DOM auf, deshalb liefert getAttribute() hier null.
Immer zusammen mit ariaColIndex: Laut WAI-ARIA 1.3 ist aria-colindextext nur eine Ergänzung. Ohne numerischen Index kann eine Hilfstechnologie die Spaltenposition nicht sicher bestimmen.
Passende Rolle nötig: Das Attribut wirkt nur bei Rollen wie cell, gridcell, columnheader, rowheader oder row. Deshalb sollte auch internals.role gesetzt werden.
Kompatibilität: Die ARIA-Eigenschaften auf ElementInternals werden von aktuellen Chromium-Browsern, Firefox ab 119 und Safari ab 16.4 unterstützt. aria-colindextext stammt aus ARIA 1.3, daher lesen manche Screenreader den Text noch nicht vor. Nutze eine Feature-Erkennung mit 'ariaColIndexText' in internals.
Der Text ist nicht für die Übersetzung durch die Hilfstechnologie gedacht. Lokalisiere ihn deshalb selbst.

Siehe auch

ElementInternals ElementInternals.ariaColIndex ElementInternals.ariaRowIndexText ElementInternals.role Element.ariaColIndexText HTMLElement.attachInternals() ElementInternals.ariaFlowToElements