Element.ariaOrientation — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaOrientation

Beschreibung

Die Eigenschaft ariaOrientation gehört zur ARIA-Reflexion (ARIAMixin) der Element-Schnittstelle und spiegelt das Attribut aria-orientation wider. Damit teilen Sie assistiven Technologien wie Screenreadern mit, ob ein Bedienelement horizontal oder vertikal ausgerichtet ist. Die Ausrichtung bestimmt auch, welche Pfeiltasten Nutzer zur Bedienung erwarten.

Sinnvoll ist das Attribut bei Rollen wie scrollbar, select, separator, slider, tablist, toolbar, listbox, menu, menubar und radiogroup. Die Standardwerte hängen von der Rolle ab: slider, separator, scrollbar, tablist und toolbar sind implizit horizontal, listbox und menu implizit vertical.

Wenn Sie die Eigenschaft setzen, wird das Attribut sofort im DOM geschrieben. Wenn Sie sie auslesen, erhalten Sie den Attributwert als String oder null, falls das Attribut fehlt. Mit null als Wert wird das Attribut entfernt. Einen Vorteil gegenüber setAttribute('aria-orientation', …) bietet die Eigenschaft vor allem bei der Lesbarkeit in Web-Components und Framework-Code.

Rückgabewert

Typ

string | null

Beschreibung

"horizontal", "vertical" oder "undefined" (unbekannt/mehrdeutig, der Standard), bzw. null, wenn das Attribut nicht gesetzt ist. Andere Werte werden unverändert als String zurückgegeben, aber nicht validiert.

Beispiele

Ausrichtung auslesen

// <div id="lautstaerke" role="slider" aria-orientation="vertical" tabindex="0"></div>
const slider = document.getElementById('lautstaerke');
console.log(slider.ariaOrientation);

const ohneAttribut = document.createElement('div');
console.log(ohneAttribut.ariaOrientation);

vertical null

Toolbar responsiv umschalten

const toolbar = document.querySelector('[role="toolbar"]');
const mq = window.matchMedia('(max-width: 600px)');

const aktualisieren = () => {
  // Auf schmalen Bildschirmen wird die Toolbar vertikal gestapelt
  toolbar.ariaOrientation = mq.matches ? 'vertical' : 'horizontal';
  toolbar.classList.toggle('vertikal', mq.matches);
};

mq.addEventListener('change', aktualisieren);
aktualisieren();
console.log(toolbar.getAttribute('aria-orientation'));

horizontal (bzw. vertical bei schmalem Viewport)

Pfeiltasten passend zur Ausrichtung auswerten

const tablist = document.querySelector('[role="tablist"]');

tablist.addEventListener('keydown', (event) => {
  // tablist ist implizit horizontal
  const vertikal = tablist.ariaOrientation === 'vertical';
  const vor = vertikal ? 'ArrowDown' : 'ArrowRight';
  const zurueck = vertikal ? 'ArrowUp' : 'ArrowLeft';
  const tabs = [...tablist.querySelectorAll('[role="tab"]')];
  const index = tabs.indexOf(document.activeElement);
  if (index === -1) return;

  if (event.key === vor) {
    event.preventDefault();
    tabs[(index + 1) % tabs.length].focus();
  } else if (event.key === zurueck) {
    event.preventDefault();
    tabs[(index - 1 + tabs.length) % tabs.length].focus();
  }
});

Attribut entfernen

const trenner = document.querySelector('[role="separator"]');
trenner.ariaOrientation = 'vertical';
console.log(trenner.hasAttribute('aria-orientation'));

trenner.ariaOrientation = null; // entfernt das Attribut
console.log(trenner.hasAttribute('aria-orientation'), trenner.ariaOrientation);

true false null

// Wichtig · Fallstricke

Kompatibilität: Chromium und Safari unterstützen die Eigenschaft seit Langem, Firefox erst ab Version 119. Für ältere Browser verwenden Sie setAttribute('aria-orientation', …) bzw. getAttribute().
Keine Validierung: Ungültige Werte wie "diagonal" werden übernommen, ohne dass ein Fehler auftritt. Assistive Technologien ignorieren sie dann. Beachten Sie außerdem: "undefined" ist ein String und nicht der JS-Wert undefined. Wenn Sie undefined zuweisen, entsteht der String "undefined". Das Attribut entfernen Sie nur mit null.
Nur Semantik: Die Eigenschaft ändert weder das Layout noch die Tastaturbedienung. CSS und Tastatursteuerung müssen Sie selbst passend umsetzen.
Implizite Werte: Wenn das Attribut fehlt, liefert der Getter null, auch wenn die Rolle einen impliziten Standardwert hat. Diesen Standard müssen Sie in Ihrer Logik selbst berücksichtigen.
Native Elemente wie <input type=\"range\"> geben ihre Ausrichtung bereits selbst an. Verwenden Sie aria-orientation vor allem bei eigenen Widgets mit expliziter role.

Siehe auch

Element.role ContactAddress.organization Element.activeViewTransition Element.ariaDescription Element.ariaInvalid