Element.ariaReadOnly — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaReadOnly

Beschreibung

Die Eigenschaft ariaReadOnly des Element-Interfaces spiegelt das ARIA-Attribut aria-readonly wider. Damit teilen Sie Hilfstechnologien wie Screenreadern mit, dass der Wert eines Elements nicht geändert werden kann. Das Element bleibt aber fokussierbar, sein Inhalt lässt sich lesen und markieren, und es kann weiter bedient werden, etwa durch Navigieren in einem Grid.

Das Attribut ist vor allem für eigene Widgets gedacht, die nicht auf nativen Formularelementen beruhen. Beispiele sind role="textbox", role="checkbox", role="combobox", role="grid", role="gridcell", role="slider" oder role="spinbutton". Bei nativen Elementen wie <input> und <textarea> verwenden Sie stattdessen das HTML-Attribut readonly. Der Browser gibt es automatisch an den Accessibility-Tree weiter.

Die Eigenschaft ist ein String und kein Boolean. Gültige Werte sind "true" und "false". Fehlt das Attribut, liefert der Getter null. Wenn Sie einen Wert zuweisen, wird das Attribut im DOM gesetzt. Wenn Sie null zuweisen, wird es entfernt.

Wichtig: aria-readonly ändert nur die Semantik des Elements. Das Verhalten bleibt gleich. Ihr Skript muss Eingaben selbst verhindern, zum Beispiel indem Tastatur-Handler nicht reagieren oder contenteditable entfernt wird.

Rückgabewert

Typ

string | null

Beschreibung

"true", wenn das Element schreibgeschützt ist, und "false", wenn es bearbeitbar ist (Standard). null bedeutet, dass das Attribut nicht gesetzt ist.

Beispiele

Wert lesen und setzen

// <div id="datum" role="textbox" aria-readonly="true">01.01.2024</div>
const feld = document.getElementById('datum');
console.log(feld.ariaReadOnly);

feld.ariaReadOnly = 'false';
console.log(feld.getAttribute('aria-readonly'));

true false

Schreibschutz für eigenes Textfeld umschalten

// <div id="notiz" role="textbox" contenteditable="true" tabindex="0">Text</div>
// <button id="sperren">Sperren</button>
const notiz = document.getElementById('notiz');
const button = document.getElementById('sperren');

const setReadOnly = (el, readOnly) => {
  el.ariaReadOnly = String(readOnly);   // Semantik für Screenreader
  el.contentEditable = String(!readOnly); // tatsächliches Verhalten
};

button.addEventListener('click', () => {
  const gesperrt = notiz.ariaReadOnly === 'true';
  setReadOnly(notiz, !gesperrt);
  button.textContent = gesperrt ? 'Sperren' : 'Entsperren';
  console.log('readonly:', notiz.ariaReadOnly);
});

readonly: true

Grid-Zellen schreibgeschützt markieren und Attribut entfernen

// <div role="grid"> ... <div role="gridcell" data-col="id">42</div> ... </div>
const zellen = document.querySelectorAll('[role="gridcell"][data-col="id"]');
zellen.forEach((zelle) => {
  zelle.ariaReadOnly = 'true'; // ID-Spalte ist nicht editierbar
});

// Attribut vollständig entfernen
const erste = zellen[0];
erste.ariaReadOnly = null;
console.log(erste.hasAttribute('aria-readonly'), erste.ariaReadOnly);

false null

// Wichtig · Fallstricke

String statt Boolean: el.ariaReadOnly = false wird zum String "false" umgewandelt. Prüfen Sie immer mit === 'true', denn if (el.ariaReadOnly) ist auch bei "false" wahr.
Nur Semantik: Das Attribut verhindert keine Eingaben. Ihr Skript muss Bearbeitung selbst unterbinden.
Nicht mit aria-disabled verwechseln: Ein schreibgeschütztes Element bleibt fokussierbar und lesbar. Ein deaktiviertes Element gilt dagegen als nicht bedienbar.
Native Elemente: Bei <input> und <textarea> setzen Sie besser readonly (el.readOnly = true). Widersprüchliche Angaben verwirren Hilfstechnologien.
Kompatibilität: Firefox unterstützt die ARIA-Reflexion erst ab Version 119. Wenn Sie ältere Browser unterstützen müssen, verwenden Sie setAttribute('aria-readonly', 'true'). Das funktioniert überall.

Siehe auch

Element.ariaHasPopup Element.ariaRequired Element.ariaAtomic Element.ariaHidden Element.ariaLabel