Stepper 步进器

点击扫码预览

23:47



组件名：rice-stepper

演示示例可扫模拟器状态栏上的二维码预览或 点击在线预览

步进器由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、增减数字。

平台兼容性

uni-app x

Android	iOS	鸿蒙Next	微信小程序	h5
√	√	√	√	√

基本使用

通过 v-model 绑定变量即可，变量的初始值即为默认值。

<rice-stepper v-model="count"/>

警告

v-model 绑定的变量只能是 Number 类型，不能传入空值或字符串类型。

步长设置

• 通过 step 属性设置递增递减的步进控制，默认为 1。
• 通过 step-strictly 属性设置是否只能输入步长的倍数。

<template>
  <rice-stepper v-model="count2" :step="2" />
  <rice-stepper v-model="count3" :step="3" step-strictly />
<template>

<script setup>
  const count2 = ref(1)
  const count3 = ref(1)
</script>

限制输入范围

通过 min 和 max 限制输入值的范围， 默认超出范围后会自动校正到最大值或最小值，可以通过 auto-fixed 属性关闭自动校正。

<template>
  <rice-stepper v-model="count4" :min="2" :max="20" />
  <!-- count5小于min 10， 会自动校正为 10 -->
  <rice-stepper v-model="count5" :min="10" :max="20" />
  <!-- 关闭自动校正 -->
  <rice-stepper v-model="count6" :min="10" :max="20" :auto-fixed="false" />
</template>

<script  setup>
  const count4 = ref(4)
  const count5 = ref(5)
  const count6 = ref(6)
</script>

提示

如果 v-model 绑定的值 小于 min 或 大于 max 且 auto-fixed 为 true 的话，v-model 绑定的值会自动校正到对应的 min 或 max值。

限制整数

通过 integer 限制输入值为整数。如输入值不是整数，组件内部会通过 Math.round 方法自动校正为整数。

<template>
 <rice-stepper v-model="count7" integer />
</template>

<script  setup>
  const count7 = ref(1)
</script>

固定小数位数

通过 decimal-length 属性可以固定小数位数。

<template>
  <rice-stepper v-model="count8" :decimal-length="1" />
  <rice-stepper v-model="count9" :decimal-length="2" />
</template>

<script  setup>
  const count8 = ref(1)
  const count9 = ref(1.2)
</script>

禁用输入框

如果需要禁用输入框，设置 disableInput 为 true 即可。

<rice-stepper v-model="count" disable-input />

禁用状态

• 通过设置 disabled 属性为 true 可以禁用整个 Stepper。
• 如果只需禁用增加或减少按钮，设置 disablePlus 或 disableMinus 为 true 即可。

<rice-stepper v-model="count" disabled />
<rice-stepper v-model="count" disable-minus />
<rice-stepper v-model="count" disable-plus />

异步控制

设置 before-change 属性，若返回 false 或者返回 Promise 且被 reject 或 resolve 但返回值不为 true， 则停止改变。

成功示例

<template>
  <rice-stepper v-model="countAsync1" :before-change="beforeChange1" />
</template>

<script setup>
const countAsync1 = ref(1)
const beforeChange1 = () => {
  uni.showLoading({
    title: '请求中…',
    mask: true
  })
  return new Promise<boolean>((resolve) => {
    setTimeout(() => {
      showToast('修改成功')
      //resolve 里面必须为 true 才能切换
      resolve(true)
    }, 1000)
  })
}
</script>

失败示例

<template>
  <rice-stepper v-model="countAsync2" :before-change="beforeChange2" />
</template>

<script setup>
const countAsync2 = ref(1)
const sleep = () => {
  return new Promise<boolean>((resolve) => {
    setTimeout(() => {
      resolve(true)
    }, 1000)
  })
}

const beforeChange2 = async () => {
  uni.showLoading({
    title: '请求中…',
    mask: true
  })
  await sleep()
  showToast('修改失败','error')
  //返回 false 就是失败
  return false
}
</script>

返回非Promise示例

<template>
  <rice-stepper v-model="countAsync3" :before-change="beforeChange3" />
</template>

<script setup>
  const countAsync3 = ref(1)
  let num = 0
  const beforeChange3 = () => {
    num++
    if (num > 3) {
      showToast('操作次数过多', 'error')
      return false
    }
    return true
  }
</script>

自定义尺寸

• 通过 button-size 属性设置按钮大小和输入框高度；
• 通过 input-width 属性设置输入框的宽度；
• 通过 font-size 属性设置按钮icon大小和输入框文字大小

<rice-stepper v-model="count" input-width="42" button-size="38" font-size="15" />

自定义风格

通过 mode 属性设置风格，可选值为 round

<rice-stepper v-model="count" mode="round" button-size="26" />
<rice-stepper v-model="count" mode="round" button-size="26" disabled />

自定义样式

• 通过 btn-style 设置加减按钮样式；
• 通过 input-style 设置输入框样式

<rice-stepper v-model="count" :btn-style="{color:'#fff',backgroundColor:'#67c23a'}"
:input-style="{color:'#fff',backgroundColor:'#67c23a',width:'60px'}" />

API

props

参数	说明	类型	默认值
v-model	绑定值，只能是 Number 类型	number	-
step	步长	number	1
step-strictly	是否只能输入 step 的倍数	boolean	true
min	最小值	number	-Infinity
max	最大值	number	Infinity
auto-fixed	是否自动校正超出限制范围的数值	boolean	true
integer	是否只允许输入整数	boolean	false
decimal-length	固定显示的小数位数	number	-
disabled	是否禁用	boolean	false
readonly	是否只读	boolean	false
disable-plus	是否禁用增加按钮	boolean	false
disable-minus	是否禁用减少按钮	boolean	false
disable-input	是否禁用输入框	boolean	false
before-change	改变前的钩子， 返回 false 或者返回 Promise 且被 reject 或 resolve 但返回值不为 true，则停止改变值	boolean	-
mode	样式风格，可选值为 round	string	square
input-width	输入框宽度，单位支持 px 和 rpx	string| number	34px
button-size	按钮大小和输入框高度，单位支持 px 和 rpx	string| number	30px
font-size	按钮icon大小和输入框文字大小，单位支持 px 和 rpx	string| number	14px
btn-style	加减按钮样式	object	-
input-style	输入框样式	object	-

Events

事件名	说明	回调参数
change	绑定值被改变时触发，input框输入过程中不会触发	{value:number,oldValue?:number}
input	组件 Input 输入时触发	value:string，当前输入的值
focus	组件 Input 获得焦点时触发	event:UniInputFocusEvent
blur	组件 Input 失去焦点时触发	event:UniInputBlurEvent

类型定义

组件导出如下类型

import {StepperMode, StepperProps } from '@/uni_modules/rice-ui'
// 组件类型
const switchRef = ref<RiceStepperComponentPublicInstance | null>(null)