步进器由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、调整数字。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';
import { Stepper } from 'vant';
const app = createApp();
app.use(Stepper); 通过 v-model 绑定输入值，可以通过 change 事件监听到输入值的变化。
<van-stepper v-model="value" />
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return { value };
},
}; 通过 step 属性设置每次点击增加或减少按钮时变化的值，默认为 1。
<van-stepper v-model="value" step="2" />
通过 min 和 max 属性限制输入值的范围，默认超出范围后会自动校正最大值或最小值，通过 auto-fixed 可以关闭自动校正。
<van-stepper v-model="value" min="5" max="8" />
设置 integer 属性后，输入框将限制只能输入整数。
<van-stepper v-model="value" integer />
通过设置 disabled 属性来禁用步进器，禁用状态下无法点击按钮或修改输入框。
<van-stepper v-model="value" disabled />
通过设置 disable-input 属性来禁用输入框，此时按钮仍然可以点击。
<van-stepper v-model="value" disable-input />
通过设置 decimal-length 属性可以保留固定的小数位数。
<van-stepper v-model="value" step="0.2" :decimal-length="1" />
通过 input-width 属性设置输入框宽度，通过 button-size 属性设置按钮大小和输入框高度。
<van-stepper v-model="value" input-width="40px" button-size="32px" />
通过 before-change 属性可以在输入值变化前进行校验和拦截。
<van-stepper v-model="value" :before-change="beforeChange" />
import { ref } from 'vue';
import { closeToast, showLoadingToast } from 'vant';
export default {
setup() {
const value = ref(1);
const beforeChange = (value) => {
showLoadingToast({ forbidClick: true });
return new Promise((resolve) => {
setTimeout(() => {
closeToast();
// 在 resolve 函数中返回 true 或 false
resolve(true);
}, 500);
});
};
return {
value,
beforeChange,
};
},
}; 将 theme 设置为 round 来展示圆角风格的步进器。
<van-stepper v-model="value" theme="round" button-size="22" disable-input />
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前输入的值 | number | string | - |
| min | 最小值 | number | string | 1 |
| max | 最大值 | number | string | - |
| auto-fixed | 是否自动校正超出限制范围的数值，设置为 false后输入超过限制范围的数值将不会自动校正 | boolean | true |
| default-value | 初始值，当 v-model 为空时生效 | number | string | 1 |
| step | 步长，每次点击时改变的值 | number | string | 1 |
| name | 标识符，通常为一个唯一的字符串或数字，可以在 change事件回调参数中获取 | number | string | - |
| input-width | 输入框宽度，默认单位为 px | number | string | 32px |
| button-size | 按钮大小以及输入框高度，默认单位为 px | number | string | 28px |
| decimal-length | 固定显示的小数位数 | number | string | - |
| theme | 样式风格，可选值为 round | string | - |
| placeholder | 输入框占位提示文字 | string | - |
| integer | 是否只允许输入整数 | boolean | false |
| disabled | 是否禁用步进器 | boolean | false |
| disable-plus | 是否禁用增加按钮 | boolean | false |
| disable-minus | 是否禁用减少按钮 | boolean | false |
| disable-input | 是否禁用输入框 | boolean | false |
| before-change | 输入值变化前的回调函数，返回 false可阻止输入，支持返回 Promise | (value: number | string) => boolean | Promise<boolean> | false |
| show-plus | 是否显示增加按钮 | boolean | true |
| show-minus | 是否显示减少按钮 | boolean | true |
| show-input | 是否显示输入框 | boolean | true |
| long-press | 是否开启长按手势，开启后可以长按增加和减少按钮 | boolean | true |
| allow-empty | 是否允许输入的值为空，设置为 true后允许传入空字符串 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | value: string, detail: { name: string } |
| overlimit | 点击不可用的按钮时触发 | - |
| plus | 点击增加按钮时触发 | - |
| minus | 点击减少按钮时触发 | - |
| focus | 输入框聚焦时触发 | event: Event |
| blur | 输入框失焦时触发 | event: Event |
组件导出以下类型定义：
import type { StepperTheme, StepperProps } from 'vant'; 组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-stepper-background | var(--van-active-color) | - |
| --van-stepper-button-icon-color | var(--van-text-color) | - |
| --van-stepper-button-disabled-color | var(--van-background) | - |
| --van-stepper-button-disabled-icon-color | var(--van-gray-5) | - |
| --van-stepper-button-round-theme-color | var(--van-primary-color) | - |
| --van-stepper-input-width | 32px | - |
| --van-stepper-input-height | 28px | - |
| --van-stepper-input-font-size | var(--van-font-size-md) | - |
| --van-stepper-input-line-height | normal | - |
| --van-stepper-input-text-color | var(--van-text-color) | - |
| --van-stepper-input-disabled-text-color | var(--van-text-color-3) | - |
| --van-stepper-input-disabled-background | var(--van-active-color) | - |
| --van-stepper-radius | var(--van-radius-md) | - |
这是因为用户输入过程中可能出现小数点或空值，比如 1.，这种情况下组件会抛出字符串类型。
如果希望 value 保持 number 类型，可以在 v-model 上添加 number 修饰符：
<van-stepper v-model.number="value" />