ElementInternals.ariaValueMax — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaValueMax

Beschreibung

Mit ElementInternals.ariaValueMax legt ein benutzerdefiniertes Element (Custom Element) den größten zulässigen Wert für Bereichs-Widgets fest, zum Beispiel für die Rollen slider, spinbutton, progressbar, scrollbar oder meter. Hilfstechnologien wie Screenreader lesen diesen Wert zusammen mit ariaValueMin und ariaValueNow vor, etwa als „50 von 100“.

Anders als Element.ariaValueMax schreibt diese Eigenschaft kein sichtbares aria-valuemax-Attribut in das DOM. Sie legt stattdessen die Standard-Semantik des Elements im Barrierefreiheitsbaum fest. So bleibt das Markup der Komponente sauber, und Nutzer der Komponente können den Wert bei Bedarf mit einem eigenen Attribut am Host-Element überschreiben.

Der Wert ist eine Zeichenkette, die eine Dezimalzahl darstellt (z. B. "100" oder "1.5"). Mit null entfernen Sie den Standardwert. Das ElementInternals-Objekt erhalten Sie in der Klasse des Elements über this.attachInternals(). Meist geschieht das im Konstruktor.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: der größte zulässige Wert als Zeichenkette mit einer Dezimalzahl. `null` entfernt den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell über ElementInternals gesetzte Standardwert für aria-valuemax oder null, wenn keiner gesetzt ist.

Beispiele

Barrierefreien Schieberegler als Custom Element definieren

class RatingSlider extends HTMLElement {
  #internals;

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

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

customElements.define('rating-slider', RatingSlider);

const slider = document.createElement('rating-slider');
document.body.append(slider);

console.log(slider.internals.ariaValueMax);
// Kein Attribut im DOM sichtbar:
console.log(slider.getAttribute('aria-valuemax'));

10 null

Maximum mit einem beobachteten max-Attribut abgleichen

class ProgressRing extends HTMLElement {
  static observedAttributes = ['max', 'value'];
  #internals = this.attachInternals();

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

  attributeChangedCallback(name, _oldValue, newValue) {
    if (name === 'max') {
      const max = Number.parseFloat(newValue);
      // Nur gültige Zahlen übernehmen, sonst Standard 100
      this.#internals.ariaValueMax = Number.isFinite(max) ? String(max) : '100';
    }
    if (name === 'value') {
      this.#internals.ariaValueNow = newValue;
    }
    console.log(`max=${this.#internals.ariaValueMax}, now=${this.#internals.ariaValueNow}`);
  }
}

customElements.define('progress-ring', ProgressRing);

const ring = document.createElement('progress-ring');
ring.setAttribute('max', '250');
ring.setAttribute('value', '125');

max=250, now=null max=250, now=125

Standardwert am Host-Element überschreiben

class VolumeKnob extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals();
    internals.role = 'slider';
    internals.ariaValueMin = '0';
    internals.ariaValueMax = '11';
  }
}

customElements.define('volume-knob', VolumeKnob);

const knob = document.createElement('volume-knob');
// Das Attribut hat Vorrang vor dem Standardwert aus ElementInternals
knob.setAttribute('aria-valuemax', '20');
document.body.append(knob);

console.log(knob.ariaValueMax); // Element.ariaValueMax spiegelt das Attribut

20

// Wichtig · Fallstricke

Kein Attribut im DOM: Der Wert erscheint weder in getAttribute('aria-valuemax') noch in element.ariaValueMax. Prüfen Sie ihn in den Barrierefreiheits-Werkzeugen der Entwicklertools.
Vorrang: Ein am Host gesetztes aria-valuemax-Attribut überschreibt immer den Standardwert aus ElementInternals.
Nur Zeichenketten: Zahlen werden in Zeichenketten umgewandelt. Ungültige Werte wie "abc" werden nicht geprüft, Hilfstechnologien ignorieren sie aber.
Stimmige Werte: ariaValueMax sollte größer oder gleich ariaValueMin sein. Ist der Wert unbekannt (z. B. bei einem unbestimmten Fortschritt), setzen Sie ihn nicht.
Passende Rolle nötig: Ohne eine Rolle wie slider oder progressbar hat der Wert keine Wirkung.
attachInternals() nur einmal: Ein zweiter Aufruf wirft eine NotSupportedError-DOMException. Das gilt auch für integrierte, erweiterte Elemente (is="…").
Kompatibilität: Die ARIA-Spiegelung in ElementInternals gibt es in Chromium seit Version 81, in Safari seit 16.4 und in Firefox seit 119. Bei älteren Browsern können Sie auf setAttribute('aria-valuemax', …) am Host zurückgreifen.

Siehe auch

ElementInternals.ariaValueMin ElementInternals.ariaValueNow ElementInternals.ariaValueText ElementInternals.ariaAtomic ElementInternals.ariaColIndex