Element.ariaValueText — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaValueText

Beschreibung

Die Eigenschaft ariaValueText gehört zur ARIA-Reflexion der Element-Schnittstelle. Sie liest und setzt das HTML-Attribut aria-valuetext direkt als String. Dafür braucht man weder getAttribute() noch setAttribute().

Das Attribut ist für Bereichs-Widgets gedacht, also Elemente mit den Rollen slider, spinbutton, progressbar, meter oder scrollbar. Deren aktueller Wert steht als Zahl in aria-valuenow. Ist diese Zahl für Menschen wenig aussagekräftig, liefert aria-valuetext einen verständlichen Text. Beispiele: Wochentage statt 1–7, „20 °C“ statt 20 oder „Schritt 2 von 5“. Screenreader lesen dann diesen Text vor und nicht die Zahl.

Gibt man in aria-valuetext nur die Zahl noch einmal an, bringt das nichts. Das Attribut lohnt sich nur, wenn es zusätzliche Informationen liefert, etwa eine Einheit oder einen Namen. aria-valuenow sollte trotzdem immer gesetzt und aktuell gehalten werden. Beide Werte müssen bei jeder Änderung gemeinsam aktualisiert werden.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert von aria-valuetext oder null, wenn das Attribut fehlt. Wird der Eigenschaft null zugewiesen, entfernt das Attribut.

Beispiele

Wert lesen und setzen

// HTML: <div id="temp" role="slider" aria-valuenow="20" aria-valuemin="10" aria-valuemax="30" aria-valuetext="20 Grad Celsius" tabindex="0"></div>
const slider = document.getElementById('temp');
console.log(slider.ariaValueText);

slider.ariaValueText = '21 Grad Celsius';
console.log(slider.getAttribute('aria-valuetext'));

20 Grad Celsius 21 Grad Celsius

Eigener Wochentags-Slider mit Tastatursteuerung

const tage = ['Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag', 'Sonntag'];
const slider = document.querySelector('#tag-slider');

const aktualisiere = (index) => {
  slider.ariaValueNow = String(index + 1);
  slider.ariaValueText = tage[index]; // Screenreader liest den Tagesnamen vor
  slider.textContent = tage[index];
};

let aktuell = 0;
aktualisiere(aktuell);

slider.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowRight') aktuell = Math.min(aktuell + 1, tage.length - 1);
  else if (e.key === 'ArrowLeft') aktuell = Math.max(aktuell - 1, 0);
  else return;
  e.preventDefault();
  aktualisiere(aktuell);
  console.log(slider.ariaValueNow, slider.ariaValueText);
});

2 Dienstag (nach einmal Pfeil nach rechts)

Fortschrittsanzeige mit Schritt-Text und Attribut entfernen

const bar = document.querySelector('[role="progressbar"]');
const schritte = 5;

const setzeSchritt = (n) => {
  bar.ariaValueNow = String(n);
  bar.ariaValueText = `Schritt ${n} von ${schritte}`;
};

setzeSchritt(2);
console.log(bar.ariaValueText);

// Attribut entfernen
bar.ariaValueText = null;
console.log(bar.hasAttribute('aria-valuetext'), bar.ariaValueText);

Schritt 2 von 5 false null

// Wichtig · Fallstricke

Browser-Unterstützung: Firefox unterstützt die ARIA-Reflexion erst ab Version 119. Wer ältere Browser unterstützen muss, verwendet stattdessen setAttribute('aria-valuetext', …). Die Feature-Erkennung geht mit 'ariaValueText' in Element.prototype.
Nicht bei nativen Elementen setzen: Bei <input type="range"> ist aria-valuetext zwar erlaubt. Bei <progress> und <meter> ermitteln Hilfstechnologien den Wert jedoch meist selbst.
Synchron halten: Ändert sich aria-valuenow, der Text aber nicht, bekommen Screenreader-Nutzer veraltete Informationen.
Der Wert ist immer ein String. Zahlen werden beim Zuweisen umgewandelt. null entfernt das Attribut, ein leerer String bleibt als leeres Attribut stehen.
Wie sich ein zugewiesenes undefined verhält, ist je nach Browser unterschiedlich. Zum Entfernen deshalb null oder removeAttribute() verwenden.

Siehe auch

Element.ariaValueNow Element.ariaValueMin Element.ariaValueMax Element.role Element.setAttribute() CSSUnparsedValue.length ElementInternals.ariaPressed