Stepper 步进器

介绍

步进器由增加按钮、减少按钮和输入框组成,用于在一定范围内输入、调整数字。

引入

  1. import Vue from 'vue';
  2. import { Stepper } from 'vant';
  3. Vue.use(Stepper);

代码演示

基础用法

通过 v-model 绑定输入值,可以通过 change 事件监听到输入值的变化。

  1. <van-stepper v-model="value" />
  1. export default {
  2. data() {
  3. return {
  4. value: 1,
  5. };
  6. },
  7. };

步长设置

通过 step 属性设置每次点击增加或减少按钮时变化的值,默认为 1

  1. <van-stepper v-model="value" step="2" />

限制输入范围

通过 minmax 属性限制输入值的范围。

  1. <van-stepper v-model="value" min="5" max="8" />

限制输入整数

设置 integer 属性后,输入框将限制只能输入整数。

  1. <van-stepper v-model="value" integer />

禁用状态

通过设置 disabled 属性来禁用步进器,禁用状态下无法点击按钮或修改输入框。

  1. <van-stepper v-model="value" disabled />

禁用输入框

通过设置 disable-input 属性来禁用输入框,此时按钮仍然可以点击。

  1. <van-stepper v-model="value" disable-input />

固定小数位数

通过设置 decimal-length 属性可以保留固定的小数位数。

  1. <van-stepper v-model="value" step="0.2" :decimal-length="1" />

自定义大小

通过 input-width 属性设置输入框宽度,通过 button-size 属性设置按钮大小和输入框高度。

  1. <van-stepper v-model="value" input-width="40px" button-size="32px" />

异步变更

如果需要异步地修改输入框的值,可以设置 async-change 属性,并在 change 事件中手动修改 value

  1. <van-stepper :value="value" async-change @change="onChange" />
  1. import { Toast } from 'vant';
  2. export default {
  3. data() {
  4. return {
  5. value: 1,
  6. };
  7. },
  8. methods: {
  9. onChange(value) {
  10. Toast.loading({ forbidClick: true });
  11. clearTimeout(this.timer);
  12. this.timer = setTimeout(() => {
  13. Toast.clear();
  14. // 注意此时修改 value 后会再次触发 change 事件
  15. this.value = value;
  16. }, 500);
  17. },
  18. },
  19. };

圆角风格

theme 设置为 round 来展示圆角风格的步进器。

  1. <van-stepper v-model="value" theme="round" button-size="22" disable-input />

API

Props

参数说明类型默认值
v-model当前输入的值number | string-
min最小值number | string1
max最大值number | string-
default-value初始值,当 v-model 为空时生效number | string1
step步长,每次点击时改变的值number | string1
name标识符,可以在change事件回调参数中获取number | string-
input-width输入框宽度,默认单位为pxnumber | string32px
button-size按钮大小以及输入框高度,默认单位为pxnumber | string28px
decimal-length固定显示的小数位数number | string-
theme v2.8.2样式风格,可选值为 roundstring-
placeholder v2.8.6输入框占位提示文字string-
integer是否只允许输入整数booleanfalse
disabled是否禁用步进器booleanfalse
disable-plus是否禁用增加按钮booleanfalse
disable-minus是否禁用减少按钮booleanfalse
disable-input是否禁用输入框booleanfalse
async-change是否开启异步变更,开启后需要手动控制输入值booleanfalse
show-plus是否显示增加按钮booleantrue
show-minus是否显示减少按钮booleantrue
show-input v2.12.1是否显示输入框booleantrue
long-press是否开启长按手势booleantrue
allow-empty v2.9.1是否允许输入的值为空booleanfalse

Events

事件名说明回调参数
change当绑定值变化时触发的事件value: string, detail: { name: string }
overlimit点击不可用的按钮时触发-
plus点击增加按钮时触发-
minus点击减少按钮时触发-
focus输入框聚焦时触发event: Event
blur输入框失焦时触发event: Event

样式变量

组件提供了下列 Less 变量,可用于自定义样式,使用方法请参考主题定制

名称默认值描述
@stepper-active-color#e8e8e8-
@stepper-background-color@active-color-
@stepper-button-icon-color@text-color-
@stepper-button-disabled-color@background-color-
@stepper-button-disabled-icon-color@gray-5-
@stepper-button-round-theme-color@red-
@stepper-input-width32px-
@stepper-input-height28px-
@stepper-input-font-size@font-size-md-
@stepper-input-line-heightnormal-
@stepper-input-text-color@text-color-
@stepper-input-disabled-text-color@gray-5-
@stepper-input-disabled-background-color@active-color-
@stepper-border-radius@border-radius-md-

常见问题

为什么 value 有时候会变成 string 类型?

这是因为用户输入过程中可能出现小数点或空值,比如 1.,这种情况下组件会抛出字符串类型。

如果希望 value 保持 number 类型,可以在 v-model 上添加 number 修饰符:

  1. <van-stepper v-model.number="value" />

Stepper 步进器 - 图1