ElementInternals

Baseline 2023 *

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Some parts of this feature may have varying levels of support.

Das ElementInternals Interface des Document Object Model bietet Webentwicklern eine Möglichkeit, benutzerdefinierte Elemente vollständig an HTML-Formulare teilnehmen zu lassen. Es stellt Werkzeuge zur Verfügung, um mit diesen Elementen auf die gleiche Weise zu arbeiten wie mit jedem standardmäßigen HTML-Formularelement. Außerdem wird das Accessibility Object Model für das Element zugänglich gemacht.

Konstruktor

Dieses Interface hat keinen Konstruktor. Ein ElementInternals-Objekt wird zurückgegeben, wenn HTMLElement.attachInternals() aufgerufen wird.

Instanz-Eigenschaften

ElementInternals.shadowRoot Schreibgeschützt: Gibt das ShadowRoot-Objekt zurück, das mit diesem Element assoziiert ist.
ElementInternals.form Schreibgeschützt: Gibt das HTMLFormElement zurück, das mit diesem Element assoziiert ist.
ElementInternals.states Schreibgeschützt: Gibt das CustomStateSet zurück, das mit diesem Element assoziiert ist.
ElementInternals.willValidate Schreibgeschützt: Ein boolescher Wert, der true zurückgibt, wenn das Element ein übermittelbares Element ist, das ein Kandidat für die Einschränkungsvalidierung ist.
ElementInternals.validity Schreibgeschützt: Gibt ein ValidityState-Objekt zurück, das die verschiedenen Gültigkeitszustände des Elements im Hinblick auf die Einschränkungsvalidierung darstellt.
ElementInternals.validationMessage Schreibgeschützt: Ein String, der die Validierungsnachricht dieses Elements enthält.
ElementInternals.labels Schreibgeschützt: Gibt eine NodeList von allen dem Element zugeordneten Beschriftungselementen zurück.

Instanz-Eigenschaften, die von ARIA enthalten sind

Das ElementInternals-Interface enthält auch die folgenden Eigenschaften.

Hinweis: Diese sind enthalten, um sicherzustellen, dass Standard-Zugänglichkeitssemantiken auf einem benutzerdefinierten Element definiert werden können. Diese können durch benutzerdefinierte Attribute überschrieben werden, stellen jedoch sicher, dass die Standardsemantiken beibehalten werden, falls der Autor diese Attribute löscht oder sie gar nicht hinzufügt. Weitere Informationen finden Sie im Accessibility Object Model erläuterer.

