Element.ariaValueMax — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaValueMax

Beschreibung

Die Eigenschaft ariaValueMax der Schnittstelle Element ist eine reflektierte Eigenschaft des Attributs aria-valuemax. Liest man sie, erhält man den aktuellen Attributwert als String. Schreibt man sie, wird das Attribut im DOM gesetzt oder aktualisiert. Assistive Technologien wie Screenreader nutzen den Wert, um Nutzern den Wertebereich eines Widgets anzusagen, etwa „50 von 100“.

Gebraucht wird die Eigenschaft bei eigenen Bereichs-Widgets mit den Rollen slider, scrollbar, spinbutton, progressbar, meter oder separator (wenn fokussierbar). Zusammen mit ariaValueMin, ariaValueNow und gegebenenfalls ariaValueText beschreibt sie den Zustand des Widgets vollständig. Native Elemente wie <input type="range"> oder <progress> liefern diese Werte bereits von selbst über ihre Attribute max/min/value.

Der Wert sollte als Dezimalzahl interpretierbar sein und größer oder gleich aria-valuemin sein. Da die Eigenschaft immer mit Strings arbeitet, muss man zum Rechnen selbst mit Number() oder parseFloat() umwandeln.

Rückgabewert

Typ

string | null

Beschreibung

Der Wert des Attributs aria-valuemax als String, oder null, wenn das Attribut nicht gesetzt ist. Setzt man null, wird das Attribut entfernt.

Beispiele

Maximalwert eines Sliders auslesen

// HTML: <div id="volume" role="slider" tabindex="0"
//        aria-valuemin="0" aria-valuemax="100" aria-valuenow="40"></div>
const slider = document.getElementById('volume');

console.log(slider.ariaValueMax);          // String
console.log(typeof slider.ariaValueMax);
console.log(Number(slider.ariaValueMax) - Number(slider.ariaValueNow));

100 string 60

Eigenen Slider mit Tastatursteuerung und Begrenzung

const slider = document.getElementById('volume');
slider.role = 'slider';
slider.ariaValueMin = '0';
slider.ariaValueMax = '10';
slider.ariaValueNow = '5';

slider.addEventListener('keydown', (event) => {
  const min = Number(slider.ariaValueMin);
  const max = Number(slider.ariaValueMax);
  let value = Number(slider.ariaValueNow);

  if (event.key === 'ArrowRight' || event.key === 'ArrowUp') value++;
  else if (event.key === 'ArrowLeft' || event.key === 'ArrowDown') value--;
  else if (event.key === 'End') value = max;
  else if (event.key === 'Home') value = min;
  else return;

  event.preventDefault();
  // Wert auf den erlaubten Bereich begrenzen
  slider.ariaValueNow = String(Math.min(max, Math.max(min, value)));
  console.log(`${slider.ariaValueNow} von ${slider.ariaValueMax}`);
});

6 von 10 (nach Drücken von Pfeil rechts)

Fortschrittsbalken mit dynamischem Maximum

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

const startUpload = (totalBytes) => {
  bar.ariaValueMin = '0';
  bar.ariaValueMax = String(totalBytes);
  bar.ariaValueNow = '0';
};

const updateUpload = (loadedBytes) => {
  bar.ariaValueNow = String(loadedBytes);
  const percent = Math.round((loadedBytes / Number(bar.ariaValueMax)) * 100);
  bar.ariaValueText = `${percent} Prozent hochgeladen`;
  console.log(bar.getAttribute('aria-valuemax'), bar.ariaValueText);
};

startUpload(2048);
updateUpload(512);

2048 25 Prozent hochgeladen

Attribut entfernen und Fallback

const meter = document.querySelector('[role="meter"]');
meter.ariaValueMax = null; // entfernt aria-valuemax

console.log(meter.hasAttribute('aria-valuemax'));
// Für role="meter"/"slider" gilt dann implizit 100
const max = Number(meter.ariaValueMax ?? 100);
console.log(max);

false 100

// Wichtig · Fallstricke

Immer ein String: Auch beim Setzen einer Zahl wird der Wert in einen String umgewandelt. Vor Vergleichen oder Rechnungen mit Number() umwandeln, sonst gilt z. B. "9" > "10" als true.
Keine Validierung: Der Browser prüft nicht, ob der Wert numerisch ist oder über aria-valuemin liegt. Ungültige Werte führen zu falschen Ansagen durch Screenreader.
Implizite Standardwerte: Bei slider, scrollbar, meter und separator gilt ohne Attribut implizit 100. Bei spinbutton gibt es keinen Standard, dann gilt der Bereich als unbegrenzt. Die Eigenschaft selbst liefert in diesen Fällen trotzdem null.
Native Elemente bevorzugen: Bei <input type="range">, <progress> und <meter> stattdessen das Attribut max nutzen. Ein zusätzliches aria-valuemax ist überflüssig und kann Widersprüche erzeugen.
Kompatibilität: Firefox unterstützt die ARIA-Reflexion erst ab Version 119. Für ältere Browser setAttribute('aria-valuemax', …) bzw. getAttribute() verwenden, das funktioniert überall.
Die Eigenschaft ist auch über ElementInternals.ariaValueMax für benutzerdefinierte Elemente (Custom Elements) verfügbar. Damit lässt sich ein Standardwert setzen, ohne ein sichtbares Attribut anzulegen.

Siehe auch

Element.ariaValueMin Element.ariaValueNow Element.ariaValueText Element.role Element.setAttribute() ElementInternals ElementInternals.ariaModal