Element.ariaMultiLine — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaMultiLine

Beschreibung

Die Eigenschaft ariaMultiLine gehört zum ARIAMixin, den Element einbindet. Sie spiegelt das Inhaltsattribut aria-multiline wider: Beim Lesen erhalten Sie den aktuellen Attributwert als String, beim Schreiben wird das Attribut gesetzt. Mit null wird es entfernt.

Gültige Werte sind "true" (das Textfeld nimmt mehrere Zeilen an) und "false" (nur eine Zeile, Standard). Screenreader nutzen diese Angabe zum Beispiel, um anzukündigen, dass die Enter-Taste einen Zeilenumbruch erzeugt und das Formular nicht absendet.

Sinnvoll ist die Eigenschaft vor allem bei eigenen Eingabe-Widgets, etwa einem <div contenteditable> mit role="textbox", zum Beispiel in Rich-Text-Editoren, Chat-Eingabefeldern oder Code-Editoren. Native Elemente wie <textarea> (mehrzeilig) und <input type="text"> (einzeilig) geben diese Information bereits von sich aus weiter und brauchen das Attribut nicht.

Rückgabewert

Typ

string | null

Beschreibung

"true" oder "false", wenn das Attribut gesetzt ist, sonst null. Der Wert ist immer ein String und nie ein boolescher Wert.

Beispiele

Wert lesen und ändern

// HTML: <div id="editor" role="textbox" contenteditable="true" aria-multiline="false"></div>
const editor = document.getElementById('editor');

console.log(editor.ariaMultiLine);

editor.ariaMultiLine = 'true';
console.log(editor.getAttribute('aria-multiline'));

false true

Eigenes Textfeld für den Chat mit passendem Enter-Verhalten

const input = document.createElement('div');
input.contentEditable = 'true';
input.role = 'textbox';
input.ariaLabel = 'Nachricht';
input.ariaMultiLine = 'true';
document.body.append(input);

input.addEventListener('keydown', (event) => {
  // Bei mehrzeiligen Feldern sendet nur Strg+Enter, Enter erzeugt einen Umbruch
  const multiline = input.ariaMultiLine === 'true';
  if (event.key === 'Enter' && (!multiline || event.ctrlKey)) {
    event.preventDefault();
    console.log('Senden:', input.textContent);
    input.textContent = '';
  }
});

Modus umschalten und Attribut entfernen

const field = document.querySelector('[role="textbox"]');

const setMultiline = (enabled) => {
  field.ariaMultiLine = enabled ? 'true' : 'false';
};

setMultiline(true);
console.log(field.ariaMultiLine);

// Attribut vollständig entfernen
field.ariaMultiLine = null;
console.log(field.hasAttribute('aria-multiline'), field.ariaMultiLine);

true false null

// Wichtig · Fallstricke

String statt boolescher Wert: Der Ausdruck el.ariaMultiLine = false setzt den String "false". Eine Abfrage wie if (el.ariaMultiLine) ist deshalb auch bei "false" wahr. Vergleichen Sie immer ausdrücklich mit === 'true'.
Nur eine Semantik: Das Attribut ändert nicht das Verhalten des Elements. Das Enter-Verhalten, Zeilenumbrüche und das Absenden müssen Sie selbst per JavaScript umsetzen, und zwar passend zum angegebenen Wert.
Native Elemente bevorzugen: Verwenden Sie wenn möglich <textarea> oder <input>. Das Attribut ist nur bei Elementen mit role="textbox" (oder searchbox) sinnvoll.
Kompatibilität: Firefox unterstützt die gespiegelten ARIA-Eigenschaften erst ab Version 119. Für ältere Browser bleibt setAttribute('aria-multiline', 'true') die sichere Lösung, die überall funktioniert.

Siehe auch

Element.role Element.ariaAutoComplete Element.ariaMultiSelectable Element.ariaLive Element.ariaSetSize