Signatur
Beschreibung
Die Eigenschaft ariaValueNow gehört zum ARIA-Reflection-Mechanismus des Element-Interfaces. Sie liest und schreibt direkt das HTML-Attribut aria-valuenow. Damit teilen Sie assistiven Technologien wie Screenreadern mit, welchen Wert ein Bereichs-Widget gerade hat, zum Beispiel ein Element mit role="slider", role="progressbar", role="spinbutton", role="scrollbar" oder role="meter".
Sie brauchen die Eigenschaft vor allem bei selbstgebauten Widgets, bei denen kein natives Element wie <input type="range">, <progress> oder <meter> infrage kommt. Ändert sich der Wert durch Tastatur, Maus oder einen Hintergrundprozess, sollten Sie ariaValueNow jedes Mal mitaktualisieren. Nur dann meldet der Screenreader den neuen Stand.
Wichtig: Der Wert ist immer ein String und kein number, obwohl er eine Dezimalzahl darstellen soll. Er sollte zwischen aria-valuemin und aria-valuemax liegen. Ist der Wert für Menschen schwer verständlich, zum Beispiel eine Zahl, die für einen Wochentag steht, ergänzen Sie ihn mit aria-valuetext (ariaValueText). Bei einem unbestimmten Fortschrittsbalken lassen Sie aria-valuenow ganz weg.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | null | null | Wird beim Schreiben zugewiesen. Ein String, der eine Dezimalzahl darstellt, z. B. "42" oder "3.5". Mit null wird das Attribut aria-valuenow entfernt. |
Rückgabewert
aria-valuenow als String. Fehlt das Attribut, ist der Wert null.Beispiele
Wert lesen und setzen
// HTML: <div id="volume" role="slider" aria-valuemin="0" aria-valuemax="100" aria-valuenow="30" tabindex="0"></div>
const slider = document.getElementById('volume');
console.log(slider.ariaValueNow); // "30"
console.log(typeof slider.ariaValueNow); // "string"
slider.ariaValueNow = '55';
console.log(slider.getAttribute('aria-valuenow'));Eigener Slider mit Tastatursteuerung
const slider = document.querySelector('[role="slider"]');
const min = Number(slider.ariaValueMin ?? 0);
const max = Number(slider.ariaValueMax ?? 100);
const setValue = (v) => {
const clamped = Math.min(max, Math.max(min, v));
slider.ariaValueNow = String(clamped);
slider.ariaValueText = `${clamped} Prozent`;
slider.style.setProperty('--pos', `${clamped}%`);
};
slider.addEventListener('keydown', (e) => {
const current = Number(slider.ariaValueNow ?? min);
if (e.key === 'ArrowRight' || e.key === 'ArrowUp') setValue(current + 1);
if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') setValue(current - 1);
if (e.key === 'Home') setValue(min);
if (e.key === 'End') setValue(max);
});Fortschrittsbalken beim Upload aktualisieren
const bar = document.querySelector('#upload-progress'); // role="progressbar"
const upload = (file) => new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest();
xhr.upload.addEventListener('progress', (e) => {
if (e.lengthComputable) {
bar.ariaValueNow = String(Math.round((e.loaded / e.total) * 100));
} else {
bar.ariaValueNow = null; // unbestimmter Zustand: Attribut entfernen
}
});
xhr.addEventListener('load', () => resolve(xhr.status));
xhr.addEventListener('error', reject);
xhr.open('POST', '/upload');
xhr.send(file);
});// Wichtig · Fallstricke
- String statt Zahl: Für Berechnungen müssen Sie den Wert mit
Number()umwandeln. Wenn Sie beim Schreiben eine Zahl zuweisen, wird sie automatisch in einen String umgewandelt. - Keine Prüfung: Der Browser kontrolliert nicht, ob der Wert zwischen
aria-valueminundaria-valuemaxliegt. Die Begrenzung müssen Sie selbst umsetzen. - Native Elemente bevorzugen:
<input type="range">,<progress>und<meter>geben ihren Wert automatisch an assistive Technologien weiter. Wenn Sie dort zusätzlicharia-valuenowsetzen, kann das dem nativen Wert widersprechen. - Kompatibilität: Firefox unterstützt ARIA-Reflection erst ab Version 119. Für ältere Browser verwenden Sie
setAttribute('aria-valuenow', …), denn das funktioniert überall. - Ist der Zahlenwert für Menschen nicht aussagekräftig, setzen Sie zusätzlich
ariaValueText, zum Beispiel „Schritt 2 von 5“.