夜雨聆风uni-app 步进器组件 cxl-number-box 实战：6 个场景掌握数字输入
购物车数量修改、商品规格选择、积分兑换……数字加减是移动端最常见的交互之一。今天介绍一个轻量级 uni-app 步进器组件 cxl-number-box，支持自定义步长、边界限制、禁用状态、列表批量管理等功能。
一、组件介绍
cxl-number-box 是一个数字步进器组件，核心特点：
- 加减按钮 + 手动输入
：点击 +/- 按钮或直接输入数字均可 - 自定义步长
：支持整数步长（1、5、10）和小数步长（0.5、0.1） - 边界限制
：min / max 限定范围，达到边界自动禁用对应按钮 - 输入保护
：手动输入超限值时自动修正，NaN 自动回退 - 浮点精度
：内部使用缩放法处理浮点运算，避免 0.1 + 0.2 ≠ 0.3 的问题 - 列表支持
：通过 index 参数在列表中定位具体行 - 禁用状态
：支持静态和动态禁用
安装方式
将组件文件夹放入 components 目录，uni-app easycom 自动注册：
components/└── cxl-number-box/└── cxl-number-box.vue
注意：组件名必须包含连字符
-，否则 easycom 无法自动识别。
二、属性速查表
value | |||
min | |||
max | |||
step | |||
disabled | |||
index | |||
@change |
重要：
step支持小数，组件内部通过"缩放法"（乘以 10^n 转为整数运算）避免浮点精度误差。
三、6 个实战示例
示例 01：基本用法
最简单的使用方式，指定 value、min、max 和 step：
<template><cxl-number-box:value=”0”:min=”0”:max=”100”:step=”1”@change=”onChange”></cxl-number-box></template><script>export default {data() {return { num: 0 }},methods: {onChange(value) {this.num = value}}}</script>
显示效果：[-] 0 [+]，点击按钮数值在 0~100 之间变化。
示例 02：自定义步长
step 支持整数和小数，满足不同精度需求：
<!-- 步长 = 5（快速增减） --><cxl-number-box:value=”0”:min=”0”:max=”100”:step=”5”></cxl-number-box><!-- 步长 = 0.5（小数精度） --><cxl-number-box:value=”1”:min=”0.5”:max=”10”:step=”0.5”></cxl-number-box>
步长对照表：
实现原理：当 step 为小数时（如 0.5），组件识别到小数位数后使用缩放法：先将数值乘以 10（变成 5 的整数运算），计算完成后再除以 10 还原，避免浮点误差。
示例 03：边界限制
min 和 max 限定操作范围，达到边界时按钮自动置灰：
<!-- 标准范围 0~10 --><cxl-number-box:min=”0”:max=”10”></cxl-number-box><!-- 最少1件（不允许为0） --><cxl-number-box:min=”1”:max=”5”></cxl-number-box><!-- 支持负数 --><cxl-number-box:min=”-5”:max=”5”></cxl-number-box>
边界行为：
示例 04：禁用状态
通过 disabled 属性控制组件是否可操作：
<!-- 静态禁用 --><cxl-number-box:value=”5”:disabled=”true”></cxl-number-box><!-- 动态禁用（根据库存判断） --><cxl-number-box:value=”1”:disabled=”stock <= 0”></cxl-number-box>
适用场景：
库存为 0 时禁止增减 活动已结束时锁定数量 订单提交中防抖
示例 05：列表场景（购物车）
在 v-for 列表中使用多个步进器，通过 index 属性定位修改行：
<template><viewclass=”cart-item”v-for=”(item,index) incartList” :key=”index”><text>{{ item.name }} - ¥{{ item.price }}</text><cxl-number-box:value=”item.quantity”:min=”1”:max=”item.stock”:step=”1”:index=”index”@change=”onCartChange”></cxl-number-box></view></template><script>export default {data() {return {cartList: [{ name: '蓝牙耳机', price: 299, quantity: 1, stock: 5 },{ name: '智能手表', price: 599, quantity: 2, stock: 10 },{ name: '充电宝', price: 129, quantity: 1, stock: 20 }]}},methods: {// 传入 index 时，参数为 [index, value] 数组onCartChange([index, value]) {this.cartList[index].quantity = value}}}</script>
index 参数说明：
value | 5 | |
[index, value] | [0, 5] |
示例 06：事件监听
@change 事件在数值变化时触发，配合事件日志可清楚看到每次变化：
<!-- 单个步进器：参数为 value --><cxl-number-box @change=”onSingleChange”></cxl-number-box><!-- 列表中：参数为 [index, value] --><cxl-number-box:index=”index”@change=”onListChange”></cxl-number-box>
// 不传 indexonSingleChange(value) {console.log('数值变为：', value) // value = 5}// 传 indexonListChange([index, value]) {console.log('第', index, '行数值变为：', value) // index = 0, value = 5}
四、使用要点与注意事项
1. value 支持 String 类型
组件内部使用 +value 进行数值转换，因此传入字符串类型的数字（如 "5"）也能正常工作：
// 以下两种写法等价<cxl-number-box :value=”5”></cxl-number-box><cxl-number-boxvalue=”5”></cxl-number-box>
2. 浮点步长的精度保护
当 step 为小数时，如果直接用浮点数运算会出现 0.1 + 0.2 = 0.30000000000000004 之类的问题。组件内部通过"缩放法"解决：
// 组件内部实现_getDecimalScale() {let scale = 1if (~~this.step !== this.step) {// 识别小数位数scale = Math.pow(10, (this.step + '').split('.')[1].length)}return scale}// step=0.5 → scale=10 → 运算时 value*10, 结果再/10
3. min / max 与按钮联动
当 inputValue <= min时，减号按钮添加--disabled样式类并阻止点击当 inputValue >= max时，加号按钮添加--disabled样式类并阻止点击手动输入时同样受边界约束
4. 组件命名
组件名包含连字符 cxl-number-box，符合 uni-app easycom 自动识别规范，无需手动 import 和注册。
5. 事件参数差异
根据是否传入 index，@change 事件参数不同：
value | onChange(value) {} | |
[index, value] | onChange([idx, val]) {} |
五、总结
cxl-number-box 是一个功能完整、考虑周全的步进器组件：
适用于电商购物车、积分兑换、数量配置、评分调节等各类场景。
源码获取：本文所有示例代码已提交至 Gitee 仓库，分支
cxl-number-box🔗 https://gitee.com/hszcxl/TestUniapp/tree/cxl-number-box