Switch 开关

手机扫码预览

23:59



---

组件名：rice-switch

用于在打开和关闭状态之间进行切换。

平台兼容性

uni-app x

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

基础用法

通过 v-model 绑定开关的选中状态，默认 true 表示开，false 表示关。

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

开关状态

通过 disabled属性将 Switch 设置为禁用，通过 loading 属性设置为加载中。

<rice-switch v-model="value" disabled />
<rice-switch v-model="value" loading />

带描述开关

• 使用 active-text 和 inactive-text 属性来设置开关的文字描述；
• 使用 active-icon 和 inactive-icon 属性来设置开关的图标；
• 使用 prompt-position 属性来控制文本/图标 是否显示在点内，默认为 outball，可设置为 inball。

<rice-switch v-model="value2" active-icon="checked" inactive-icon="cross"/>
<!-- 描述位置 -->
<rice-switch v-model="value2" prompt-position="inball" active-icon="checked"inactive-icon="cross"/>

自定义value 类型

通过 active-value 和 inactive-value 属性自定义打开/关闭时对应的值，它们接受 Boolean、String 和 Number 类型的值。

<rice-switch v-model="value3" active-value="N" inactive-value="Y" active-text="Y" inactive-text="N"></rice-switch>

自定义颜色

通过 active-color 属性设置打开时的背景颜色，通过 inactive-color 属性设置关闭时的背景颜色。

<rice-switch v-model="value4" active-color="#07c160" inactive-color="#f56c6c"></rice-switch>

自定义大小

• 通过 width 属性可以设置 Switch 的宽度，单位支持 px 和 rpx；
• 也可以通过 css 的 scale 方法进行调节，通过 custom-style 属性进行传递。

<rice-switch v-model="value4" :custom-style="{transform:'scale(0.82)'}"></rice-switch>
<rice-switch v-model="value4" width="45px"></rice-switch>

异步控制

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

成功示例1

<template>
  <rice-switch v-model="statusAsync1" :loading="loadingAsync1" :before-change="beforeChange1"/>
</template>

<script setup lang="ts">
//请求成功示例1
const statusAsync1 = ref(true)
const loadingAsync1 = ref(false)

const beforeChange1 = () : Promise<boolean> => {
  loadingAsync1.value = true
  return new Promise((resolve) => {
    setTimeout(() => {
      loadingAsync1.value = false
      //resolve 里面必须为 true 才能切换
      resolve(true)
      //如返回reject 则不会切换
      //reject(false)
    }, 1000)
  })
}
</script>

成功示例2

<template>
  <rice-switch v-model="statusAsync2" :loading="loadingAsync2" :before-change="beforeChange2"/>
</template>

<script setup>
//请求成功示例2
const sleep = (flag : boolean) : Promise<boolean> => {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
         flag ? resolve(true) : reject(false)
      }, 1000)
    })
}

const statusAsync2 = ref(true)
const loadingAsync2 = ref(false)

const beforeChange2 = async () : Promise<boolean> => {
    loadingAsync2.value = true
    await sleep(true)
    loadingAsync2.value = false
    //不要忘记返回 true
    return true
}
</script>

失败示例

<template>
  <rice-switch v-model="statusAsyncFail" :loading="loadingAsyncFail" :before-change="beforeChangeFail"/>
</template>
<script setup>
const statusAsyncFail = ref(false)
const loadingAsyncFail = ref(false)

const beforeChangeFail = async () => {
    try {
      loadingAsyncFail.value = true
      await sleep(false)
      //不要忘记返回 true
      return true
    } catch (e) {
      loadingAsyncFail.value = false
      uni.showToast({
        title: '修改失败',
        icon: 'error'
      })
      //不要忘记返回 false
      return false
    }

}
</script>

API

Props

属性名	类型	说明	默认值
v-model/model-value	String|Number|Boolean	开关选中状态	-
active-value	String|Number|Boolean	打开时对应的值 默认true	-
inactive-value	String|Number|Boolean	关闭时对应的值 默认false	-
loading	Boolean	是否处于加载状态	-
disabled	Boolean	是否禁用	-
readonly	Boolean	是否只读	-
width	String|Number	宽度，单位支持 px rpx	-
icon-size	String|Number	icon 图标大小，单位支持 px rpx	-
text-size	String|Number	字体大小，单位支持 px rpx	-
active-color	String	打开时的背景颜色	-
inactive-color	String	关闭时的背景颜色	-
active-text	String	打开时的文字描述	-
inactive-text	String	关闭时的文字描述	-
active-icon	String	打开时显示的图标，设置此项会忽略active-text	-
inactive-icon	String	关闭时显示的图标，设置此项会忽略inactive-text	-
prompt-position	String	图标或文本显示的位置，可选值：inball、outball	outball
before-change	Function	switch 状态改变前的钩子， 返回 false 或者返回 Promise 且被 reject 则停止切换	-
vibrate	Boolean	打开时是否开启震动效果，目前仅小程序支持	-
custom-style	Object	自定义style	-

Events

事件名	说明	回调参数
change	Switch 状态发生变化时触发	value:string|number|boolean

类型定义

组件导出如下类型

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