ElementInternals.ariaRowSpan — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaRowSpan

Beschreibung

Die Eigenschaft ariaRowSpan der Schnittstelle ElementInternals legt fest, wie viele Zeilen eine Zelle (role="cell", gridcell, rowheader oder columnheader) in einer Tabelle, einem Grid oder einem Treegrid überspannt. Sie gehört zur ARIA-Reflexion und entspricht inhaltlich dem Attribut aria-rowspan.

Der wichtige Unterschied zu Element.ariaRowSpan: Über ElementInternals setzt ein autonomes Custom Element seine Standard-Semantik, ohne ein sichtbares Attribut in das DOM zu schreiben. Das Host-Element bleibt „sauber“, und Nutzer der Komponente können den Wert jederzeit mit einem eigenen aria-rowspan-Attribut überschreiben. Das Attribut auf dem Element hat immer Vorrang.

Man braucht die Eigenschaft vor allem bei eigenen Tabellen- oder Grid-Komponenten, deren Zellen aus Custom Elements bestehen, etwa <data-cell> innerhalb von <data-grid>. Da solche Elemente keine native <td rowspan>-Semantik haben, müssen Hilfstechnologien wie Screenreader über ARIA erfahren, dass eine Zelle mehrere Zeilen belegt.

Der Wert ist ein String mit einer ganzen Zahl ≥ 0 oder null, wenn kein Wert gesetzt ist. Laut ARIA-Spezifikation bedeutet 0, dass die Zelle alle übrigen Zeilen des aktuellen Abschnitts überspannt. Diese Bedeutung wird aber nicht überall zuverlässig unterstützt.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: String mit einer ganzen Zahl ≥ 0 (z. B. `"2"`). Mit `null` wird der Standardwert entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell per ElementInternals gesetzte Standardwert für aria-rowspan oder null, falls keiner gesetzt ist. Ein aria-rowspan-Attribut auf dem Host-Element wird hier nicht wiedergegeben.

Beispiele

Custom-Grid-Zelle mit Standard-Rowspan

class GridCell extends HTMLElement {
  #internals;

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

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

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

const cell = document.createElement('grid-cell');
console.log(cell.internals.ariaRowSpan);
console.log(cell.hasAttribute('aria-rowspan'));

1 false

Rowspan dynamisch aus einer Eigenschaft ableiten

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

  connectedCallback() {
    this.#internals.role = 'cell';
  }

  attributeChangedCallback(name, _old, value) {
    if (name === 'span-rows') {
      const n = Number.parseInt(value, 10);
      // Nur gültige Werte übernehmen, sonst Standard entfernen
      this.#internals.ariaRowSpan = Number.isInteger(n) && n >= 0 ? String(n) : null;
      console.log('ariaRowSpan =', this.#internals.ariaRowSpan);
    }
  }
}

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

const td = document.createElement('data-cell');
td.setAttribute('span-rows', '3');
td.setAttribute('span-rows', 'abc');

ariaRowSpan = 3 ariaRowSpan = null

Attribut überschreibt den Internals-Standardwert

class HeaderCell extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals();
    internals.role = 'rowheader';
    internals.ariaRowSpan = '2';
  }
}

customElements.define('header-cell', HeaderCell);

const el = document.createElement('header-cell');
// Der Nutzer der Komponente überschreibt den Standardwert
el.setAttribute('aria-rowspan', '4');
console.log(el.ariaRowSpan); // Element-Reflexion zeigt das Attribut

4

// Wichtig · Fallstricke

Nur für autonome Custom Elements: attachInternals() wirft bei eingebauten Elementen und erweiterten Built-ins (is="…") einen NotSupportedError. Pro Element darf attachInternals() außerdem nur einmal aufgerufen werden.
Vorrang: Ein aria-rowspan-Attribut auf dem Host-Element überschreibt den Wert aus ElementInternals. internals.ariaRowSpan gibt das Attribut nicht wieder.
Typ ist String: Zahlen werden beim Setzen in Strings umgewandelt. Die Gültigkeit prüft der Browser nicht, ungültige Werte wie "-1" werden einfach gespeichert und von Hilfstechnologien ignoriert. Deshalb sollte man die Werte selbst prüfen.
Nur mit passender Rolle sinnvoll: aria-rowspan wirkt nur bei cell, gridcell, rowheader und columnheader innerhalb von table, grid oder treegrid. Sobald die Tabelle virtualisiert ist, sollte sie auch aria-rowcount und aria-rowindex konsistent angeben.
Kompatibilität: Die ARIA-Reflexion auf ElementInternals gibt es in Chromium seit Version 81 und in Safari seit 16.4. Firefox unterstützt sie erst ab Version 119. Für ältere Browser mit Feature-Erkennung prüfen ('ariaRowSpan' in ElementInternals.prototype) und bei Bedarf auf setAttribute('aria-rowspan', …) ausweichen.

Siehe auch

ElementInternals.ariaColSpan ElementInternals.ariaRowCount ElementInternals.ariaModal ElementInternals.ariaRelevant ElementInternals.ariaRowIndex