ElementInternals: labels-Eigenschaft
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit März 2023 browserübergreifend verfügbar.
Die schreibgeschützte Eigenschaft labels des Interfaces ElementInternals gibt die dem Element zugeordneten Labels zurück.
Wert
Eine NodeList, die alle diesem Element zugeordneten Label-Elemente enthält.
Ausnahmen
NotSupportedErrorDOMException-
Wird ausgelöst, wenn für das Element die Eigenschaft
formAssociatednicht auftruegesetzt ist.
Bedenken hinsichtlich der Barrierefreiheit
Ein <label>, das mit einem formularzugeordneten benutzerdefinierten Element verknüpft ist, wird unterstützenden Technologien auf dieselbe Weise bereitgestellt wie ein Label für ein integriertes Formular-Steuerelement.
In Chrome und Firefox stellt es den zugänglichen Namen für das Element bereit.
Damit ein Screenreader diesen Namen erreichen kann, muss das Element außerdem fokussierbar sein.
Ein benutzerdefiniertes Element ist standardmäßig nicht fokussierbar.
Es benötigt ein tabindex-Attribut oder eine mit delegatesFocus: true erstellte Shadow Root mit einem darin enthaltenen fokussierbaren Element.
Safari stellt das Label auf diese Weise nicht bereit.
VoiceOver liest ein mit einem formularzugeordneten benutzerdefinierten Element verknüpftes <label> nicht vor (WebKit-Fehler 259124).
Ein Element, das sich ausschließlich auf die Label-Zuordnung stützt, hat daher in Safari keinen zugänglichen Namen.
Um dem Element in jedem Browser einen zugänglichen Namen zu geben, setzen Sie ariaLabel auf den Internals des Elements und ordnen Sie außerdem das Label zu:
class CustomCheckbox extends HTMLElement {
static formAssociated = true;
constructor() {
super();
this.internals_ = this.attachInternals();
this.internals_.role = "checkbox";
this.internals_.ariaLabel = "Join newsletter";
}
}
Hinweis:
Das Setzen von ariaLabel auf den Internals definiert eine Standard-Semantik für das Element.
Ein auf dem Element selbst gesetztes aria-label-Attribut hat Vorrang davor, sodass ein Seitenautor den Namen überschreiben kann, ohne dass die Komponente ihren eigenen Fallback verliert.
Beispiele
Das folgende Beispiel zeigt eine benutzerdefinierte Checkbox-Komponente mit einem damit verknüpften <label>-Element.
Das Ausgeben des Werts von labels in der Konsole gibt eine NodeList mit einem Eintrag zurück, der dieses Label repräsentiert.
<form id="myForm">
<custom-checkbox id="custom-checkbox" tabindex="0"></custom-checkbox>
<label for="custom-checkbox">Join newsletter</label>
</form>
class CustomCheckbox extends HTMLElement {
static formAssociated = true;
constructor() {
super();
this.internals_ = this.attachInternals();
}
// …
}
window.customElements.define("custom-checkbox", CustomCheckbox);
const element = document.getElementById("custom-checkbox");
console.log(element.internals_.labels); // NodeList [ label ]
Hinweis:
Ein Label wird erst in labels aufgenommen, nachdem es geparst wurde.
Das Lesen von labels aus connectedCallback() gibt eine leere NodeList zurück, wenn das zugeordnete <label> im Quelltext nach dem Element steht, da der Parser es noch nicht erreicht hat.
Spezifikationen
| Spezifikation |
|---|
| HTML # dom-elementinternals-labels |