Signatur
Beschreibung
Mit ElementInternals.ariaRequired legt ein autonomes Custom Element fest, dass es eine Pflichteingabe darstellt, bevor ein Formular abgeschickt werden kann. Der Wert gelangt direkt in den Barrierefreiheitsbaum. Screenreader lesen das Element dann z. B. als „erforderlich“ vor, ohne dass im Light DOM ein aria-required-Attribut auftaucht.
Die Eigenschaft ist Teil des ARIA-Reflection-Mechanismus von ElementInternals. Sie legt die Standard-Semantik des Elements fest. Setzt der Nutzer der Komponente selbst ein aria-required-Attribut auf den Host, hat dieses Vorrang. So bleiben Komponenten überschreibbar, bringen aber sinnvolle Voreinstellungen mit.
Gebraucht wird die Eigenschaft vor allem bei formularassoziierten Custom Elements (static formAssociated = true), etwa bei eigenen Eingabefeldern, Auswahllisten oder Datumswählern. Wichtig: ariaRequired betrifft nur die Semantik für Hilfstechnologien. Für die eigentliche Formularprüfung musst du zusätzlich internals.setValidity() aufrufen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $wert | string | null | null | Beim Setzen: "true" (Eingabe erforderlich), "false" (nicht erforderlich, entspricht dem Standard) oder null (Standard-Semantik entfernen). |
Rückgabewert
"true" oder "false") oder null, wenn kein Wert gesetzt wurde.Beispiele
Pflichtfeld-Komponente mit Standard-Semantik
class PflichtEingabe extends HTMLElement {
static formAssociated = true;
constructor() {
super();
this.internals = this.attachInternals();
this.internals.role = 'textbox';
this.internals.ariaRequired = 'true';
}
}
customElements.define('pflicht-eingabe', PflichtEingabe);
const el = document.createElement('pflicht-eingabe');
console.log(el.internals.ariaRequired);
console.log(el.hasAttribute('aria-required'));ariaRequired mit dem required-Attribut synchronisieren und Validierung setzen
class MeinFeld extends HTMLElement {
static formAssociated = true;
static observedAttributes = ['required'];
#internals = this.attachInternals();
#wert = '';
connectedCallback() {
this.#internals.role = 'textbox';
this.tabIndex = 0;
this.#pruefen();
}
attributeChangedCallback(name) {
if (name === 'required') this.#pruefen();
}
set value(v) {
this.#wert = v;
this.#internals.setFormValue(v);
this.#pruefen();
}
#pruefen() {
const pflicht = this.hasAttribute('required');
// Semantik für Screenreader
this.#internals.ariaRequired = pflicht ? 'true' : 'false';
// Tatsächliche Formularvalidierung
if (pflicht && !this.#wert) {
this.#internals.setValidity({ valueMissing: true }, 'Bitte ausfüllen.');
} else {
this.#internals.setValidity({});
}
}
}
customElements.define('mein-feld', MeinFeld);Wert zurücksetzen
class Toggle extends HTMLElement {
constructor() {
super();
this.internals = this.attachInternals();
this.internals.ariaRequired = 'true';
}
}
customElements.define('x-toggle', Toggle);
const t = new Toggle();
t.internals.ariaRequired = null;
console.log(t.internals.ariaRequired);// Wichtig · Fallstricke
- Nur Semantik, keine Validierung:
ariaRequired = 'true'hält kein Formular vom Absenden ab. Dafür brauchst dusetValidity({ valueMissing: true }, …). - Der Wert ist ein String.
internals.ariaRequired = truewird zwar zu\"true\"umgewandelt, aberfalsewird zu\"false\"und nicht entfernt. Zum Entfernen setzt dunull. - Ein
aria-required-Attribut, das der Nutzer auf dem Host-Element setzt, überschreibt den Wert ausElementInternals. attachInternals()funktioniert nur bei autonomen Custom Elements und nur einmal pro Element. Ein zweiter Aufruf löst einenNotSupportedErroraus.- Browser-Unterstützung: Firefox kennt ARIA-Reflection auf
ElementInternalserst ab Version 119. In älteren Browsern prüfst du vorher mit'ariaRequired' in ElementInternals.prototypeund setzt ersatzweise das Attribut. aria-requiredist nur bei passenden Rollen sinnvoll (z. B.textbox,combobox,listbox,radiogroup,checkbox). Setze deshalb auchinternals.role.