Stepper 步进器 - Vant 4

Stepper 步进器

介绍

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

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { Stepper } from'vant'; const app = createApp(); app.use(Stepper);

🎯 代码演示

🔢 基础用法

通过 v-model 绑定输入值，可以通过 change 事件监听到输入值的变化，轻松实现数值的增减操作。

html

<template>
  <van-stepper v-model="value" @change="onChange" />
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    
    const onChange = (value) => {
      console.log('当前值：', value);
    };
    
    return {
      value,
      onChange,
    };
  },
};
</script>

📐 步长设置

通过 step 属性设置每次点击增加或减少按钮时变化的值，默认为 1，可以根据业务需求自定义步长。

html

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

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    
    return {
      value,
    };
  },
};
</script>

📊 限制输入范围

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

html

<template>
  <van-stepper v-model="value" min="5" max="40" />
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(10);
    
    return {
      value,
    };
  },
};
</script>

🔢 限制输入整数

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

html

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

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    
    return {
      value,
    };
  },
};
</script>

🚫 禁用状态

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

html

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

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    
    return {
      value,
    };
  },
};
</script>

🔒 禁用输入框

通过设置 disable-input 属性来禁用输入框，此时按钮仍然可以点击，适合只允许按钮操作的场景。

html

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

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    
    return {
      value,
    };
  },
};
</script>

📏 固定小数位数

通过设置 decimal-length 属性可以保留固定的小数位数，确保数值格式的一致性。

html

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

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1.0);
    
    return {
      value,
    };
  },
};
</script>

🎨 自定义大小

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

html

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

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    
    return {
      value,
    };
  },
};
</script>

⏳ 异步变更

通过 before-change 属性可以在输入值变化前进行校验和拦截，支持异步操作。

html

<template>
  <van-stepper v-model="value" :before-change="beforeChange" />
</template>

<script>
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,
    };
  },
};
</script>

🔘 圆角风格

将 theme 设置为 round 来展示圆角风格的步进器，提供更现代的视觉效果。

html

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

<script>
import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    
    return {
      value,
    };
  },
};
</script>

📋 API

🎛️ Props

参数	说明	类型	默认值
v-model	📊 当前输入的值	*number	string*
min	📉 最小值	*number	string*
max	📈 最大值	*number	string*
auto-fixed	🔧 是否自动校正超出限制范围的数值，设置为 `false` 后输入超过限制范围的数值将不会自动校正	boolean	`true`
default-value	🎯 初始值，当 v-model 为空时生效	*number	string*
step	📐 步长，每次点击时改变的值	*number	string*
name	🏷️ 标识符，通常为一个唯一的字符串或数字，可以在 `change` 事件回调参数中获取	*number	string*
input-width	📏 输入框宽度，默认单位为 `px`	*number	string*
button-size	📐 按钮大小以及输入框高度，默认单位为 `px`	*number	string*
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: string) => boolean	Promise<boolean>*
show-plus	👁️ 是否显示增加按钮	boolean	`true`
show-minus	👁️ 是否显示减少按钮	boolean	`true`
show-input	👁️ 是否显示输入框	boolean	`true`
long-press	👆 是否开启长按手势，开启后可以长按增加和减少按钮	boolean	`true`
allow-empty	🈳 是否允许输入的值为空，设置为 `true` 后允许传入空字符串	boolean	`false`

🎪 Events

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

📘 类型定义

组件导出以下类型定义，方便在 TypeScript 项目中使用：

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)	🔄 步进器圆角大小

常见问题

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

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

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

html

🔗 相关文档

📝 表单组件

Field 输入框 - 📝 用于数据录入的输入框组件
NumberKeyboard 数字键盘 - 🔢 虚拟数字键盘，常用于密码输入
Rate 评分 - ⭐ 用于对事物进行评级操作
Switch 开关 - 🔄 用于在打开和关闭状态之间进行切换

📊 展示组件

Progress 进度条 - 📊 用于展示操作的当前进度
Circle 环形进度条 - ⭕ 圆环形的进度条组件
CountDown 倒计时 - ⏰ 用于实时展示倒计时数值

💬 反馈组件

Toast 轻提示 - 💬 在页面中间弹出黑色半透明提示
Dialog 弹出框 - 📱 模态对话框，在浮层中显示，引导用户进行相关操作

🛠️ 工具组件

ConfigProvider 全局配置 - ⚙️ 用于全局配置 Vant 组件，提供深色模式、主题定制等能力

Stepper 步进器 ​

介绍 ​

引入 ​

🎯 代码演示 ​

🔢 基础用法 ​

📐 步长设置 ​

📊 限制输入范围 ​

🔢 限制输入整数 ​

🚫 禁用状态 ​

🔒 禁用输入框 ​

📏 固定小数位数 ​

🎨 自定义大小 ​

⏳ 异步变更 ​

🔘 圆角风格 ​

📋 API ​

🎛️ Props ​

🎪 Events ​

📘 类型定义 ​

🎨 主题定制 ​

🎭 样式变量 ​

常见问题 ​

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

🔗 相关文档 ​

📝 表单组件 ​

📊 展示组件 ​

💬 反馈组件 ​

🛠️ 工具组件 ​

Stepper 步进器

介绍

引入

🎯 代码演示

🔢 基础用法

📐 步长设置

📊 限制输入范围

🔢 限制输入整数

🚫 禁用状态

🔒 禁用输入框

📏 固定小数位数

🎨 自定义大小

⏳ 异步变更

🔘 圆角风格

📋 API

🎛️ Props

🎪 Events

📘 类型定义

🎨 主题定制

🎭 样式变量

常见问题

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

🔗 相关文档

📝 表单组件

📊 展示组件

💬 反馈组件

🛠️ 工具组件