Stepper 步进器

手机扫码预览

01:50



组件名：rice-stepper

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

平台兼容性

uni-app x

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

基本使用

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

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

注意

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

步长设置

• 通过 step 属性设置递增递减的步进控制，默认为 1。

<rice-stepper v-model="value2" :step="5"></rice-stepper>

限制输入范围

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

<rice-stepper v-model="value3" :min="5" :max="10"></rice-stepper>

提示

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

限制输入整数

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

<rice-stepper v-model="value4" integer></rice-stepper>

固定小数位数

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

<rice-stepper v-model="value5" :step="0.2" :decimal-length="1"></rice-stepper>

禁用状态

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

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

禁用输入框

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

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

异步控制

设置 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" />

自定义样式

• 通过 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/model-value	Number	绑定值	-
step	Number	步长，默认	1
min	Number	最小值	-
max	Number	最大值	-
auto-fixed	Boolean	是否自动校正超出限制范围的数值	-
integer	Boolean	是否只允许输入整数，默认false	-
decimal-length	Number	固定显示的小数位数	-
disabled	Boolean	是否禁用，默认false	-
readonly	Boolean	是否只读，默认false	-
disable-minus	Boolean	是否禁用减少按钮，默认false	-
disable-plus	Boolean	是否禁用增加按钮，默认false	-
disable-input	Boolean	是否禁用输入框，默认false	-
show-minus	Boolean	是否显示减少按钮，默认true	-
show-plus	Boolean	是否显示增加按钮，默认true	-
show-input	Boolean	是否显示输入框，默认true	-
before-change	Function	改变前的钩子，返回 false 或者返回 Promise 且被 reject 或 resolve 但返回值不为 true，则停止切换	-
input-width	String|Number	输入框宽度，默认36px	-
button-size	String|Number	按钮大小和输入框高度，默认30px	-
font-size	String|Number	按钮icon大小和输入框文字大小，默认14px	-
mode	String	样式风格，可选值为 round 默认 square，可选值：round、square、outline	square
plus-btn-style	Object	增加按钮的样式	-
minus-btn-style	Object	减少按钮的样式	-
input-style	Object	input的样式	-
custom-style	Object	自定义style	-

Events

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

类型定义

组件导出如下类型

// 组件类型
const switchRef = ref<RiceStepperComponentPublicInstance | null>(null)