Signatur
Beschreibung
Die Eigenschaft ariaMultiLine der Schnittstelle ElementInternals entspricht dem ARIA-Attribut aria-multiline. Damit kann ein Custom Element Hilfstechnologien wie Screenreadern mitteilen, ob es sich um ein einzeiliges oder ein mehrzeiliges Textfeld handelt. Sinnvoll ist das vor allem bei Elementen mit der Rolle textbox (oder searchbox), z. B. bei eigenen Editoren auf Basis von contenteditable.
Anders als Element.ariaMultiLine schreibt die Eigenschaft auf ElementInternals kein sichtbares Attribut in das DOM. Sie legt stattdessen die Standardsemantik des Elements fest. Setzt eine Seitenautorin am Host-Element selbst aria-multiline, hat dieser Wert Vorrang. So kann eine Komponente sinnvolle Vorgaben liefern, die sich trotzdem von außen überschreiben lassen.
Der Wert ist ein String: "true" bedeutet mehrzeilige Eingabe (Enter fügt einen Zeilenumbruch ein), "false" bedeutet einzeilige Eingabe (Enter sendet z. B. ein Formular ab). Mit null wird die Vorgabe entfernt. Das Objekt ElementInternals bekommt man in der Klasse des Custom Elements über this.attachInternals().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | null | null | Wert beim Setzen: "true" (mehrzeilig), "false" (einzeilig) oder null, um die Vorgabe zu entfernen. |
Rückgabewert
"true" oder "false") oder null, wenn nichts gesetzt ist. Ein aria-multiline-Attribut am Host-Element fließt nicht in diesen Wert ein.Beispiele
Mehrzeiliges Custom-Textfeld mit Standardsemantik
class RichEditor extends HTMLElement {
#internals;
constructor() {
super();
this.#internals = this.attachInternals();
this.#internals.role = 'textbox';
this.#internals.ariaMultiLine = 'true';
this.contentEditable = 'true';
}
get multiLine() {
return this.#internals.ariaMultiLine;
}
}
customElements.define('rich-editor', RichEditor);
const editor = document.createElement('rich-editor');
document.body.append(editor);
console.log(editor.multiLine);
console.log(editor.hasAttribute('aria-multiline'));Zwischen einzeilig und mehrzeilig über ein Attribut umschalten
class SmartInput extends HTMLElement {
static observedAttributes = ['multiline'];
#internals = this.attachInternals();
connectedCallback() {
this.#internals.role = 'textbox';
this.contentEditable = 'true';
this.#update();
this.addEventListener('keydown', (e) => {
// Einzeilig: Enter verhindern und stattdessen ein Ereignis auslösen
if (e.key === 'Enter' && this.#internals.ariaMultiLine === 'false') {
e.preventDefault();
this.dispatchEvent(new CustomEvent('submit-line', { bubbles: true }));
}
});
}
attributeChangedCallback() {
this.#update();
}
#update() {
this.#internals.ariaMultiLine = this.hasAttribute('multiline') ? 'true' : 'false';
}
}
customElements.define('smart-input', SmartInput);
const field = document.createElement('smart-input');
document.body.append(field);
field.setAttribute('multiline', '');
field.removeAttribute('multiline');Vorgabe entfernen und Unterstützung prüfen
class PlainBox extends HTMLElement {
internals = this.attachInternals();
}
customElements.define('plain-box', PlainBox);
const box = new PlainBox();
if ('ariaMultiLine' in ElementInternals.prototype) {
box.internals.ariaMultiLine = 'false';
console.log(box.internals.ariaMultiLine);
box.internals.ariaMultiLine = null;
console.log(box.internals.ariaMultiLine);
} else {
console.log('ARIA-Spiegelung auf ElementInternals wird nicht unterstützt');
}// Wichtig · Fallstricke
- Kein DOM-Attribut: Das Setzen erzeugt kein
aria-multiline-Attribut am Host.getAttribute('aria-multiline')liefert also weiterhinnull. Ein Attribut, das von außen gesetzt wird, überschreibt die Vorgabe ausElementInternals. - Nur semantisch:
ariaMultiLineverändert kein Verhalten. Dass Enter einen Zeilenumbruch einfügt oder eben nicht, muss die Komponente selbst umsetzen. Sonst hören Screenreader-Nutzer etwas anderes, als tatsächlich passiert. - Passende Rolle nötig: Der Wert ist nur bei einer passenden Rolle wie
textboxsinnvoll. Die Rolle setzt man z. B. überinternals.role. - Werte sind Strings: Übergib
\"true\"oder\"false\", keine booleschen Werte.truewird zwar in\"true\"umgewandelt, sollte aber aus Gründen der Lesbarkeit vermieden werden. - Kompatibilität:
attachInternals()funktioniert nur bei autonomen Custom Elements. Die Spiegelung der ARIA-Attribute aufElementInternalsgibt es erst in neueren Browsern (Firefox ab Version 119, Safari ab 16.4). Für ältere Browser prüfst du die Unterstützung mit'ariaMultiLine' in ElementInternals.prototypeund setzt ersatzweise das Attribut.