HTMLInputElement.stepDown() — Methode · JavaScript-Referenz

Signatur

HTMLInputElement.prototype.stepDown(stepDecrement)

Beschreibung

stepDown() verringert den Wert eines <input>-Elements programmatisch um das step-Attribut multipliziert mit stepDecrement. Das funktioniert bei den Typen number, range, date, month, week, time und datetime-local. Ohne step-Attribut gilt der Standardschritt des jeweiligen Typs, zum Beispiel 1 bei number, 1 Tag bei date und 60 Sekunden bei time.

Die Methode ist praktisch für eigene Minus-Schaltflächen, Tastenkürzel oder Mengenwähler in Warenkörben. Sie beachtet min, max und step: Würde der neue Wert min unterschreiten, wird er auf den kleinsten erlaubten Wert gesetzt, der zum Schrittraster passt. Liegt der aktuelle Wert nicht auf dem Raster, rundet der Browser ihn zuerst auf den nächsten gültigen Schritt in Zielrichtung.

Wichtig: Wenn Sie den Wert mit stepDown() ändern, lösen Browser keine input- oder change-Events aus. Wenn andere Teile der Anwendung auf solche Events hören, müssen Sie das Event selbst mit dispatchEvent() auslösen.

Parameter

Name	Typ	Default	Beschreibung
$stepDecrement	number	1	Faktor, mit dem der Wert von `step` multipliziert wird. Negative Werte erhöhen den Wert, wie bei `stepUp()`. Nachkommastellen werden abgeschnitten.

Rückgabewert

Typ

void

Beschreibung

Gibt nichts zurück (undefined). Der geänderte Wert steht danach in value bzw. valueAsNumber.

Beispiele

Minus-Schaltfläche für einen Mengenwähler

// HTML: <input type="number" id="menge" value="5" min="1" max="10">
//       <button id="minus">−</button>
const menge = document.querySelector('#menge');
document.querySelector('#minus').addEventListener('click', () => {
  menge.stepDown();
  // stepDown() löst kein Event aus, deshalb manuell auslösen
  menge.dispatchEvent(new Event('input', { bubbles: true }));
  console.log(menge.value);
});

4

Um mehrere Schritte verringern und min beachten

const input = document.createElement('input');
input.type = 'number';
input.step = '5';
input.min = '0';
input.value = '20';

input.stepDown(3);   // 20 - 3 * 5
console.log(input.value);

input.stepDown(10);  // würde unter min fallen, also wird auf min gesetzt
console.log(input.value);

5 0

Datum um eine Woche zurücksetzen

const datum = document.createElement('input');
datum.type = 'date';
datum.value = '2024-03-15';

// Standardschritt bei date = 1 Tag
datum.stepDown(7);
console.log(datum.value);

2024-03-08

Nicht unterstützten Typ abfangen

const text = document.createElement('input');
text.type = 'text';

try {
  text.stepDown();
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Ausnahme: Bei nicht unterstützten Typen wie text, checkbox oder email wirft die Methode einen InvalidStateError (DOMException). Dasselbe gilt bei step="any", weil es dann kein Schrittraster gibt.
Keine Events: input und change werden nicht ausgelöst. Frameworks wie React oder Vue merken die Änderung daher erst, wenn Sie das Event selbst auslösen.
Leerer Wert: Ist value leer, rechnet der Browser mit 0 bzw. mit dem Standard-Startwert des Typs. Das Ergebnis wird dann an min/max angepasst.
Grenzen: Liegt der aktuelle Wert schon unter min, ändert stepDown() nichts. Heute setzen moderne Browser den Wert an die Grenze, statt einen Fehler zu werfen (ältere Spezifikationen haben hier noch einen Fehler verlangt).
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Bei week und month fehlt die Unterstützung in Firefox und Safari teilweise, weil sie diese Eingabetypen dort nicht vollständig anbieten.

Siehe auch

HTMLInputElement.stepUp() HTMLInputElement.valueAsNumber HTMLInputElement.valueAsDate HTMLInputElement.step HTMLInputElement EventTarget.dispatchEvent() HTMLOutputElement.reportValidity()