更新记录

1.0.2（2025-12-07） 下载此版本

适配鸿蒙样式

1.0.1（2025-12-07） 下载此版本

针对鸿蒙系统进行适配

1.0.0（2025-12-07） 下载此版本

appx-number-box 是一款基于 UTS 编写的跨端步进器组件，支持数值的增加 / 减少操作、手动输入，可自定义样式、禁用状态、数值范围等，适用于电商数量选择、表单数值调整等场景。

平台兼容性

uni-app x(4.87)

appx-number-box 步进器组件帮助文档

组件介绍

appx-number-box 是一款基于UTS编写的跨端步进器组件，支持数值的增加/减少操作、手动输入，可自定义样式、禁用状态、数值范围等，适用于电商数量选择、表单数值调整等场景。

组件属性（Props）

组件事件（Emits）

组件方法（内部逻辑）

数值格式化逻辑

组件内置formatValue方法，会自动处理以下场景：

1. 非数字值（如输入字母）自动修正为min值；
2. 数值超出min/max范围时，自动修正为边界值；
3. 步长为非正数时，自动重置为1并在控制台输出警告。

核心交互逻辑

1. 按钮操作：点击“+”/“-”按钮时，先判断组件是否禁用、数值是否超出边界，再按步长调整数值，最后触发update:modelValue和change事件；
2. 输入框操作：输入过程中实时格式化数值并更新绑定值；失焦时再次格式化数值，确保符合范围限制，并触发blur事件；
3. 值同步：监听modelValue变化，实时同步到组件内部值并格式化，确保数值始终合法。

样式说明（Scoped）

使用示例

基础用法

<template>
  <appx-number-box v-model="count" />
</template>

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

自定义范围和步长

<template>
  <appx-number-box 
    v-model="count" 
    :min="1" 
    :max="10" 
    :step="2" 
  />
</template>

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

自定义样式+禁用输入

<template>
  <appx-number-box 
    v-model="count" 
    :height="40" 
    :borderRadius="8" 
    inputColor="#0088ff"
    :disableInput="true"
    :customStyle="{ background: '#f8f8f8', borderColor: '#ddd' }"
    @change="handleChange"
    @blur="handleBlur"
  />
</template>

<script lang="uts" setup>
const count = ref(1);
const handleChange = (val) => {
  console.log('数值变化：', val);
};
const handleBlur = (val) => {
  console.log('输入框失焦，最终值：', val);
};
</script>

禁用组件

<template>
  <appx-number-box v-model="count" :disabled="true" />
</template>

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

注意事项

1. step属性必须为正数，否则组件会自动重置为1并在控制台输出警告；
2. 手动输入非数字内容时，失焦后会自动修正为min值；
3. customStyle优先级高于组件默认样式，可覆盖背景、边框等样式；
4. 组件支持跨端使用（基于UTS），样式已做自适应处理，无需额外适配基础布局。