步进器由增加按钮、减少按钮和输入框组成,用于在一定范围内输入、调整数字。
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
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 属性限制输入值的范围。
<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 { Toast } from 'vant';
export default {
setup() {
const value = ref(1);
const beforeChange = (value) => {
Toast.loading({ forbidClick: true });
return new Promise((resolve) => {
setTimeout(() => {
Toast.clear();
// 在 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 |
|
max | 最大值 | number | string | - |
default-value | 初始值,当 v-model 为空时生效 | number | string |
|
step | 步长,每次点击时改变的值 | number | string |
|
name | 标识符,可以在 change 事件回调参数中获取 | number | string | - |
input-width | 输入框宽度,默认单位为 | number | string |
|
button-size | 按钮大小以及输入框高度,默认单位为 | number | string |
|
decimal-length | 固定显示的小数位数 | number | string | - |
theme | 样式风格,可选值为 | string | - |
placeholder | 输入框占位提示文字 | string | - |
integer | 是否只允许输入整数 | boolean |
|
disabled | 是否禁用步进器 | boolean |
|
disable-plus | 是否禁用增加按钮 | boolean |
|
disable-minus | 是否禁用减少按钮 | boolean |
|
disable-input | 是否禁用输入框 | boolean |
|
before-change | 输入值变化前的回调函数,返回 false 可阻止输入,支持返回 Promise | (value: number | string) => boolean | Promise<boolean> |
|
show-plus | 是否显示增加按钮 | boolean |
|
show-minus | 是否显示减少按钮 | boolean |
|
show-input | 是否显示输入框 | boolean |
|
long-press | 是否开启长按手势 | boolean |
|
allow-empty | 是否允许输入的值为空 | boolean |
|
事件名 | 说明 | 回调参数 |
---|---|---|
change | 当绑定值变化时触发的事件 | value: string, detail: { name: string } |
overlimit | 点击不可用的按钮时触发 | - |
plus | 点击增加按钮时触发 | - |
minus | 点击减少按钮时触发 | - |
focus | 输入框聚焦时触发 | event: Event |
blur | 输入框失焦时触发 | event: Event |
组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件。
名称 | 默认值 | 描述 |
---|---|---|
--van-stepper-active-color | #e8e8e8 | - |
--van-stepper-background-color | var(--van-active-color) | - |
--van-stepper-button-icon-color | var(--van-text-color) | - |
--van-stepper-button-disabled-color | var(--van-background-color) | - |
--van-stepper-button-disabled-icon-color | var(--van-gray-5) | - |
--van-stepper-button-round-theme-color | var(--van-danger-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-gray-5) | - |
--van-stepper-input-disabled-background-color | var(--van-active-color) | - |
--van-stepper-border-radius | var(--van-border-radius-md) | - |
这是因为用户输入过程中可能出现小数点或空值,比如 1.,这种情况下组件会抛出字符串类型。
如果希望 value 保持 number 类型,可以在 v-model 上添加 number 修饰符:
<van-stepper v-model.number="value" />