ElementInternals.ariaPlaceholder — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaPlaceholder

Beschreibung

Die Eigenschaft ariaPlaceholder des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-placeholder. Sie enthält einen kurzen Hinweis, zum Beispiel ein Beispielwert oder eine Formatbeschreibung. Assistive Technologien wie Screenreader lesen ihn vor, solange ein Eingabefeld leer ist.

Gedacht ist sie für autonome Custom Elements, die sich wie Eingabefelder verhalten, etwa ein eigenes <my-textbox> mit role="textbox" oder role="searchbox". Über this.attachInternals() legt die Komponente ihre Standard-Semantik fest, ohne Attribute auf dem Host-Element zu setzen. Das DOM bleibt dadurch sauber. Setzt der Nutzer der Komponente selbst ein aria-placeholder-Attribut, hat dieses Vorrang vor dem Wert aus ElementInternals.

Der Wert ist eine beliebige Zeichenkette oder null. Mit null wird der Standardwert entfernt. Der ARIA-Platzhalter ist nur ein Hinweis für die Barrierefreiheit: Er zeigt keinen sichtbaren Text an. Den sichtbaren Platzhalter muss die Komponente selbst darstellen, etwa im Shadow DOM.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: der Hinweistext, z. B. `"TT.MM.JJJJ"`. Mit `null` wird der Standardwert entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell über ElementInternals gesetzte Platzhalterhinweis, oder null, wenn keiner gesetzt ist. Ein Attribut aria-placeholder auf dem Host-Element wird hier nicht zurückgegeben.

Beispiele

Eigenes Textfeld mit Standard-Platzhalterhinweis

class MyTextbox extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'textbox';
    this.#internals.ariaPlaceholder = 'z. B. max@example.com';

    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = '<span part="hint">z. B. max@example.com</span>';
    this.tabIndex = 0;
  }

  get placeholderHint() {
    return this.#internals.ariaPlaceholder;
  }
}

customElements.define('my-textbox', MyTextbox);

const box = document.createElement('my-textbox');
document.body.append(box);
console.log(box.placeholderHint);
console.log(box.hasAttribute('aria-placeholder'));

z. B. max@example.com false

Hinweis aus einem Attribut übernehmen und wieder entfernen

class DateField extends HTMLElement {
  static observedAttributes = ['format'];
  #internals = this.attachInternals();

  connectedCallback() {
    this.#internals.role = 'textbox';
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'format') {
      // null entfernt den Standardhinweis
      this.#internals.ariaPlaceholder = newValue ?? null;
      console.log('Hinweis:', this.#internals.ariaPlaceholder);
    }
  }
}

customElements.define('date-field', DateField);

const field = document.createElement('date-field');
field.setAttribute('format', 'TT.MM.JJJJ');
field.removeAttribute('format');

Hinweis: TT.MM.JJJJ Hinweis: null

Unterstützung prüfen und auf ein Attribut ausweichen

class SearchBox extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals();
    internals.role = 'searchbox';

    if ('ariaPlaceholder' in internals) {
      internals.ariaPlaceholder = 'Artikel durchsuchen …';
    } else {
      // Ausweichlösung für ältere Browser
      this.setAttribute('role', 'searchbox');
      this.setAttribute('aria-placeholder', 'Artikel durchsuchen …');
    }
  }
}

customElements.define('search-box', SearchBox);

// Wichtig · Fallstricke

Vorrang: Ein vom Nutzer gesetztes aria-placeholder-Attribut am Host-Element überschreibt den Wert aus ElementInternals. Das ist so gewollt: Die Komponente liefert nur Standardwerte.
Nicht sichtbar: ariaPlaceholder zeigt keinen Text an. Die Komponente muss den sichtbaren Platzhalter selbst darstellen und ihn ausblenden, sobald ein Wert eingegeben ist. Den ARIA-Hinweis sollte sie dann ebenfalls entfernen oder anpassen.
Kein Ersatz für ein Label: Laut WAI-ARIA ersetzt ein Platzhalter keine zugängliche Beschriftung. Zusätzlich ariaLabel, ariaLabelledByElements oder ein <label> (bei formularassoziierten Elementen) verwenden.
Passende Rolle nötig: aria-placeholder gilt nur für die Rollen textbox und searchbox. Ohne passende role ignorieren Screenreader den Wert.
Nur für autonome Custom Elements: attachInternals() wirft bei eingebauten Elementen und bei angepassten eingebauten Elementen (is="…") eine NotSupportedError-Ausnahme. Außerdem lässt es sich pro Element nur einmal aufrufen.
Browser-Unterstützung: Die ARIA-Eigenschaften von ElementInternals gibt es in Firefox erst ab Version 119. Für ältere Browser mit 'ariaPlaceholder' in internals prüfen, ob die Eigenschaft vorhanden ist.

Siehe auch

ElementInternals.ariaLabel ElementInternals.ariaChecked ElementInternals.ariaColIndex ElementInternals.ariaHidden ElementInternals.ariaLevel