Vant Stepper 步进器组件完全指南API 详解、交互原理与实战应用【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant导读Stepper步进器是移动端表单场景中使用频率极高的组件它由增加按钮、减少按钮和输入框三部分组成用于在限定范围内输入与调整数字典型应用包括商品购买数量选择、年龄/人数设置、价格区间调整等。本文以 Vant 官方文档为骨架结合 Stepper 源码、样式实现 与 单元测试系统讲解 Stepper 的安装方式、全部 21 个 Props、7 个事件、值格式化原理、长按手势、异步拦截before-change机制与主题定制方案让你既能快速上手也能深入理解其底层实现。组件简介与安装注册Stepper 组件由增加按钮、减少按钮和输入框组成用于在一定范围内输入、调整数字。作为 Vant 的标准组件Stepper 已内置在vant包中只需从包中导入并全局注册即可使用import { createApp } from vue; import { Stepper } from vant; const app createApp(); app.use(Stepper);从源码看Stepper 通过withInstall包装导出入口文件因此支持app.use(Stepper)的全局注册方式同时也支持局部注册与按需引入配合vant-auto-import-resolver自动导入并在declare module vue中声明了VanStepper全局组件类型模板中可直接使用van-stepper标签并获得完整的类型提示。更多注册方式可参考组件注册指南。基础用法与核心交互基础用法通过v-model双向绑定当前值初始值1van-stepper v-modelvalue /import { ref } from vue; export default { setup() { const value ref(1); return { value }; }, };点击按钮数值增加step默认1点击−按钮数值减少step。组件在渲染时使用rolegroup/rolespinbutton等 ARIA 属性并同步设置aria-valuemin、aria-valuemax、aria-valuenow具备良好的无障碍可访问性见 Stepper.tsx。步长设置step通过step属性设置每次点击增加或减少按钮时变化的数值默认为1van-stepper v-modelvalue step2 /源码中步长通过addNumber(current.value, diff)累加计算Stepper.tsx其中addNumber是 Vant 提供的浮点安全加法工具函数export function addNumber(num1: number, num2: number) { const cardinal 10 ** 10; return Math.round((num1 num2) * cardinal) / cardinal; }它在 utils/format.ts 中定义通过先放大再四舍五入的方式规避0.1 0.2 ! 0.3这类 JS 浮点精度问题。因此使用step0.2这类小数步长时累加结果也能保持准确。限制输入范围min / max通过min和max属性限制输入值的范围van-stepper v-modelvalue min5 max8 /默认情况下超出范围的值会被自动校正到最近的边界值min或max若希望保留用户输入的超范围值而不自动校正可将auto-fixed设置为false。这一行为在源码的format函数中有明确实现Stepper.tsx// 超出范围时根据 autoFixed 决定是否夹取到 [min, max] value autoFixed ? Math.max(Math.min(max, value), min) : value;同时minusDisabled与plusDisabled两个计算属性会实时判断当前值是否已到边界从而自动为−、按钮加上禁用态Stepper.tsx。测试用例也验证了边界行为设置max: 2后连续点击 两次update:modelValue仅发出[2]和[1]越界点击会触发overlimit事件见 test/index.spec.ts。限制输入整数integer设置integer属性后输入框将限制只能输入整数van-stepper v-modelvalue integer /该属性有三层作用Stepper.tsx输入过滤formatNumber(String(value), !props.integer)在integer为true时不允许小数点输入2.2会被过滤为2键盘类型输入框type变为telinputmode变为numeric移动端弹出纯数字键盘格式化失焦或属性变化时数值会被取整。测试should format value to integer when using integer prop验证了输入2.2后得到2的行为test/index.spec.ts。禁用状态disabled通过设置disabled属性禁用整个步进器禁用后无法点击按钮、也无法修改输入框van-stepper v-modelvalue disabled /禁用时输入框的disabled属性被置为true−和按钮的计算禁用条件中包含props.disabled见 Stepper.tsx同时按钮会添加van-stepper__minus--disabled/van-stepper__plus--disabled类名与aria-disabled属性。样式方面禁用态按钮使用--van-stepper-button-disabled-color背景与--van-stepper-button-disabled-icon-color图标色输入框使用--van-stepper-input-disabled-text-color/--van-stepper-input-disabled-background并针对 iOS 补充了-webkit-text-fill-color修复禁用文字颜色问题见 index.less。禁用输入框disable-input通过设置disable-input属性禁用输入框此时按钮仍然可以点击van-stepper v-modelvalue disable-input /实现上输入框被设置为readonly源码注释说明readonly在旧版移动端 Safari 上不生效因此onFocus中还会主动调用inputRef.value?.blur()强制失焦见 Stepper.tsx同时onMousedown会preventDefault用于修复移动端 Safari 页面滚动问题。测试should make input readonly when using disable-input prop断言了输入框存在readonly属性test/index.spec.ts。固定小数位数decimal-length通过decimal-length属性保留固定的小数位数常与小数步长搭配使用van-stepper v-modelvalue step0.2 :decimal-length1 /该属性在输入过程与最终格式化两处生效Stepper.tsx 与 Stepper.tsx输入时若输入内容包含小数点则只保留小数点后decimal-length位例如输入1.25且decimal-length1时输入框内容会被截断为1.2格式化后最终值通过value.toFixed(decimalLength)补齐位数例如step0.2、decimal-length2时初始值显示为1.00点击一次变为1.20见 test/index.spec.ts。需要留意的是设置decimal-length后v-model的值会以字符串形式输出如1.20以便保留小数位。自定义大小input-width / button-size通过input-width设置输入框宽度通过button-size设置按钮大小以及输入框高度van-stepper v-modelvalue input-width40px button-size32px /源码中通过addUnit和getSizeStyle将尺寸转换为内联样式Stepper.tsxconst inputStyle computed(() ({ width: addUnit(props.inputWidth), height: addUnit(props.buttonSize), })); const buttonStyle computed(() getSizeStyle(props.buttonSize));即button-size同时决定输入框高度与加减按钮的边长当传入纯数字时自动补px单位。测试用例验证了input-width10rem时输入框样式宽度为10remtest/index.spec.ts。异步变更before-change通过before-change属性可以在输入值变化前进行校验和拦截。回调返回false时阻止变更也支持返回 Promise 进行异步校验van-stepper v-modelvalue :before-changebeforeChange /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, }; }, };底层通过 Vant 的工具函数callInterceptor实现定义于 utils/interceptor.ts调用点见 Stepper.tsx。其核心逻辑为若beforeChange返回 Promise则等待 resolve值为true时执行done()即真正写入current.value为false时取消变更Promise 被 reject 时执行error回调。测试should allow to using before-change prop验证了beforeChange: () false时点击 不会发出update:modelValuetest/index.spec.ts。典型应用场景包括服务端库存校验、提交前的二次确认、需要展示加载状态的长流程校验等。圆角风格themeround将theme设置为round可展示圆角风格步进器通常搭配disable-input使用van-stepper v-modelvalue themeround button-size22 disable-input /圆角主题的样式定义在 index.less输入框背景变为透明加减按钮变为圆形border-radius: 100%按钮使用主色--van-stepper-button-round-theme-color白字实心样式−按钮为主色描边 浅色背景按钮禁用时透明度降为0.3。完整 API 参考Props参数说明类型默认值v-model当前输入的值number | string-min最小值number | string1max最大值number | string-auto-fixed是否自动校正超出限制范围的数值设置为false后输入超过限制范围的数值将不会自动校正booleantruedefault-value初始值当 v-model 为空时生效number | string1step步长每次点击时改变的值number | string1name标识符通常为一个唯一的字符串或数字可以在change事件回调参数中获取number | string-input-width输入框宽度默认单位为pxnumber | string32pxbutton-size按钮大小以及输入框高度默认单位为pxnumber | string28pxdecimal-length固定显示的小数位数number | string-theme样式风格可选值为roundstring-placeholder输入框占位提示文字string-integer是否只允许输入整数booleanfalsedisabled是否禁用步进器booleanfalsedisable-plus是否禁用增加按钮booleanfalsedisable-minus是否禁用减少按钮booleanfalsedisable-input是否禁用输入框booleanfalsebefore-change输入值变化前的回调函数返回false可阻止输入支持返回 Promise(value: number | string) boolean | Promisebooleanfalseshow-plus是否显示增加按钮booleantrueshow-minus是否显示减少按钮booleantrueshow-input是否显示输入框booleantruelong-press是否开启长按手势开启后可以长按增加和减少按钮booleantrueallow-empty是否允许输入的值为空设置为true后允许传入空字符串booleanfalse源码级补充说明min、max、step、name、default-value等数值型 Props 在源码中使用makeNumericProp声明类型为Number | String的组合意味着传入字符串2与数字2等效见 Stepper.tsx 与 utils/props.tsshow-plus、show-minus、show-input、long-press、auto-fixed使用truthPropBoolean类型但默认值为true因此不传值即为开启只有显式传false才关闭utils/props.tsmax的源码默认值是InfinitymakeNumericProp(Infinity)即不传时无上限min的源码默认值为1before-change的类型即 Vant 的Interceptor类型(...args: any[]) Promiseboolean | boolean | undefined | voidutils/interceptor.tsshow-*系列属性控制的是按钮/输入框的显示与隐藏v-show而disable-*系列控制的是可用性二者可以组合使用例如只展示输入框的纯数量输入场景。Events事件名说明回调参数change当绑定值变化时触发的事件value: string, detail: { name: string }overlimit点击不可用的按钮时触发-plus点击增加按钮时触发-minus点击减少按钮时触发-focus输入框聚焦时触发event: Eventblur输入框失焦时触发event: Event事件触发时序与内部逻辑Stepper.tsx内部current值变化时依次发出update:modelValue与changechange的第二参数为{ name }可用于在列表循环中区分具体是哪个步进器点击被禁用或已达边界的按钮时发出overlimit事件适合用于提示已达上限/下限plus/minus在按钮点击且变更成功时发出可在变更后执行埋点等副作用blur事件在失焦格式化完成后通过nextTick发出并调用resetScroll()修复 iOS 输入框失焦后页面滚动位置错乱的问题Stepper.tsx。测试用例验证了change事件携带{ name }的行为默认name为空字符串设置name: name后回调参数变为[3, { name: name }]test/index.spec.ts。类型定义组件导出以下类型定义可在 TS 项目中直接引用import type { StepperTheme, StepperProps } from vant;此外入口文件还导出了stepperPropsprops 定义对象便于二次封装透传与StepperThemeVars主题变量类型见 types.ts 与 index.tsimport type { StepperThemeVars } from vant; // StepperThemeVars 包含 stepperBackground、stepperInputWidth、 // stepperButtonRoundThemeColor、stepperRadius 等全部主题变量值格式化机制与底层原理Stepper 之所以怎么输入都不会出错核心在于组件内部统一的format函数Stepper.tsx它按以下顺序处理值空值处理allowEmpty为true时保留空字符串否则空值转为0科学计数法修正数字若包含e如9.9e-7先toFixed展开为普通小数最多保留 17 位JS number 的最大精度避免大/小数值显示异常非法字符过滤调用formatNumber过滤掉非数字、多余小数点与多余负号非法输入如a会被清空NaN 兜底Number.isNaN(value)时回退为min值范围夹取autoFixed为true时通过Math.max(Math.min(max, value), min)将值夹取到[min, max]小数位补齐设置了decimal-length时用toFixed格式化。同时组件通过两个watch保持外部值与内部值的同步Stepper.tsx监听max / min / integer / decimalLength变化时重新check()当前值因此动态修改 min/max 后现有值会被立即自动校正测试should watch min and max props and format modelValue验证了这一点监听外部modelValue变化若与内部值不一致则重新格式化。为什么 value 有时候会变成 string 类型用户输入过程中可能出现小数点或空值比如输入1.时onInput会优先保留number 类型只有当formatted String(formatted)即格式化的字符串能还原为同值数字时才转成数字否则以字符串抛出Stepper.tsx。因此在输入中间态v-model的值可能是字符串。如果希望 value 始终保持 number 类型可以在 v-model 上添加number修饰符van-stepper v-model.numbervalue /长按手势long-press默认开启长按手势长按或−按钮可连续、快速调整数值适合需要大范围调整数量的场景如购物车数量从 1 加到 99。关闭方式van-stepper v-modelvalue :long-pressfalse /实现要点Stepper.tsx常量LONG_PRESS_START_TIME 500定义于 utils/constant.ts触摸按下 500ms 后判定为长按进入连续调整模式常量LONG_PRESS_INTERVAL 200进入长按后每 200ms 触发一次onChange递归调用longPressStep实现定时器链长按期间松开手指touchend/touchcancel时清除定时器并通过preventDefault阻止后续 click 事件的二次触发按钮同时绑定了 click 与 passive 的 touchstart 事件onTouchstartPassive保证普通点击与长按互不干扰。测试用例使用假定时器验证了长按 500ms 后再持续 500ms 可连续从 1 调到 5而设置longPress: false后长按无任何效果test/index.spec.ts。主题定制CSS 变量组件提供了下列 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)圆角大小这些变量的默认值定义在 index.less 的:root, :host中通过覆盖同名变量即可实现主题定制例如:root { --van-stepper-button-round-theme-color: #ff976a; --van-stepper-input-width: 48px; --van-stepper-radius: 8px; }对应的 TypeScript 主题变量类型StepperThemeVars定义于 types.ts可在基于 ConfigProvider 的 TS 主题方案中获得类型提示。进阶使用技巧1. 表单中区分多个步进器在商品列表等循环场景中通过name标识符 change事件回调即可区分具体是哪个步进器发生了变化van-stepper v-foritem in goodsList :keyitem.id v-modelitem.count :nameitem.id change(val, detail) onCountChange(val, detail) /const onCountChange (value, { name }) { // name 即为商品 idvalue 为最新数量 console.log(商品 ${name} 的数量变为 ${value}); };2. 仅输入框模式与纯按钮模式结合show-*与disable-*系列属性可裁剪出不同形态!-- 仅显示输入框隐藏按钮 -- van-stepper v-modelvalue :show-minusfalse :show-plusfalse / !-- 仅按钮模式隐藏输入框常用于步进按钮 -- van-stepper v-modelvalue :show-inputfalse /3. 空值允许与占位提示需要允许用户清空输入如数量可为空时配合allow-empty与placeholdervan-stepper v-modelvalue allow-empty placeholder请输入数量 /4. 结合表单组件使用Stepper 内部调用了useCustomFieldValue来自vant/use见 Stepper.tsx因此可以无缝嵌入 Vant 的 Form 表单 中参与校验与值收集无需额外桥接。常见问题FAQQ1点击按钮没有反应是什么原因先检查disabled是否误传了true其次确认是否到达min/max边界此时按钮为禁用态并触发overlimit事件可监听该事件给出提示最后检查是否配置了before-change返回了false或 resolve(false) 导致变更被拦截。Q2为什么设置decimal-length后 v-model 的值变成字符串了因为toFixed的结果是字符串这是为了保留小数位如1.20无法用 number 表达。如仍需数字可在外层使用v-model.number或在回调中Number()转换。Q3为什么 value 有时候会变成 string 类型用户输入过程中可能出现小数点或空值比如1.此时组件会抛出字符串类型。如果希望 value 保持 number 类型可以在 v-model 上添加number修饰符van-stepper v-model.numbervalue /Q4长按会误触吗如何关闭长按判定需要按住 500ms 才进入连续调整模式普通点击不受影响。若在列表滚动场景担心误触可设置:long-pressfalse关闭。总结Stepper 是 Vant 中小而精的代表组件对外提供 21 个 Props、6 个事件与 13 个主题变量覆盖了数量调整的大多数业务形态对内则通过统一的format管道非法字符过滤、NaN 兜底、范围夹取、小数位补齐、浮点安全的addNumber累加、callInterceptor异步拦截和基于定时器链的长按手势把输入健壮性这件事做到了极致。理解其格式化与事件时序后无论是直接使用、二次封装还是阅读其他 Vant 表单组件的源码都会更加得心应手。完整的组件演示代码可查看 demo/index.vue快照测试见 test/index.spec.ts。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