ElementInternals.ariaAtomic: Ein String, der das aria-atomic-Attribut widerspiegelt, welches angibt, ob unterstützende Technologien den gesamten geänderten Bereich oder nur Teile davon basierend auf den durch das aria-relevant-Attribut definierten Änderungsmitteilungen präsentieren werden.
ElementInternals.ariaAutoComplete: Ein String, der das aria-autocomplete-Attribut widerspiegelt, welches angibt, ob Texteingaben die Anzeige von einer oder mehreren Vorhersagen des beabsichtigten Werts eines Benutzer für ein Kombinationsfeld, Suchfeld oder Textfeld auslösen könnten und wie Vorhersagen präsentiert würden, falls sie gemacht würden.
ElementInternals.ariaBrailleLabel: Ein String, der das aria-braillelabel-Attribut widerspiegelt, welches die Braille-Beschriftung des Elements definiert.
ElementInternals.ariaBrailleRoleDescription: Ein String, der das aria-brailleroledescription-Attribut widerspiegelt, welches die ARIA-Braille-Rollenbeschreibung des Elements definiert.
ElementInternals.ariaBusy: Ein String, der das aria-busy-Attribut widerspiegelt, welches angibt, ob ein Element modifiziert wird, da unterstützende Technologien möglicherweise warten möchten, bis die Modifikationen abgeschlossen sind, bevor sie dem Benutzer zugänglich gemacht werden.
ElementInternals.ariaChecked: Ein String, der das aria-checked-Attribut widerspiegelt, welches den aktuellen "geprüften" Zustand von Kontrollkästchen, Optionsfeldern und anderen Widgets angibt, die einen geprüften Zustand haben.
ElementInternals.ariaColCount: Ein String, der das aria-colcount-Attribut widerspiegelt, welches die Anzahl der Spalten in einer Tabelle, einem Raster oder einem Baumraster definiert.
ElementInternals.ariaColIndex: Ein String, der das aria-colindex-Attribut widerspiegelt, welches den Spaltenindex oder die Position eines Elements im Verhältnis zur Gesamtanzahl der Spalten innerhalb einer Tabelle, eines Rasters oder eines Baumrasters definiert.
ElementInternals.ariaColIndexText: Ein String, der das aria-colindextext-Attribut widerspiegelt, welches eine menschenlesbare Textalternative zu aria-colindex definiert.
ElementInternals.ariaColSpan: Ein String, der das aria-colspan-Attribut widerspiegelt, welches die Anzahl der von einer Zelle oder Rasterzelle innerhalb einer Tabelle, eines Rasters oder eines Baumrasters überspannten Spalten definiert.
ElementInternals.ariaCurrent: Ein String, der das aria-current-Attribut widerspiegelt, welches das Element angibt, das das aktuelle Element innerhalb eines Containers oder Satzes verwandter Elemente darstellt.
ElementInternals.ariaDescription: Ein String, der das aria-description-Attribut widerspiegelt, welches einen Stringwert definiert, der das aktuelle ElementInternals beschreibt oder annotiert.
ElementInternals.ariaDisabled: Ein String, der das aria-disabled-Attribut widerspiegelt, welches angibt, dass das Element wahrnehmbar, aber deaktiviert ist, sodass es nicht bearbeitbar oder anderweitig bedienbar ist.
ElementInternals.ariaExpanded: Ein String, der das aria-expanded-Attribut widerspiegelt, welches angibt, ob ein Gruppierungselement, das diesem Element gehört oder von ihm kontrolliert wird, erweitert oder eingeklappt ist.
ElementInternals.ariaHasPopup: Ein String, der das aria-haspopup-Attribut widerspiegelt, welches die Verfügbarkeit und den Typ eines interaktiven Popup-Elements angibt, wie Menü oder Dialog, das durch ein ElementInternals ausgelöst werden kann.
ElementInternals.ariaHidden: Ein String, der das aria-hidden-Attribut widerspiegelt, welches angibt, ob das Element einer Zugänglichkeits-API ausgesetzt ist.
ElementInternals.ariaInvalid: Ein String, der das aria-invalid-Attribut widerspiegelt, welches angibt, dass der eingegebene Wert nicht dem von der Anwendung erwarteten Format entspricht.
ElementInternals.ariaKeyShortcuts: Ein String, der das aria-keyshortcuts-Attribut widerspiegelt, welches angibt, welche Tastenkombinationen ein Autor implementiert hat, um ein Objekt zu aktivieren oder den Fokus darauf zu setzen.
ElementInternals.ariaLabel: Ein String, der das aria-label-Attribut widerspiegelt, welches einen Stringwert definiert, der das aktuelle Objekt beschriftet.
ElementInternals.ariaLevel: Ein String, der das aria-level-Attribut widerspiegelt, welches die hierarchische Ebene eines Elements innerhalb einer Struktur definiert.
ElementInternals.ariaLive: Ein String, der das aria-live-Attribut widerspiegelt, welches angibt, dass ein Element aktualisiert wird und die Arten der Updates beschreibt, die die Benutzeragenten, unterstützende Technologien und Benutzer von dem Live-Bereich erwarten können.
ElementInternals.ariaModal: Ein String, der das aria-modal-Attribut widerspiegelt, welches angibt, ob ein Element beim Anzeigen modal ist.
ElementInternals.ariaMultiline: Ein String, der das aria-multiline-Attribut widerspiegelt, welches angibt, ob ein Textfeld mehrere Zeilen Eingaben akzeptiert oder nur eine einzelne Zeile.
ElementInternals.ariaMultiSelectable: Ein String, der das aria-multiselectable-Attribut widerspiegelt, welches angibt, dass der Benutzer mehr als ein Element aus den aktuellen auswählbaren Nachfahren auswählen kann.
ElementInternals.ariaOrientation: Ein String, der das aria-orientation-Attribut widerspiegelt, welches angibt, ob die Ausrichtung des Elements horizontal, vertikal oder unbekannt/mehrdeutig ist.
ElementInternals.ariaPlaceholder: Ein String, der das aria-placeholder-Attribut widerspiegelt, welches einen kurzen Hinweis definiert, der dem Benutzer bei der Dateneingabe hilft, wenn das Steuerelement keinen Wert hat.
ElementInternals.ariaPosInSet: Ein String, der das aria-posinset-Attribut widerspiegelt, welches die Nummer oder Position eines Elements im aktuellen Satz von Listenelementen oder Baumelementen definiert.
ElementInternals.ariaPressed: Ein String, der das aria-pressed-Attribut widerspiegelt, welches den aktuellen "gedrückten" Zustand von Schaltflächen mit Umschaltung angibt.
ElementInternals.ariaReadOnly: Ein String, der das aria-readonly-Attribut widerspiegelt, welches angibt, dass das Element nicht bearbeitbar, aber anderweitig bedienbar ist.
ElementInternals.ariaRelevant Nicht standardisiert: Ein String, der das aria-relevant-Attribut widerspiegelt, welches angibt, welche Benachrichtigungen der Benutzeragent auslösen wird, wenn der Zugänglichkeitsbaum innerhalb eines Live-Bereichs geändert wird. Dies wird verwendet, um zu beschreiben, welche Änderungen in einem aria-live-Bereich relevant sind und angekündigt werden sollten.
ElementInternals.ariaRequired: Ein String, der das aria-required-Attribut widerspiegelt, welches angibt, dass eine Benutzereingabe auf dem Element erforderlich ist, bevor ein Formular übermittelt werden kann.
ElementInternals.role: Ein String, der eine ARIA-Rolle enthält. Eine vollständige Liste der ARIA-Rollen finden Sie auf der ARIA-Techniken-Seite.
ElementInternals.ariaRoleDescription: Ein String, der das aria-roledescription-Attribut widerspiegelt, welches eine menschenlesbare, vom Autor lokalisierte Beschreibung für die Rolle eines Elements definiert.
ElementInternals.ariaRowCount: Ein String, der das aria-rowcount-Attribut widerspiegelt, welches die Gesamtanzahl der Zeilen in einer Tabelle, einem Raster oder einem Baumraster definiert.
ElementInternals.ariaRowIndex: Ein String, der das aria-rowindex-Attribut widerspiegelt, welches den Zeilenindex oder die Position eines Elements im Verhältnis zur Gesamtanzahl der Zeilen innerhalb einer Tabelle, eines Rasters oder eines Baumrasters definiert.
ElementInternals.ariaRowIndexText: Ein String, der das aria-rowindextext-Attribut widerspiegelt, welches eine menschenlesbare Textalternative zu aria-rowindex definiert.
ElementInternals.ariaRowSpan: Ein String, der das aria-rowspan-Attribut widerspiegelt, welches die Anzahl der von einer Zelle oder Rasterzelle innerhalb einer Tabelle, eines Rasters oder eines Baumrasters überspannten Zeilen definiert.
ElementInternals.ariaSelected: Ein String, der das aria-selected-Attribut widerspiegelt, welches den aktuellen "ausgewählten" Zustand von Elementen angibt, die einen ausgewählten Zustand haben.
ElementInternals.ariaSetSize: Ein String, der das aria-setsize-Attribut widerspiegelt, welches die Anzahl der Elemente im aktuellen Satz von Listenelementen oder Baumelementen definiert.
ElementInternals.ariaSort: Ein String, der das aria-sort-Attribut widerspiegelt, welches angibt, ob Elemente in einer Tabelle oder einem Raster in aufsteigender oder absteigender Reihenfolge sortiert werden.
ElementInternals.ariaValueMax: Ein String, der das aria-valueMax-Attribut widerspiegelt, welches den maximal zulässigen Wert für ein Bereichs-Widget definiert.
ElementInternals.ariaValueMin: Ein String, der das aria-valueMin-Attribut widerspiegelt, welches den minimal zulässigen Wert für ein Bereichs-Widget definiert.
ElementInternals.ariaValueNow: Ein String, der das aria-valueNow-Attribut widerspiegelt, welches den aktuellen Wert für ein Bereichs-Widget definiert.
ElementInternals.ariaValueText: Ein String, der das aria-valuetext-Attribut widerspiegelt, welches die menschenlesbare Textalternative zu aria-valuenow für ein Bereichs-Widget definiert.

