Signatur
Beschreibung
Die Eigenschaft ariaCurrent des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-current. Damit wird das Element gekennzeichnet, das innerhalb eines Containers oder einer zusammengehörigen Gruppe das aktuelle ist, z. B. die aktive Seite in einer Navigation, der aktuelle Schritt in einem Assistenten oder das heutige Datum in einem Kalender.
Anders als Element.ariaCurrent bzw. das HTML-Attribut aria-current legt der Wert auf ElementInternals die Standard-Semantik eines autonomen Custom Elements fest. Er erscheint nicht im DOM als Attribut und lässt sich deshalb vom Nutzer der Komponente nicht versehentlich entfernen. Setzt der Autor der Seite trotzdem selbst ein aria-current-Attribut am Host-Element, hat dieses Vorrang.
Gültige Werte sind die Zeichenketten "page", "step", "location", "date", "time", "true" und "false". Mit null wird die Standard-Semantik wieder entfernt. Man nutzt die Eigenschaft typischerweise im Konstruktor oder in Reaktion auf Zustandsänderungen einer Web Component, die über this.attachInternals() ein ElementInternals-Objekt erhalten hat.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | null | null | Neuer Wert beim Setzen: "page", "step", "location", "date", "time", "true" oder "false". null entfernt die Standard-Semantik. |
Rückgabewert
aria-current als Zeichenkette oder null, wenn keiner gesetzt ist.Beispiele
Standard-Semantik im Konstruktor setzen
class NavLink extends HTMLElement {
#internals;
constructor() {
super();
this.#internals = this.attachInternals();
this.#internals.role = 'link';
this.#internals.ariaCurrent = 'false';
}
get internals() { return this.#internals; }
}
customElements.define('nav-link', NavLink);
const link = document.createElement('nav-link');
console.log(link.internals.ariaCurrent);
console.log(link.hasAttribute('aria-current'));Aktive Seite in einer Navigation markieren
class NavItem extends HTMLElement {
static observedAttributes = ['href'];
#internals = this.attachInternals();
connectedCallback() {
this.#internals.role = 'link';
this.#update();
}
attributeChangedCallback() { this.#update(); }
#update() {
const isCurrent = this.getAttribute('href') === location.pathname;
// Nur die aktuelle Seite erhält "page", sonst Semantik entfernen
this.#internals.ariaCurrent = isCurrent ? 'page' : null;
}
}
customElements.define('nav-item', NavItem);Aktuellen Schritt in einem Assistenten setzen
class WizardStep extends HTMLElement {
#internals = this.attachInternals();
set active(value) {
this.#internals.ariaCurrent = value ? 'step' : null;
}
get active() {
return this.#internals.ariaCurrent === 'step';
}
}
customElements.define('wizard-step', WizardStep);
const steps = [...document.querySelectorAll('wizard-step')];
const goTo = (index) => steps.forEach((s, i) => { s.active = i === index; });
goTo(1);
console.log(steps.map((s) => s.active));// Wichtig · Fallstricke
attachInternals()funktioniert nur bei autonomen Custom Elements (nicht beiis="…"-Erweiterungen eingebauter Elemente) und darf pro Element nur einmal aufgerufen werden, sonst wird einNotSupportedErrorausgelöst.- Ein vom Seitenautor gesetztes
aria-current-Attribut am Host-Element überschreibt den Wert ausElementInternals. Der Wert ausElementInternalsgilt also nur als Standard. - Der Browser prüft den Wert nicht. Ungültige Zeichenketten werden gespeichert, von assistiven Technologien aber meist wie
"true"behandelt. Für „nicht aktuell“ bessernullsetzen als"false". ariaCurrentsollte innerhalb einer Gruppe jeweils nur einem Element zugewiesen werden.- Kompatibilität: ARIA-Reflexion über
ElementInternalsgibt es in Chromium seit Version 81, in Safari seit 16.4 und in Firefox erst seit 119. Für ältere Browser per'ariaCurrent' in ElementInternals.prototypeprüfen und notfalls aufsetAttribute('aria-current', …)ausweichen.