ElementInternals.ariaColSpan — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaColSpan

Beschreibung

Die Eigenschaft ariaColSpan der Schnittstelle ElementInternals entspricht dem ARIA-Attribut aria-colspan. Damit gibt eine Zelle (Rolle cell, gridcell, columnheader oder rowheader) an, über wie viele Spalten sie sich in einer table, einem grid oder einem treegrid erstreckt. Der Wert ist ein String mit einer positiven Ganzzahl, zum Beispiel "2".

Anders als Element.ariaColSpan schreibt die Variante auf ElementInternals kein sichtbares Attribut ins DOM. Sie legt stattdessen die Standard-Semantik eines autonomen Custom Elements fest. Setzt jemand, der das Element verwendet, selbst aria-colspan im Markup, hat dieses Attribut Vorrang. So kann eine Komponente sinnvolle Standardwerte mitbringen, ohne das Light DOM ihrer Nutzer zu verändern.

Das brauchen Sie vor allem bei eigenen Tabellen- oder Grid-Komponenten wie <data-cell>, die keine nativen <td>-Elemente verwenden und deshalb kein natives colspan haben. Das ElementInternals-Objekt erhalten Sie im Konstruktor mit this.attachInternals().

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: Ganzzahl als String (≥ 1), z. B. `"3"`. Mit `null` entfernen Sie die Standard-Semantik.

Rückgabewert

Typ

string | null

Beschreibung

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

Beispiele

Grid-Zelle mit Standard-Spaltenbreite

class GridCell extends HTMLElement {
  #internals;

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

customElements.define('grid-cell', GridCell);

const cell = document.createElement('grid-cell');
document.body.append(cell);
console.log(cell.hasAttribute('aria-colspan'));

false

colspan-Attribut der Komponente auf ARIA übertragen

class DataCell extends HTMLElement {
  static observedAttributes = ['colspan'];
  #internals = this.attachInternals();

  connectedCallback() {
    this.#internals.role = 'cell';
    this.style.gridColumn = `span ${this.#span}`;
  }

  get #span() {
    const n = Number.parseInt(this.getAttribute('colspan') ?? '1', 10);
    return Number.isInteger(n) && n > 0 ? n : 1;
  }

  attributeChangedCallback() {
    // Semantik und Darstellung synchron halten
    this.#internals.ariaColSpan = String(this.#span);
    this.style.gridColumn = `span ${this.#span}`;
    console.log('ariaColSpan:', this.#internals.ariaColSpan);
  }
}

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

// <data-cell colspan="3">Summe</data-cell>
const el = document.createElement('data-cell');
el.setAttribute('colspan', '3');

ariaColSpan: 3

Standardwert zurücksetzen

class HeaderCell extends HTMLElement {
  internals = this.attachInternals();
  constructor() {
    super();
    this.internals.role = 'columnheader';
    this.internals.ariaColSpan = '2';
  }
}
customElements.define('header-cell', HeaderCell);

const h = new HeaderCell();
console.log(h.internals.ariaColSpan);
h.internals.ariaColSpan = null;
console.log(h.internals.ariaColSpan);

2 null

// Wichtig · Fallstricke

Nur Semantik, kein Layout: ariaColSpan ändert die Darstellung nicht. Die sichtbare Spaltenbreite (z. B. grid-column: span 3) müssen Sie selbst per CSS setzen und synchron halten.
Wirkt nur mit passender Rolle: Das Element braucht eine Zellenrolle (cell, gridcell usw.) und muss sich in einem Container mit der Rolle table, grid oder treegrid befinden.
Vorrang: Ein vom Nutzer gesetztes aria-colspan-Attribut überschreibt den Wert aus ElementInternals. Umgekehrt spiegelt sich internals.ariaColSpan nie als Attribut im DOM – mit getAttribute() ist der Wert nicht sichtbar.
Der Wert ist immer ein String. Zahlen werden beim Setzen in Strings umgewandelt, ungültige Werte wie "0" ignorieren Hilfstechnologien.
attachInternals() funktioniert nur bei autonomen Custom Elements und nur einmal pro Element, sonst wird ein NotSupportedError geworfen.
Kompatibilität: Firefox unterstützt ARIA-Reflection auf ElementInternals erst ab Version 119. Für ältere Browser brauchen Sie eine Prüfung wie 'ariaColSpan' in ElementInternals.prototype und als Ausweichlösung setAttribute('aria-colspan', …).

Siehe auch

ElementInternals.ariaBusy ElementInternals.ariaRowSpan ElementInternals.ariaColCount ElementInternals.ariaColIndex ElementInternals.ariaModal