ElementInternals.ariaOrientation — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaOrientation

Beschreibung

Die Eigenschaft ariaOrientation der ElementInternals-Schnittstelle entspricht dem ARIA-Attribut aria-orientation. Sie gibt an, ob ein Element horizontal, vertikal oder mit unbekannter bzw. mehrdeutiger Ausrichtung dargestellt wird. Assistive Technologien wie Screenreader nutzen die Information, um Nutzern die richtige Pfeiltasten-Navigation anzukündigen, zum Beispiel bei Schiebereglern, Scrollbars, Toolbars, Tablists, Menüs oder Trennlinien (separator).

Anders als Element.ariaOrientation setzt die Variante auf ElementInternals kein sichtbares Attribut im DOM. Sie legt eine Standard-Semantik für ein autonomes Custom Element fest. Setzt ein Autor später selbst aria-orientation auf dem Host-Element, gilt dieser Wert. So kann eine Komponente ihre Barrierefreiheits-Informationen intern festlegen, ohne das Markup des Nutzers zu verändern.

Die ElementInternals bekommt man nur im Custom Element selbst über this.attachInternals(), typischerweise im Konstruktor. Der Wert ist ein String oder null. null bedeutet, dass keine Standard-Ausrichtung festgelegt ist. Dann gilt der implizite Wert der jeweiligen Rolle, etwa horizontal bei slider und tablist oder vertical bei scrollbar und listbox.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Neuer Wert beim Setzen: `"horizontal"`, `"vertical"` oder `"undefined"` (als String: unbekannt/mehrdeutig). Mit `null` wird die Standard-Semantik entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Die aktuell hinterlegte Standard-Ausrichtung als String oder null, wenn keine gesetzt ist.

Beispiele

Custom Slider mit vertikaler Standard-Ausrichtung

class VSlider extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'slider';
    this.#internals.ariaOrientation = 'vertical';
    this.#internals.ariaValueMin = '0';
    this.#internals.ariaValueMax = '100';
    this.#internals.ariaValueNow = '50';
    this.tabIndex = 0;
  }
  get orientation() {
    return this.#internals.ariaOrientation;
  }
}
customElements.define('v-slider', VSlider);

const slider = document.createElement('v-slider');
document.body.append(slider);
console.log(slider.orientation);
console.log(slider.getAttribute('aria-orientation'));

vertical null

Ausrichtung dynamisch per Attribut umschalten

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

  connectedCallback() {
    this.#internals.role = 'toolbar';
    this.#update();
  }
  attributeChangedCallback() {
    this.#update();
  }
  #update() {
    const value = this.getAttribute('orientation') === 'vertical'
      ? 'vertical'
      : 'horizontal';
    this.#internals.ariaOrientation = value;
    console.log(`Toolbar-Ausrichtung: ${value}`);
  }
}
customElements.define('tool-bar', ToolBar);

const bar = document.createElement('tool-bar');
document.body.append(bar);
bar.setAttribute('orientation', 'vertical');

Toolbar-Ausrichtung: horizontal Toolbar-Ausrichtung: vertical

Pfeiltasten passend zur Ausrichtung auswerten

class TabStrip extends HTMLElement {
  #internals = this.attachInternals();
  constructor() {
    super();
    this.#internals.role = 'tablist';
    this.#internals.ariaOrientation = 'vertical';
    this.addEventListener('keydown', (e) => {
      const vertical = this.#internals.ariaOrientation === 'vertical';
      const next = vertical ? 'ArrowDown' : 'ArrowRight';
      const prev = vertical ? 'ArrowUp' : 'ArrowLeft';
      if (e.key === next) console.log('Nächster Tab');
      if (e.key === prev) console.log('Vorheriger Tab');
    });
  }
}
customElements.define('tab-strip', TabStrip);

const strip = document.createElement('tab-strip');
document.body.append(strip);
strip.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown' }));

Nächster Tab

// Wichtig · Fallstricke

Kein Attribut-Reflektieren: Der Wert erscheint nicht als aria-orientation im DOM. Ein Attribut, das der Autor auf dem Host-Element setzt, hat Vorrang vor dem internen Standardwert.
Nur bei passenden Rollen sinnvoll: aria-orientation wird nur für Rollen wie scrollbar, select, separator, slider, tablist, toolbar, listbox, menu, menubar, radiogroup und tree ausgewertet. Ohne passende role ignorieren assistive Technologien den Wert.
Keine Validierung: Ungültige Strings werden ohne Fehler gespeichert, aber nicht wie gültige ARIA-Werte behandelt. Mit "undefined" ist der String gemeint, nicht der JavaScript-Wert undefined.
Nur Semantik: Die Eigenschaft ändert weder Layout noch Tastaturverhalten. Die Pfeiltasten-Navigation muss die Komponente selbst umsetzen.
attachInternals(): Diese Methode lässt sich nur einmal pro Element aufrufen und nur bei autonomen Custom Elements, nicht bei angepassten eingebauten Elementen (is="…").
Kompatibilität: Die ARIA-Spiegelung auf ElementInternals gibt es in Firefox erst ab Version 119. Für ältere Browser kann man als Rückfall this.setAttribute('aria-orientation', …) verwenden.

Siehe auch

ElementInternals.ariaDescription ElementInternals.ariaInvalid ElementInternals.ariaCurrent ElementInternals.ariaPosInSet ElementInternals.ariaReadOnly