Instanzeigenschaften, die von ARIA-Elementreferenzen widergespiegelt werden

Die Eigenschaften spiegeln die in den entsprechenden Attributen durch id-Referenz angegebenen Elemente wider, jedoch mit einigen Vorbehalten. Weitere Informationen finden Sie unter Reflektierte Elementreferenzen im Leitfaden für reflektierte Attribute.

ElementInternals.ariaActiveDescendantElement: Ein Element, das das aktuelle aktive Element darstellt, wenn der Fokus auf einem kompositiv Widget, einem Kombinationsfeld, einem Textfeld, einer Gruppe oder einer Anwendung liegt. Reflektiert das aria-activedescendant-Attribut.
ElementInternals.ariaControlsElements: Ein Array von Elementen, deren Inhalt oder Vorhandensein durch das angewendete Element kontrolliert wird. Reflektiert das aria-controls-Attribut.
ElementInternals.ariaDescribedByElements: Ein Array von Elementen, die die zugängliche Beschreibung für das angewendete Element enthalten. Reflektiert das aria-describedby-Attribut.
ElementInternals.ariaDetailsElements: Ein Array von Elementen, die zugängliche Details für das angewendete Element bereitstellen. Reflektiert das aria-details-Attribut.
ElementInternals.ariaErrorMessageElements: Ein Array von Elementen, die eine Fehlermeldung für das angewendete Element bereitstellen. Reflektiert das aria-errormessage-Attribut.
ElementInternals.ariaFlowToElements: Ein Array von Elementen, die das nächste Element (oder die nächsten Elemente) in einer alternativen Lesereihenfolge von Inhalten identifizieren, die die allgemeine Standardlesereihenfolge nach Ermessen des Benutzers überschreibt. Reflektiert das aria-flowto-Attribut.
ElementInternals.ariaLabelledByElements: Ein Array von Elementen, die den zugänglichen Namen für das angewendete Element bereitstellen. Reflektiert das aria-labelledby-Attribut.
ElementInternals.ariaOwnsElements: Ein Array von Elementen, die von dem Element, auf das dies angewendet wird, besessen werden. Dies wird verwendet, um eine visuelle, funktionale oder kontextuelle Beziehung zwischen einem Elternteil und seinen Kindelementen zu definieren, wenn die DOM-Hierarchie nicht verwendet werden kann, um die Beziehung darzustellen. Reflektiert das aria-owns-Attribut.

