uView Next
4.0.105

外观

NumberBox 步进器

约 1553 字大约 5 分钟

2025-10-31

该组件一般用于商城购物选择物品数量的场景

注意：该输入框只能输入大于或等于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'

const value = ref<number>(0)

const onChange = (e: UnNumberBoxChangeEvent) => {
	console.log('当前值为:', e.value)
	console.log('组件标识符:', e.name)
}
</script>

步长设置

  • 通过step属性设置每次点击增加或减少按钮时变化的值，默认为1，下面示例每次都会加2或者减2
<un-number-box :step="2"></un-number-box>

限制输入范围

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

<un-number-box :min="1" :max="100"></un-number-box>

限制只能输入整数

通过integer限制输入类型

<un-number-box integer></un-number-box>

禁用

<!-- 通过设置`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>

固定小数位数

通过step设置步进长度，decimal-length设置显示小数位数

<un-number-box step="0.25" decimal-length="1"></un-number-box>

异步变更

通过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'

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>

自定义颜色和大小

  • 通过button-size参数设置按钮大小
  • 通过icon-style参数设置加减按钮图标的样式
<un-number-box 
    button-size="36"
    color="#ffffff"
    bgColor="#2979ff"
    iconStyle="color: #fff"
></un-number-box>

自定义 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>

API

Props

参数说明类型默认值
name步进器标识符，在change回调返回String | Number-
value用于双向绑定的值，初始化时设置设为默认min值(最小值)String | Number1
min用户可输入的最小值String | Number1
max用户可输入的最大值String | Number-
step步长，每次加或减的值，支持小数值，如需小数String | Number1
integer是否只能输入正整数
Enum
false
disabled是否禁用操作，包括输入框，加减按钮
Enum
false
disabledInput是否禁止输入框
Enum
false
asyncChange是否开启异步变更，开启后需要手动控制输入值
Enum
false
inputWidth输入框宽度，单位pxString | Number35
showMinus是否显示减少按钮
Enum
true
showPlus是否显示增加按钮
Enum
true
decimalLength显示的小数位数String | Number-
longPress是否允许长按进行加减
Enum
true
color输入框文字和加减按钮图标的颜色String#323233
buttonSize按钮大小，宽高等于此值，单位px，输入框高度和此值保持一致String | Number30
bgColor输入框和按钮的背景颜色String#EBECEE
cursorSpacing指定光标于键盘的距离，避免键盘遮挡输入框，单位pxString | Number100
disablePlus是否禁用增加按钮
Enum
false
disableMinus是否禁用减少按钮
Enum
false
iconStyle加减按钮图标的样式String-
iconSize加减按钮图标大小String | Number15
buttonRound加减按钮圆角String | Number-
inputBgColor输入框背景颜色String-
disableColor按钮禁用后按钮和输入框字体颜色String#f7f8fa
disableBgColor禁用后的按钮和输入框背景颜色String#c8c9cc

Events

事件名说明类型
focus输入框得到焦点触发(按钮可点击情况下)
Function
blur输入框失去焦点时触发
Function
change输入框内容发生变化时触发
Function
plus点击增加按钮时触发
Function
minus点击减少按钮时触发
Function
overlimit超过范围阈值时触发
Function

Slots

名称说明
minus减少按钮
input输入框
plus增加按钮

数据类型

// 数字输入框变化事件回调参数类型，在 `@change` 事件中返回。
type UnNumberBoxChangeEvent = {
    name: string | number     // 步进器标识符
    value: number            // 输入框当前值
}

Scss 变量

变量名默认值说明
$un-number-box-button-width30px按钮宽度
$un-number-box-button-height30px按钮高度
$un-number-box-button-bg-color#EBECEE按钮背景颜色
$un-number-box-button-disabled-bg-color#f7f8fa按钮禁用背景颜色
$un-number-box-button-border-radius4px按钮圆角
$un-number-box-input-width35px输入框宽度
$un-number-box-input-font-size15px输入框文字大小
$un-number-box-input-height30px输入框高度
$un-number-box-input-margin0 2px输入框外边距
$un-number-box-input-bg-color#EBECEE输入框背景颜色
$un-number-box-input-disabled-color#c8c9cc输入框禁用文字颜色
$un-number-box-input-disabled-bg-color#f2f3f5输入框禁用背景颜色

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next