HTMLInputElement: stepDown() 方法

可用性有限

此特性不是基线特性,因为它在一些最广泛使用的浏览器中不起作用。

HTMLInputElement.stepDown() 方法会根据 step 属性的值,将数字类型的 <input> 元素的值减去该值。如果传递了一个数字作为参数,则会减去该数字乘以 step 属性值的倍数。

当调用该方法时,它会将 value 减去 (step * n),其中 n 在未指定时默认为 1,step 在未指定时默认为 step 的默认值。

该方法适用于所有支持 step 属性的数字、日期和时间输入类型,包括 datemonthweektimedatetime-localnumberrange

给定 <input id="myTime" type="time" max="17:00" step="900" value="17:00">,调用 myTime.stepDown(3) 会将值更改为 16:15,即减去 3 * 900(45 分钟)。而调用 myTime.stepDown()(不带参数)则会得到 16:45,因为 n 默认为 1

html
<!-- decrements by intervals of 900 seconds (15 minute) -->
<input type="time" max="17:00" step="900" />

<!-- decrements by intervals of 7 days (one week) -->
<input type="date" max="2019-12-25" step="7" />

<!-- decrements by intervals of 12 months (one year) -->
<input type="month" max="2019-12" step="12" />

然而,在 <input type="time" max="17:00" step="900"> 上调用 stepDown 不会将值设置为 17:00,正如人们所期望的那样——对于 stepUp 在输入为 <input type="time" min="17:00" step="900"> 时是这样的。相反,第一次调用 stepDown 会将初始值设置为 23:45,即使设置了 max 属性。第二次调用会将值设置为 17:00。第三次调用会将值设置为 16:45

js
let input1 = document.createElement("input");
input1.setAttribute("type", "time");
input1.setAttribute("min", "17:00");
input1.setAttribute("step", 900);
console.log(input1.value); // ""
input1.stepUp();
console.log(input1.value); // "17:00"
// However
let input2 = document.createElement("input");
input2.setAttribute("type", "time");
input2.setAttribute("max", "17:00");
input2.setAttribute("step", 900);
console.log(input2.value); // ""
input2.stepDown();
console.log(input2.value); // "23:45"
input2.stepDown();
console.log(input2.value); // "17:00"
input2.stepDown();
console.log(input2.value); // "16:45"

当调用该方法时,它会根据 step 属性的值乘以参数的值来更改表单控件的值,并在表单控件设定的约束范围内。如果未传递参数,则参数的默认值为 1。该方法不会导致值低于设定的 min 值,也不会违反 step 属性设定的约束。n 的负值将递增值,但不会超过 max 值。

如果调用 stepDown() 方法之前的值无效,例如,如果不符合 step 属性设定的约束,调用 stepDown() 方法将返回一个符合表单控件约束的值。

如果表单控件不是时间、日期或数字类型的,因此不支持 step 属性(请参阅上面支持的输入类型列表),或者 step 的值设置为 any,则会抛出 InvalidStateError 异常。

语法

js
stepDown()
stepDown(stepDecrement)

参数

stepDecrement 可选

一个数字值。如果未传递参数,stepDecrement 默认为 1。

如果值为浮点数,则该值将像传递了 Math.floor(stepDecrement) 一样递减。如果值为负数,则该值将递增而不是递减。

返回值

无(undefined)。

异常

InvalidStateError DOMException

在以下情况之一中抛出

  • 如果该方法不适用于当前 type 值,
  • 如果元素没有 step 值,
  • 如果 value 无法转换为数字,
  • 如果结果值大于 max 或小于 min

示例

点击此示例中的按钮可减少 number 输入类型的值

HTML

html
<p>
  <label for="theNumber">
    Enter a number between 0 and 400 that is divisible by 5:
  </label>
  <input type="number" step="5" id="theNumber" min="0" max="400" />
</p>
<p>
  <label for="decrementButton">
    Enter how many values of step you would like to decrement by or leave it
    blank:
  </label>
  <input type="number" step="1" id="decrementInput" min="-2" max="15" />
</p>
<input type="button" value="Decrement" id="theButton" />

JavaScript

js
/* make the button call the function */
let button = document.getElementById("theButton");
button.addEventListener("click", () => {
  stepOnDown();
});

function stepOnDown() {
  let input = document.getElementById("theNumber");
  let val = document.getElementById("decrementInput").value;

  if (val) {
    // decrement with a parameter
    input.stepDown(val);
  } else {
    // or without a parameter. Try it with 0, 5, -2, etc.
    input.stepDown();
  }
}

CSS

css
input:invalid {
  border: red solid 3px;
}

结果

注意,如果您不向 stepDown() 方法传递参数,它默认为 1。任何其他值都是 step 属性值(在本例中为 5)的乘数。如果我们传递 4 作为 stepDecrement,则输入将按 4 * 5,即 20 进行 stepDown。如果参数为 0,则数字不会递减。stepDown() 方法不会让输入超出范围,在这种情况下,它会在达到 0 时停止,并将传递为参数的浮点数向下取整。

尝试将步长递减输入设置为 1.2。调用该方法会发生什么?

尝试将值设置为 44,这是无效的。调用该方法会发生什么?

规范

规范
HTML
# dom-input-stepdown-dev

浏览器兼容性

另见