Instanz-Methoden

ElementInternals.setFormValue(): Legt den Übermittlungswert und Zustand des Elements fest und überträgt diese Informationen an den Benutzeragenten.
ElementInternals.setValidity(): Legt die Gültigkeit des Elements fest.
ElementInternals.checkValidity(): Überprüft, ob ein Element einer der darauf angewendeten Einschränkungsvalidierungs-Regeln entspricht.
ElementInternals.reportValidity(): Überprüft, ob ein Element einer der darauf angewendeten Einschränkungsvalidierungs-Regeln entspricht und sendet auch eine Validierungsnachricht an den Benutzeragenten.

Beispiele

Das folgende Beispiel zeigt, wie ein benutzerdefiniertes, formularassoziiertes Element mit HTMLElement.attachInternals erstellt wird.

class CustomCheckbox extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals_ = this.attachInternals();
  }

  // …
}

window.customElements.define("custom-checkbox", CustomCheckbox);

let element = document.createElement("custom-checkbox");
let form = document.createElement("form");

// Append element to form to associate it
form.appendChild(element);

console.log(element.internals_.form);
// expected output: <form><custom-checkbox></custom-checkbox></form>

Spezifikationen

Specification
HTML # the-elementinternals-interface

Browser-Kompatibilität

Siehe auch

Fähigere Formularelemente über web.dev (2019)
Erstellen von benutzerdefinierten Formularelementen mit ElementInternals über CSS-tricks (2021)