# NumberBox 步进器 
该组件一般用于商城购物选择物品数量的场景
注意:该输入框只能输入大于或等于0的整数
# 基本使用
通过v-model绑定modelValue初始值,此值是双向绑定的,无需在回调中将返回的数值重新赋值给modelValue。
<template> <un-number-box v-model="value" @change="onChange"></un-number-box> </template> <script setup lang="uts"> import { ref } from 'vue' import type { UnNumberBoxChangeEvent } from '@/uni_modules/uview-unix/components/un-number-box' const value = ref<number>(0) const onChange = (e: UnNumberBoxChangeEvent) => { console.log('当前值为:', e.value) console.log('组件标识符:', e.name) } </script>✅ Copy success!
# 步长设置
- 通过
step属性设置每次点击增加或减少按钮时变化的值,默认为1,下面示例每次都会加2或者减2
<un-number-box :step="2"></un-number-box>✅ Copy success!
# 限制输入范围
通过min和max参数限制输的入值最小值和最大值
<un-number-box :min="1" :max="100"></un-number-box>✅ Copy success!
# 限制只能输入整数
通过integer限制输入类型
<un-number-box integer></un-number-box>✅ Copy success!
# 禁用
<!-- 通过设置`disabled`参数来禁用输入框,禁用状态下无法点击加减按钮或修改输入框的值 --> <un-number-box :disabled="true"></un-number-box> <!-- 禁用输入框 --> <un-number-box :disabledInput="true"></un-number-box> <!-- 禁用增加按钮 --> <un-number-box :disablePlus="true"></un-number-box> <!-- 禁用减少按钮 --> <un-number-box :disableMinus="true"></un-number-box> <!-- 禁用长按 --> <un-number-box :longPress="false"></un-number-box>✅ Copy success!
# 固定小数位数
通过step设置步进长度,decimal-length设置显示小数位数
<un-number-box step="0.25" decimal-length="1"></un-number-box>✅ Copy success!
# 异步变更
通过asyncChange设置异步变更,开启后需要手动控制输入值(默认 false)
<template> <un-number-box v-model="value" :asyncChange="true" @change="onChange"></un-number-box> </template> <script setup lang="uts"> import { ref } from 'vue' import type { UnNumberBoxChangeEvent } from '@/uni_modules/uview-unix/components/un-number-box' const value = ref<number>(1) const asyncChange = ref<boolean>(true) const onChange = (e: UnNumberBoxChangeEvent) => { asyncChange.value = false uni.showLoading({ title: '正在加载' }) setTimeout(() => { uni.hideLoading() value.value = e.value asyncChange.value = true }, 3000) } </script>✅ Copy success!
# 自定义颜色和大小
- 通过
button-size参数设置按钮大小 - 通过
icon-style参数设置加减按钮图标的样式
<un-number-box button-size="36" color="#ffffff" bgColor="#2979ff" iconStyle="color: #fff" ></un-number-box>✅ Copy success!
# 自定义 slot
<template> <un-number-box v-model="value"> <view slot="minus" class="minus" > <un-icon name="minus" size="12" ></un-icon> </view> <text slot="input" style="width: 50px;text-align: center;" class="input" >{{value}}</text> <view slot="plus" class="plus" > <un-icon name="plus" color="#FFFFFF" size="12" ></un-icon> </view> </un-number-box> </template> <script setup lang="uts"> import { ref } from 'vue' const value = ref<number>(1) </script> <style lang="scss"> .minus { width: 22px; height: 22px; border-width: 1px; border-color: #E6E6E6; border-style: solid; border-top-left-radius: 100px; border-top-right-radius: 100px; border-bottom-left-radius: 100px; border-bottom-right-radius: 100px; /* #ifndef APP-NVUE */ display: flex; /* #endif */ flex-direction: row; justify-content: center; align-items: center; } .input { padding: 0 10px; } .plus { width: 22px; height: 22px; background-color: #FF0000; border-radius: 100px; /* #ifndef APP-NVUE */ display: flex; /* #endif */ justify-content: center; align-items: center; } </style>✅ Copy success!
# API
# Props
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
|---|---|---|---|---|
| name | 步进器标识符,在change回调返回 | String | Number | - | - |
| value | 用于双向绑定的值,初始化时设置设为默认min值(最小值) | String | Number | 1 | - |
| min | 用户可输入的最小值 | String | Number | 1 | - |
| max | 用户可输入的最大值 | String | Number | Number.MAX_SAFE_INTEGER | - |
| step | 步长,每次加或减的值, 支持小数值,如需小数 | String | Number | 1 | - |
| integer | 是否只能输入正整数 | Boolean | false | true |
| disabled | 是否禁用操作,包括输入框,加减按钮 | Boolean | false | true |
| disabledInput | 是否禁止输入框 | Boolean | false | true |
| asyncChange | 是否开启异步变更,开启后需要手动控制输入值 | Boolean | false | true |
| inputWidth | 输入框宽度,单位px | String | Number | 35 | - |
| showMinus | 是否显示减少按钮 | Boolean | true | false |
| showPlus | 是否显示增加按钮 | Boolean | true | false |
| decimalLength | 显示的小数位数 | String | Number | - | - |
| longPress | 是否允许长按进行加减 | Boolean | true | false |
| color | 输入框文字和加减按钮图标的颜色 | String | #323233 | - |
| buttonSize | 按钮大小,宽高等于此值,单位px,输入框高度和此值保持一致 | String | Number | 30 | - |
| bgColor | 输入框和按钮的背景颜色 | String | #EBECEE | - |
| cursorSpacing | 指定光标于键盘的距离,避免键盘遮挡输入框,单位px | String | Number | 100 | - |
| disablePlus | 是否禁用增加按钮 | Boolean | false | true |
| disableMinus | 是否禁用减少按钮 | Boolean | false | true |
| iconStyle | 加减按钮图标的样式 | String | - | - |
| iconSize | 加减按钮图标大小 | String | Number | 15 | - |
| buttonRound | 加减按钮圆角 | String | Number | - | - |
| inputBgColor | 输入框背景颜色 | String | - | - |
| disableColor | 按钮禁用后按钮和输入框字体颜色 | String | #f7f8fa | - |
| disableBgColor | 禁用后的按钮和输入框背景颜色 | String | #c8c9cc | - |
# Events
| 事件名 | 说明 | 回调参数 | 参数说明 |
|---|---|---|---|
| focus | 输入框得到焦点触发(按钮可点击情况下) | value: number | 输入框当前值 |
| focus | 输入框得到焦点触发(按钮可点击情况下) | name: string | number | 步进器标识符 |
| blur | 输入框失去焦点时触发 | value: number | 输入框当前值 |
| blur | 输入框失去焦点时触发 | name: string | number | 步进器标识符 |
| change | 输入框内容发生变化时触发 | value: number | 输入框当前值 |
| change | 输入框内容发生变化时触发 | name: string | number | 步进器标识符 |
| plus | 点击增加按钮时触发 | value: number | 输入框当前值 |
| plus | 点击增加按钮时触发 | name: string | number | 步进器标识符 |
| minus | 点击减少按钮时触发 | value: number | 输入框当前值 |
| minus | 点击减少按钮时触发 | name: string | number | 步进器标识符 |
| overlimit | 超过范围阈值时触发 | type: string | 操作类型:minus已达最小值,plus已达最大值 |
# Slots
| 名称 | 说明 |
|---|---|
| minus | 减少按钮 |
| input | 输入框 |
| plus | 增加按钮 |
# 类型定义
# UnNumberBoxChangeEvent
数字输入框变化事件回调参数类型,在 @change 事件中返回。
type UnNumberBoxChangeEvent = { name: string | number // 步进器标识符 value: number // 输入框当前值 }✅ Copy success!
示例:
// 处理数字输入框变化事件 const handleChange = (e: UnNumberBoxChangeEvent) => { console.log('标识符:', e.name) console.log('当前值:', e.value) }✅ Copy success!
属性说明:
name: 步进器标识符,用于区分多个数字输入框modelValue: 双向绑定的数值,组件初始化时自动设置为最小值min/max: 数值范围限制,支持字符串和数字类型integer: 是否只允许输入整数,开启后无法输入小数asyncChange: 异步变更模式,开启后需要手动控制输入值更新decimalLength: 小数位数限制,控制数值精度longPress: 长按手势支持,可快速连续增减数值