rice-ui

暗黑模式

Switch 开关 ​

点击扫码预览
23:47
组件名：rice-switch
演示示例可扫模拟器状态栏上的二维码预览或 点击在线预览

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

平台兼容性 ​

uni-app x ​

AndroidiOS鸿蒙Next微信小程序h5
√√√√√

基础用法 ​

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

html
<rice-switch v-model="status"/>

带描述开关 ​

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

提示

如果文本的字数在2个及以上，不建议将 prompt-position 设置为 inside，否则会导致文字显示不全。
默认情况下， Switch 的宽度会根据文本的宽度自适应，若需要固定宽度，可通过传递 width 属性实现，当设置固定宽度后，若文本宽度超出 Switch宽度，超出部分会显示为省略号。

html
<!-- 带文字 -->
<rice-switch v-model="status" active-text="开" inactive-text="关" :custom-style="{marginRight:'12px'}" />
<rice-switch v-model="status" active-text="开" inactive-text="关" prompt-position="inside" />
<!-- 带图标 -->
<rice-switch v-model="status" active-icon="right" inactive-icon="cross"
  :custom-style="{marginRight:'12px'}" />
<rice-switch v-model="status" active-icon="right" inactive-icon="cross" prompt-position="inside" />
 <!-- 长文本 -->
<rice-switch v-model="status" active-text="不显示省略号" inactive-text="关闭" :custom-style="{marginRight:'12px'}" />
<rice-switch v-model="status" active-text="超出会显示省略号" inactive-text="超出会显示省略号" width="70" />

自定义颜色 ​

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

html
<rice-switch v-model="status" active-color="#13ce66" inactive-color="#fc4b49" />

自定义大小 ​

  • 通过 width 属性可以设置 Switch 的宽度，单位支持 px 和 rpx；
  • 也可以通过 css 的 scale 方法进行调节，通过 custom-style 属性进行传递。
html
<rice-switch v-model="status" :custom-style="{transform:'scale(0.8)'}" active-text="0.8"/>
<rice-switch v-model="status" width="56" />

自定义 value 类型 ​

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

html
<rice-switch v-model="status5" active-value="on" inactive-value="off" :active-text="status5" :inactive-text="status5"/>
<rice-switch v-model="status6" :active-value="1" :inactive-value="0"/>

开关状态 ​

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

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

异步控制 ​

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

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

<script setup>
//请求成功示例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>
vue
<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>
vue
<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绑定值，必须等于 active-value 或 inactive-valueboolean|string|numberfalse
active-value打开时对应的值boolean|string|numbertrue
inactive-value关闭时对应的值boolean|string|numberfalse
loading是否为加载状态booleanfalse
disabled是否禁用booleanfalse
readonly是否只读booleanfalse
width宽度，单位支持 px rpxstring|number28px
active-color打开时的背景颜色string-
inactive-color关闭时的背景颜色string-
active-text打开时的文字描述string-
inactive-text关闭时的文字描述string-
active-icon打开时显示的图标，设置此项会忽略active-textstring-
inactive-icon关闭时显示的图标，设置此项会忽略inactive-textstring-
icon-size描述图标的大小，单位支持 px rpxstring|number12px
text-size描述文字的大小，单位支持 px rpxstring|number12px
prompt-position图标或文本显示的位置，可选 inside 在小球内stringoutside
before-changeSwitch 状态改变前的钩子， 返回 false 或者返回 Promise 且被 reject 或 resolve 但返回值不为 true，则停止切换Function
() => Promise<boolean> | boolean		-
vibrate打开时是否开启震动效果，目前仅小程序支持booleantrue
custom-style自定义styleobject-

Events ​

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

类型定义 ​

组件导出如下类型

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