Stepper 步进器 ​

介绍 ​

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

引入 ​

通过以下方式来引入组件。

js
import { createApp } from 'vue';
import { Stepper } from '@szhn/dh-design-mobile';

const app = createApp();
app.use(Stepper);

代码演示 ​

基础用法 ​

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

html
<van-stepper v-model="value" />
js
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    return { value };
  },
};

步长设置 ​

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

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

限制输入范围 ​

通过 min 和 max 属性限制输入值的范围，默认超出范围后会自动校正最大值或最小值，通过 auto-fixed 可以关闭自动校正。

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

限制输入整数 ​

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

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

禁用状态 ​

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

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

禁用输入框 ​

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

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

固定小数位数 ​

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

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

自定义大小 ​

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

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

异步变更 ​

通过 before-change 属性可以在输入值变化前进行校验和拦截。

html
<van-stepper v-model="value" :before-change="beforeChange" />
js
import { ref } from 'vue';
import { closeToast, showLoadingToast } from '@szhn/dh-design-mobile';

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 来展示圆角风格的步进器。

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

API ​

Props ​

参数说明类型默认值
v-model当前输入的值number | string-
min最小值number | string1
max最大值number | string-
auto-fixed是否自动校正超出限制范围的数值，设置为 false 后输入超过限制范围的数值将不会自动校正booleantrue
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样式风格，可选值为 roundstring-
placeholder输入框占位提示文字string-
integer是否只允许输入整数booleanfalse
disabled是否禁用步进器booleanfalse
disable-plus是否禁用增加按钮booleanfalse
disable-minus是否禁用减少按钮booleanfalse
disable-input是否禁用输入框booleanfalse
before-change输入值变化前的回调函数，返回 false 可阻止输入，支持返回 Promise(value: number | string) => boolean | Promise<boolean>false
show-plus是否显示增加按钮booleantrue
show-minus是否显示减少按钮booleantrue
show-input是否显示输入框booleantrue
long-press是否开启长按手势，开启后可以长按增加和减少按钮booleantrue
allow-empty是否允许输入的值为空，设置为 true 后允许传入空字符串booleanfalse

Events ​

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

类型定义 ​

组件导出以下类型定义：

ts
import type { StepperTheme, StepperProps } from '@szhn/dh-design-mobile';

主题定制 ​

样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称默认值描述
--van-stepper-backgroundvar(--van-active-color)步进器的背景色
--van-stepper-button-icon-colorvar(--van-text-color)按钮图标的颜色
--van-stepper-button-disabled-colorvar(--van-background)禁用状态下按钮的颜色
--van-stepper-button-disabled-icon-colorvar(--van-gray-5)禁用状态下按钮图标的颜色
--van-stepper-button-round-theme-colorvar(--van-primary-color)圆角主题下按钮的颜色
--van-stepper-input-width32px输入框的宽度
--van-stepper-input-height28px输入框的高度
--van-stepper-input-font-sizevar(--van-font-size-md)输入框的字体大小
--van-stepper-input-line-heightnormal输入框的行高
--van-stepper-input-text-colorvar(--van-text-color)输入框的文字颜色
--van-stepper-input-disabled-text-colorvar(--van-text-color-3)禁用状态下输入框的文字颜色
--van-stepper-input-disabled-backgroundvar(--van-active-color)禁用状态下输入框的背景色
--van-stepper-radiusvar(--van-radius-md)步进器的圆角大小

常见问题 ​

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

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

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

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