ElementInternals.ariaSort — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaSort

Beschreibung

Mit der Eigenschaft ariaSort des ElementInternals-Objekts legt ein autonomes Custom Element seine Standard-Semantik für den ARIA-Zustand aria-sort fest. Dieser Zustand sagt assistiven Technologien wie Screenreadern, ob eine Tabellen- oder Rasterspalte aufsteigend, absteigend, anders oder gar nicht sortiert ist.

Anders als Element.ariaSort wird dabei kein Attribut in das Markup geschrieben. Der Wert geht direkt in den Barrierefreiheitsbaum (Accessibility Tree) ein. Die Komponente sieht also für Nutzer von assistiven Technologien korrekt aus, und ihr Light DOM bleibt trotzdem sauber. Setzt der Autor der Seite selbst ein aria-sort-Attribut auf das Element, hat dieses Vorrang vor dem internen Wert.

Erlaubte Werte sind die Zeichenketten "ascending", "descending", "none" und "other". Mit null entfernen Sie den Standardwert wieder. Sinnvoll ist aria-sort nur bei Elementen mit der Rolle columnheader oder rowheader. Setzen Sie deshalb zusätzlich internals.role.

Setzen Sie aria-sort immer nur auf eine Spalte gleichzeitig, nämlich die, nach der gerade sortiert wird. Die übrigen Überschriften sollten "none" oder gar keinen Wert haben.

Parameter

Name	Typ	Default	Beschreibung
$value	"ascending" \| "descending" \| "none" \| "other" \| null	null	Neuer Sortierzustand beim Setzen. Mit `null` wird der Standardwert entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell intern gesetzte Sortierzustand als Zeichenkette oder null, wenn kein Wert gesetzt ist. Ein aria-sort-Attribut, das der Seitenautor gesetzt hat, wird hier nicht zurückgegeben.

Beispiele

Sortierbare Spaltenüberschrift als Custom Element

class SortHeader extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'columnheader';
    this.#internals.ariaSort = 'none';
    this.tabIndex = 0;
    this.addEventListener('click', () => this.toggle());
  }
  toggle() {
    const next = this.#internals.ariaSort === 'ascending' ? 'descending' : 'ascending';
    this.#internals.ariaSort = next;
    console.log(`${this.textContent}: ${next}`);
  }
}
customElements.define('sort-header', SortHeader);

// <sort-header>Name</sort-header>
const header = document.createElement('sort-header');
header.textContent = 'Name';
document.body.append(header);
header.click();
header.click();

Name: ascending Name: descending

Nur eine Spalte gleichzeitig als sortiert markieren

class GridHeader extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'columnheader';
  }
  set sortState(value) {
    this.internals.ariaSort = value;
  }
}
customElements.define('grid-header', GridHeader);

const headers = ['Name', 'Preis', 'Datum'].map((label) => {
  const h = document.createElement('grid-header');
  h.textContent = label;
  document.body.append(h);
  return h;
});

const sortBy = (active, direction) => {
  for (const h of headers) {
    h.sortState = h === active ? direction : 'none';
  }
};

sortBy(headers[1], 'descending');
console.log(headers.map((h) => `${h.textContent}=${h.internals.ariaSort}`).join(', '));

Name=none, Preis=descending, Datum=none

Autoren-Attribut hat Vorrang

class MyCol extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'columnheader';
    this.internals.ariaSort = 'ascending';
  }
}
customElements.define('my-col', MyCol);

const col = document.createElement('my-col');
col.setAttribute('aria-sort', 'other');
console.log(col.internals.ariaSort); // interner Standardwert
console.log(col.getAttribute('aria-sort')); // gilt für den Accessibility Tree

col.internals.ariaSort = null; // Standardwert entfernen
console.log(col.internals.ariaSort);

ascending other null

// Wichtig · Fallstricke

attachInternals() funktioniert nur bei autonomen Custom Elements, also Klassen, die direkt von HTMLElement erben. Rufen Sie die Methode pro Element nur einmal auf, sonst wird ein NotSupportedError ausgelöst.
Der Browser prüft den Wert nicht. Ungültige Zeichenketten wie "asc" werden angenommen, von assistiven Technologien aber ignoriert oder wie "none" behandelt.
Ohne passende Rolle (columnheader/rowheader) innerhalb einer table- oder grid-Struktur hat aria-sort keine Wirkung.
Die ARIA-Spiegel-Eigenschaften (ARIA Reflection) auf ElementInternals gibt es in Chromium seit Version 90, in Safari seit 16.4 und in Firefox seit 119. Für ältere Browser brauchen Sie als Ausweichlösung ein normales aria-sort-Attribut per setAttribute.
Den internen Wert kann man nicht über CSS-Attributselektoren abfragen. Für eine optische Kennzeichnung eignen sich eigene Zustände über internals.states (:state()).

Siehe auch

ElementInternals.ariaAtomic ElementInternals.ariaBusy ElementInternals.ariaLive ElementInternals.ariaModal ElementInternals.ariaCurrent