# 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!

# 限制输入范围

通过minmax参数限制输的入值最小值和最大值

<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: 长按手势支持,可快速连续增减数值
上次更新时间: 2025/10/28 21:19:58
当前文档拷贝至3.x版本,尚不完善,我们正在努力完善中,欢迎您的反馈和参与改进。
×