ElementInternals.ariaFlowToElements — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaFlowToElements

Beschreibung

Über die Eigenschaft ariaFlowToElements der Schnittstelle ElementInternals legt ein autonomes Custom Element fest, welche Elemente semantisch als nächstes im Lesefluss folgen. Sie ist das Gegenstück zum ARIA-Attribut aria-flowto auf Ebene der Element-Internals, arbeitet aber mit direkten Element-Referenzen statt mit ID-Listen.

Der Wert, den man hier setzt, ist die Standard-Semantik des Custom Elements: Er wirkt, solange der Autor der Seite am Element selbst kein aria-flowto-Attribut und kein element.ariaFlowToElements gesetzt hat. So kann eine Komponente eine sinnvolle Voreinstellung mitliefern, die der Anwender der Komponente trotzdem überschreiben kann.

Einsatzgebiete sind Layouts, in denen die visuelle Anordnung (z. B. mehrspaltige Artikel, Randnotizen, Diagramme, Prozessschritte) nicht der DOM-Reihenfolge entspricht. Screenreader, die aria-flowto unterstützen (vor allem JAWS), bieten dem Nutzer dann an, zum referenzierten Element zu springen. Mehrere Elemente im Array bedeuten Verzweigungen, zwischen denen der Nutzer wählen kann.

Da Element-Referenzen verwendet werden, können auch Elemente angegeben werden, die keine ID besitzen. Allerdings gelten die Regeln zur Shadow-DOM-Kapselung: Referenzierte Elemente müssen im selben Baum oder in einem umgebenden (Licht-)DOM liegen.

Parameter

Name	Typ	Default	Beschreibung
$value	Array<Element> \| null	null	Beim Setzen: ein Array von Elementen, die als alternative nächste Lesepositionen dienen. `null` entfernt die Standard-Semantik.

Rückgabewert

Typ

Array<Element> | null

Beschreibung

Ein eingefrorenes Array der aktuell referenzierten Elemente oder null, wenn nichts gesetzt ist. Elemente, die nicht (mehr) gültig referenzierbar sind, werden beim Lesen herausgefiltert.

Beispiele

Standard-Lesefluss in einem Custom Element setzen

class StepCard extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'region';
  }
  connectedCallback() {
    // Nächster Schritt ist über das Attribut data-next referenziert
    const next = document.getElementById(this.dataset.next);
    if (next) {
      this.#internals.ariaFlowToElements = [next];
    }
  }
  get flowTargets() {
    return this.#internals.ariaFlowToElements;
  }
}
customElements.define('step-card', StepCard);

// HTML: <step-card id="s1" data-next="s3"></step-card> ... <step-card id="s3"></step-card>
const card = document.querySelector('#s1');
console.log(card.flowTargets?.map((el) => el.id));

["s3"]

Verzweigung auf mehrere Ziele

class ArticleColumn extends HTMLElement {
  internals = this.attachInternals();
  setFlow(...targets) {
    this.internals.ariaFlowToElements = targets;
  }
}
customElements.define('article-column', ArticleColumn);

const col = document.createElement('article-column');
const sidebar = document.createElement('aside');
const nextCol = document.createElement('article-column');
document.body.append(col, sidebar, nextCol);

// Nutzer kann wählen: weiter zur nächsten Spalte oder zur Randnotiz
col.setFlow(nextCol, sidebar);
console.log(col.internals.ariaFlowToElements.length);

2

Autor-Attribut überschreibt die Voreinstellung

class FlowBox extends HTMLElement {
  internals = this.attachInternals();
}
customElements.define('flow-box', FlowBox);

const box = document.createElement('flow-box');
const a = Object.assign(document.createElement('div'), { id: 'a' });
const b = Object.assign(document.createElement('div'), { id: 'b' });
document.body.append(box, a, b);

box.internals.ariaFlowToElements = [a]; // Standard der Komponente
box.setAttribute('aria-flowto', 'b');   // Seitenautor hat Vorrang

// Internals bleibt unverändert, der Accessibility-Baum nutzt aber 'b'
console.log(box.internals.ariaFlowToElements[0].id, box.getAttribute('aria-flowto'));

// Voreinstellung wieder entfernen
box.internals.ariaFlowToElements = null;
console.log(box.internals.ariaFlowToElements);

a b null

// Wichtig · Fallstricke

Browser-Kompatibilität: Die ARIA-Element-Referenz-Eigenschaften (*Elements) auf ElementInternals sind noch nicht überall verfügbar. Vor der Nutzung per 'ariaFlowToElements' in ElementInternals.prototype prüfen und ggf. auf aria-flowto mit IDs ausweichen.
Screenreader-Unterstützung: aria-flowto wird von vielen Screenreadern (z. B. NVDA, VoiceOver) kaum oder gar nicht ausgewertet. Nicht als einziges Mittel für eine verständliche Reihenfolge einsetzen – eine logische DOM-Reihenfolge ist immer vorzuziehen.
Shadow DOM: Elemente in einem anderen Shadow-Root (z. B. tiefer verschachtelt) werden beim Lesen herausgefiltert und im Accessibility-Baum ignoriert.
Das gelesene Array ist eingefroren; push() o. Ä. wirft einen Fehler. Immer ein neues Array zuweisen.
Nur für autonome Custom Elements verfügbar, da attachInternals() auf eingebauten Elementen einen NotSupportedError auslöst.
Die Internals-Werte werden nicht als Attribut im DOM sichtbar (getAttribute('aria-flowto') liefert weiterhin null).

Siehe auch

ElementInternals.ariaControlsElements ElementInternals.ariaOwnsElements ElementInternals.ariaDetailsElements ElementInternals.ariaLabelledByElements ElementInternals.ariaRelevant