NumberBox 步进器

17:06

说明

用于加减选择数值：点击加减按钮或直接输入，v-model 双向绑定数值。支持 step 步长、min / max 范围限制与 long-press 长按连续加减；positive-integer 默认只接受正整数。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

v-model 绑定数值，点击加减按钮或手动输入修改。

查看源码

<template>
    <ux-number-box v-model="val" />
</template>

<script setup lang="uts">
const val = ref<number>(1);
</script>

步长设置

通过 step 属性设置每次加减的值，这里为 10。

查看源码

<template>
    <ux-number-box v-model="val" :step="10" />
</template>

<script setup lang="uts">
const val = ref<number>(10);
</script>

限制范围

通过 min 和 max 限制最小值和最大值，这里为 5-50。

查看源码

<template>
    <ux-number-box v-model="val" :min="5" :max="50" />
</template>

<script setup lang="uts">
const val = ref<number>(5);
</script>

禁用状态

disabled=true 时禁止加减和输入操作。

查看源码

<template>
    <ux-number-box v-model="val" :disabled="true" />
</template>

<script setup lang="uts">
const val = ref<number>(1);
</script>

自定义尺寸

通过 size、input-width、input-height 自定义尺寸。

查看源码

<template>
    <ux-number-box v-model="val" :size="15" :input-width="60" :input-height="30" />
</template>

<script setup lang="uts">
const val = ref<number>(1);
</script>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
modelValue	输入框初始值（默认1）	number	1	-
bgColor	输入框和按钮的背景颜色	string	''	-
min	用户可输入的最小值（默认0）	number	0	-
max	用户可输入的最大值（默认50000）	number	99999	-
step	步长，每次加或减的值（默认1）	number	1	-
disabled	是否禁用操作（默认false）	boolean	false	-
size	输入框文字和按钮字体大小，单位px（默认13）	number | string	13	-
color	输入框文字和加减按钮图标的颜色	string	''	-
inputWidth	输入框宽度，单位px（默认40）	number | string	40	-
inputHeight	输入框和按钮的高度，单位px（默认25）	number | string	25	-
index	事件回调时用以区分当前发生变化的是哪个输入框	number | string	''	-
disabledInput	是否禁止输入框手动输入值（默认false）	boolean	false	-
cursorSpacing	指定光标于键盘的距离（默认50）	number | string	100	-
longPress	是否开启长按连续递增或递减（默认true）	boolean	true	-
pressTime	开启长按触发后，每触发一次需要多久，单位ms（默认125）	number | string	250	-
positiveInteger	是否只能输入正整数（默认true）	boolean	true	-
validateState	校验错误状态，用于错误时边框是否改为红色	boolean	false	-

Events

事件名	说明	回调参数	版本
change	输入框内容发生变化时触发	value: UTSJSONObject	-
blur	输入框失去焦点时触发	value: UTSJSONObject	-
focus	输入框获得焦点时触发	-	-
minus	点击减少按钮时触发	value: UTSJSONObject	-
plus	点击增加按钮时触发	value: UTSJSONObject	-

Slots

ux-number-box 无插槽。

注意事项

• 手动输入只接受非负整数：失焦时用 /^\d+$/ 校验，含小数点、负号或以 0 开头的输入会被重置为 min，随后再按 min / max 夹取。
• positive-integer（默认 true）在输入过程中拦截负数与小数，回退到上一个合法值。
• 点击加减按钮使结果超出 min / max 时不会更新（直接忽略该次点击）；到达边界或禁用时，按钮呈置灰样式。
• long-press 默认开启：长按加减按钮按 press-time（默认 250ms）间隔连续递增/递减，松手停止。
• disabled-input 只禁止输入框手动输入，加减按钮仍可用；disabled 则整体禁用（输入框与按钮都不可操作）。
• 组件可注入 ux-form-item 上下文，值变化与失焦会触发其校验；validate-state 或表单校验失败时根节点加红色边框。