ElementInternals.ariaReadOnly — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaReadOnly

Beschreibung

Die Eigenschaft ariaReadOnly des ElementInternals-Interfaces entspricht dem ARIA-Zustand aria-readonly. Sie zeigt assistiven Technologien wie Screenreadern an, dass ein Element nicht bearbeitet, aber weiterhin bedient werden kann: Es bleibt fokussierbar, man kann seinen Inhalt markieren und kopieren und darin navigieren.

Anders als Element.ariaReadOnly setzt die Variante auf ElementInternals kein Attribut im DOM. Sie legt die Standard-Semantik eines autonomen Custom Elements fest. Setzt jemand, der die Komponente verwendet, selbst ein aria-readonly-Attribut auf das Host-Element, hat dieses Vorrang. So können Web Components ihre Barrierefreiheitsinformationen kapseln, ohne das Light DOM zu verändern.

Sinnvoll ist die Eigenschaft vor allem bei eigenen Formular-Steuerelementen (formularassoziierte Custom Elements), deren Rolle aria-readonly unterstützt, etwa textbox, combobox, grid, gridcell, listbox, radiogroup, slider, spinbutton, checkbox oder switch. Mögliche Werte sind die Strings "true" und "false" sowie null (nicht gesetzt).

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"` (schreibgeschützt), `"false"` (bearbeitbar, Standardverhalten) oder `null`, um den Standardwert zu entfernen.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell gesetzte Standardwert als String ("true" oder "false") oder null, wenn nichts gesetzt wurde.

Beispiele

Schreibgeschütztes Custom-Textfeld

class ReadonlyField extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'textbox';
    this.#internals.ariaReadOnly = 'true';
    this.tabIndex = 0; // bleibt fokussierbar
  }
  connectedCallback() {
    this.textContent = 'Kundennummer: 4711';
    console.log(this.#internals.ariaReadOnly);
  }
}
customElements.define('readonly-field', ReadonlyField);
document.body.append(document.createElement('readonly-field'));

true

Schreibschutz über ein Attribut umschalten (formularassoziiert)

class EditableValue extends HTMLElement {
  static formAssociated = true;
  static observedAttributes = ['readonly'];
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'textbox';
    this.contentEditable = 'true';
  }
  attributeChangedCallback(name, _alt, neu) {
    const readOnly = neu !== null;
    this.contentEditable = readOnly ? 'false' : 'true';
    this.#internals.ariaReadOnly = readOnly ? 'true' : 'false';
    console.log('ariaReadOnly =', this.#internals.ariaReadOnly);
  }
}
customElements.define('editable-value', EditableValue);

const el = document.createElement('editable-value');
document.body.append(el);
el.setAttribute('readonly', '');
el.removeAttribute('readonly');

ariaReadOnly = true ariaReadOnly = false

Wert zurücksetzen und Vorrang des Host-Attributs

class ReadonlyGrid extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'grid';
    this.internals.ariaReadOnly = 'true';
  }
}
customElements.define('readonly-grid', ReadonlyGrid);

const grid = document.createElement('readonly-grid');
// Attribut des Verwenders überschreibt die Standard-Semantik
grid.setAttribute('aria-readonly', 'false');
console.log(grid.getAttribute('aria-readonly'), grid.internals.ariaReadOnly);

grid.internals.ariaReadOnly = null; // Standardwert entfernen
console.log(grid.internals.ariaReadOnly);

false true null

// Wichtig · Fallstricke

Nur Semantik, kein Verhalten: ariaReadOnly = "true" verhindert keine Eingaben. Die Bearbeitung musst du selbst unterbinden, z. B. mit contentEditable = "false" oder im Tastatur-Handler.
Nicht mit aria-disabled verwechseln: Schreibgeschützte Elemente bleiben fokussierbar und bedienbar. Nimm daher tabIndex nicht weg.
Strings statt Booleans: Der Wert ist ein String. ariaReadOnly = true wird zu "true" umgewandelt, false zu "false". Nur null entfernt den Wert.
Vorrang: Ein aria-readonly-Attribut am Host-Element überschreibt den Wert aus ElementInternals. In element.ariaReadOnly oder getAttribute() taucht der Internals-Wert nicht auf.
Passende Rolle nötig: Ohne eine Rolle, die aria-readonly unterstützt (z. B. textbox, grid), ignorieren assistive Technologien den Zustand.
Kompatibilität: ARIA-Reflexion auf ElementInternals gibt es erst in Firefox 119 und Safari 16.4. Für ältere Browser per 'ariaReadOnly' in ElementInternals.prototype prüfen und notfalls das Attribut am Host setzen.
attachInternals() darf pro Element nur einmal aufgerufen werden. Ein zweiter Aufruf wirft einen NotSupportedError.

Siehe auch

ElementInternals.ariaExpanded ElementInternals.ariaAtomic ElementInternals.ariaHidden ElementInternals.ariaLabel ElementInternals.ariaLevel