ElementInternals.ariaValueMin — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaValueMin

Beschreibung

Die Eigenschaft ariaValueMin der Schnittstelle ElementInternals gehört zum sogenannten ARIA-Reflection-Mechanismus für Custom Elements. Sie legt die Standard-Semantik für aria-valuemin fest, also den kleinsten zulässigen Wert von Bereichs-Widgets wie slider, spinbutton, progressbar, meter oder scrollbar.

Anders als Element.ariaValueMin schreibt die Variante auf ElementInternals kein Attribut in das DOM. Der Wert gilt nur intern für den Barrierefreiheitsbaum. Setzt der Nutzer der Komponente selbst ein aria-valuemin-Attribut, hat dieses Vorrang. So kann eine Komponente sinnvolle Standardwerte mitbringen, ohne das Markup ihrer Nutzer zu überschreiben.

Der Wert ist ein String, der eine Dezimalzahl darstellt, z. B. "0" oder "-10.5". Mit null wird der Standardwert entfernt. Man verwendet die Eigenschaft typischerweise im Konstruktor oder in attributeChangedCallback eines Custom Elements, zusammen mit ariaValueMax, ariaValueNow und passender role.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: String mit einer Dezimalzahl als Minimalwert. `null` entfernt den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell gesetzte Standard-Minimalwert als String oder null, wenn keiner gesetzt ist. Ein vom Nutzer gesetztes aria-valuemin-Attribut wird hier nicht zurückgegeben.

Beispiele

Eigener Slider mit Standardwerten

class RangeSlider extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    // Standard-Semantik festlegen, ohne DOM-Attribute zu setzen
    this.#internals.role = 'slider';
    this.#internals.ariaValueMin = '0';
    this.#internals.ariaValueMax = '100';
    this.#internals.ariaValueNow = '50';
  }

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

customElements.define('range-slider', RangeSlider);

const slider = document.createElement('range-slider');
document.body.append(slider);
console.log(slider.internals.ariaValueMin);
console.log(slider.hasAttribute('aria-valuemin'));

0 false

Minimalwert aus Attribut synchronisieren

class TemperatureSpinner extends HTMLElement {
  static observedAttributes = ['min'];
  #internals = this.attachInternals();

  constructor() {
    super();
    this.#internals.role = 'spinbutton';
    this.#internals.ariaValueMin = '-20';
  }

  attributeChangedCallback(name, _oldValue, newValue) {
    if (name === 'min') {
      const min = Number.parseFloat(newValue);
      // Ungültige Werte entfernen den Standard
      this.#internals.ariaValueMin = Number.isFinite(min) ? String(min) : null;
      console.log('ariaValueMin:', this.#internals.ariaValueMin);
    }
  }
}

customElements.define('temperature-spinner', TemperatureSpinner);

const spinner = document.createElement('temperature-spinner');
spinner.setAttribute('min', '-40');
spinner.setAttribute('min', 'abc');

ariaValueMin: -40 ariaValueMin: null

Nutzer-Attribut hat Vorrang

// Angenommen <range-slider> aus Beispiel 1 ist definiert
const el = document.createElement('range-slider');
el.setAttribute('aria-valuemin', '10');
document.body.append(el);

// Internals-Wert bleibt unverändert, Screenreader nutzen aber 10
console.log(el.internals.ariaValueMin);
console.log(el.ariaValueMin);

0 10

// Wichtig · Fallstricke

Nur für autonome Custom Elements: attachInternals() wirft einen NotSupportedError bei eingebauten Elementen und bei angepassten eingebauten Elementen (is="…"). Außerdem darf es pro Element nur einmal aufgerufen werden.
String statt Zahl: Zahlen werden beim Setzen in Strings umgewandelt. Es findet keine Prüfung statt. Ungültige Werte wie "abc" werden gespeichert, aber von Hilfstechnologien ignoriert. Prüfen Sie Werte deshalb selbst.
Konsistenz: ariaValueMin sollte kleiner oder gleich ariaValueMax sein, und ariaValueNow sollte dazwischen liegen. Ohne passende role (z. B. slider) hat der Wert keine Wirkung.
Keine Tastaturlogik: Die Eigenschaft beschreibt nur die Semantik. Tastaturbedienung (Pfeiltasten, Pos1/Ende) und Fokus (tabindex) müssen Sie selbst umsetzen.
Kompatibilität: Firefox unterstützt ARIA-Reflection auf ElementInternals erst ab Version 119. Für ältere Browser prüfen Sie die Unterstützung mit 'ariaValueMin' in ElementInternals.prototype und setzen als Rückfall das Attribut direkt.

Siehe auch

ElementInternals.ariaValueMax ElementInternals.ariaValueNow ElementInternals.ariaValueText ElementInternals.ariaAtomic ElementInternals.ariaColSpan