ElementInternals.ariaValueNow — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaValueNow

Beschreibung

Die Eigenschaft ariaValueNow gehört zum ARIA-Reflection-Teil von ElementInternals. Damit kann ein autonomes Custom Element seine Standard-Barrierefreiheitssemantik festlegen, ohne sichtbare Attribute am Host-Element zu setzen. Der Wert entspricht dem ARIA-Attribut aria-valuenow und gibt den aktuellen Zahlenwert eines Bereichs-Widgets an – etwa bei role="slider", "spinbutton", "progressbar", "meter" oder "scrollbar".

Man nutzt die Eigenschaft typischerweise zusammen mit internals.role, ariaValueMin, ariaValueMax und optional ariaValueText. Screenreader lesen dann z. B. „Lautstärke, Schieberegler, 40“ vor. Anders als ein per setAttribute() gesetztes Attribut bleibt dieser Wert im DOM unsichtbar und lässt sich vom Nutzer der Komponente überschreiben.

Der Wert ist ein String (bzw. null), obwohl er inhaltlich eine Zahl darstellt. Setzt man eine Zahl, wird sie zu einem String umgewandelt. Mit null entfernt man den Standardwert wieder.

Wichtig: Setzt der Anwender des Elements selbst ein aria-valuenow-Attribut am Host, hat dieses Vorrang vor dem Wert aus ElementInternals.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: der aktuelle Wert als Zeichenkette, die eine Dezimalzahl darstellt (z. B. `"42"` oder `"3.5"`). `null` entfernt den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell über ElementInternals gesetzte Standardwert für aria-valuenow oder null, falls keiner gesetzt ist. Ein Attribut am Host-Element wird dabei nicht gelesen.

Beispiele

Eigener Schieberegler mit Standardsemantik

class VolumeSlider extends HTMLElement {
  #internals;
  #value = 40;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'slider';
    this.#internals.ariaValueMin = '0';
    this.#internals.ariaValueMax = '100';
    this.#internals.ariaValueNow = String(this.#value);
    this.tabIndex = 0;
  }

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

customElements.define('volume-slider', VolumeSlider);

const slider = document.createElement('volume-slider');
document.body.append(slider);
console.log(slider.internals.ariaValueNow);
console.log(slider.getAttribute('aria-valuenow'));

"40" null

Wert per Tastatur ändern und synchron halten

class StepSlider extends HTMLElement {
  static observedAttributes = [];
  #internals = this.attachInternals();
  #value = 5;

  connectedCallback() {
    this.tabIndex = 0;
    this.#internals.role = 'slider';
    this.#internals.ariaValueMin = '0';
    this.#internals.ariaValueMax = '10';
    this.#update();
    this.addEventListener('keydown', (e) => {
      if (e.key === 'ArrowRight') this.#value = Math.min(10, this.#value + 1);
      if (e.key === 'ArrowLeft') this.#value = Math.max(0, this.#value - 1);
      this.#update();
    });
  }

  #update() {
    this.#internals.ariaValueNow = String(this.#value);
    this.#internals.ariaValueText = `${this.#value} von 10`;
    this.textContent = this.#value;
  }
}

customElements.define('step-slider', StepSlider);
document.body.append(document.createElement('step-slider'));

Fortschrittsanzeige mit Unterstützungsprüfung

class UploadProgress extends HTMLElement {
  #internals = this.attachInternals();

  connectedCallback() {
    this.#internals.role = 'progressbar';
    this.#internals.ariaValueMin = '0';
    this.#internals.ariaValueMax = '100';
  }

  set progress(percent) {
    if ('ariaValueNow' in this.#internals) {
      this.#internals.ariaValueNow = String(percent);
    } else {
      // Fallback für ältere Browser
      this.setAttribute('aria-valuenow', String(percent));
    }
    this.style.setProperty('--progress', `${percent}%`);
  }
}

customElements.define('upload-progress', UploadProgress);
const bar = document.createElement('upload-progress');
document.body.append(bar);
bar.progress = 75;

// Unbestimmter Zustand: Wert entfernen
bar.progress = 75;

// Wichtig · Fallstricke

Nur Standardwert: Ein vom Nutzer gesetztes aria-valuenow-Attribut am Host überschreibt den Wert aus ElementInternals. Der Getter liefert trotzdem nur den internen Wert.
Typ ist String: Zahlen werden umgewandelt; ariaValueNow = 5 ergibt "5". Beim Rechnen mit dem gelesenen Wert Number() verwenden.
Rolle nötig: Ohne passende Rolle (slider, spinbutton, progressbar, meter, scrollbar) wird der Wert von Hilfstechnologien meist ignoriert. Bei unbestimmtem Fortschritt (progressbar) den Wert mit null entfernen.
Der Wert sollte zwischen ariaValueMin und ariaValueMax liegen; bei nicht rein numerischer Anzeige zusätzlich ariaValueText setzen.
attachInternals() geht nur bei autonomen Custom Elements und nur einmal pro Element; ein zweiter Aufruf wirft einen NotSupportedError.
Kompatibilität: ARIA-Reflection auf ElementInternals gibt es in Chromium seit Version 90, in Safari seit 16.4 und in Firefox seit 119. Für ältere Browser per 'ariaValueNow' in internals prüfen und notfalls auf setAttribute() zurückgreifen.

Siehe auch

ElementInternals.ariaValueMax ElementInternals.ariaValueMin ElementInternals.ariaValueText ElementInternals.ariaCurrent ElementInternals.ariaHidden