夜雨聆风uni-app 开关组件 cxl-switch 详解
前言
在表单设置、权限管理、功能开关等场景中，「开关组件」是最常用的交互元素之一。一个好用、灵活的开关组件能极大提升用户体验。
今天介绍一个功能全面的开关组件 —— cxl-switch，它支持 v-model 双向绑定、自定义颜色、自定义开关值、异步校验等功能，完美适配 uni-app 多端（H5、微信小程序、App）。
组件特性
- v-model 双向绑定
：支持 Vue 标准的 v-model 语法，使用极其简单 - 自定义颜色
： activeColor和inactiveColor分别控制开关两个状态的颜色 - 自定义开关值
： activeValue/inactiveValue支持布尔、数字、字符串类型 - 异步校验
： beforeChange函数支持 Promise 和 Boolean 返回值，可在切换前进行确认或校验 - 禁用状态
： disabled属性控制开关是否可交互 - 多种尺寸
： size属性控制开关大小（默认 30px） - 跨端适配
：适配 APP-NVUE，支持原生渲染
属性速查表
value | false | ||
activeColor | '#108ee9' | ||
inactiveColor | '#fff' | ||
size | 30 | ||
disabled | false | ||
activeValue | true | ||
inactiveValue | false | ||
beforeChange | null | ||
extraData | null | ||
contextLevel | 1 |
快速开始
在 components/cxl-switch/ 目录下放置组件后，uni-app 的 easycom 会自动注册，无需手动 import。
最简用法：
<cxl-switchv-model=”value”></cxl-switch>就这么简单！一行代码即可实现开关切换。
实战示例
示例1：基本用法
v-model 双向绑定：
<template><view><text>当前状态：{{ value ? '开' : '关' }}</text><cxl-switchv-model=”value” /></view></template><script>export default {data() {return { value: false }}}</script>
监听 change 事件：
<cxl-switchv-model=”val” @change=”onChange” /><script>export default {methods: {onChange(newVal) {console.log('切换到：', newVal)}}}</script>
示例2：自定义颜色
通过 activeColor 和 inactiveColor 可以灵活搭配颜色：
<!-- 默认蓝色 --><cxl-switchv-model=”v1”activeColor=”#108ee9” /><!-- 绿色 --><cxl-switchv-model=”v2”activeColor=”#52c41a” /><!-- 红色 --><cxl-switchv-model=”v3”activeColor=”#f5222d” /><!-- 组合配色：绿 + 灰 --><cxl-switchv-model=”v4”activeColor=”#52c41a”inactiveColor=”#f0f0f0” /><!-- 组合配色：红 + 粉 --><cxl-switchv-model=”v5”activeColor=”#f5222d”inactiveColor=”#fff0f0” />
示例3：自定义开关值
除了布尔值，开关还支持数字和字符串：
<!-- 数字值：1 和 0，适合对接后端 --><cxl-switchv-model=”status”:activeValue=”1”:inactiveValue=”0” /><!-- 字符串值：'on' 和 'off' --><cxl-switchv-model=”mode”activeValue=”on”inactiveValue=”off” />
三种值类型的使用场景：
truefalse | ||
10 | ||
'on''off' |
示例4：异步校验
beforeChange 是 cxl-switch 最强大的特性之一，支持两种返回方式：
返回 Promise（异步确认）：
<cxl-switchv-model=”val”:beforeChange=”beforeChangePromise” /><script>export default {methods: {beforeChangePromise(newVal) {return new Promise((resolve, reject) => {uni.showModal({title: '确认操作',content: `确定要${newVal ? '开启' : '关闭'}吗？`,success: (res) => {if (res.confirm) resolve()else reject()}})})}}}</script>
点击开关后会弹出确认框，只有用户确认后才真正切换。
返回布尔值（同步校验）：
<cxl-switchv-model=”val”:beforeChange=”beforeChangeBool” /><script>export default {methods: {beforeChangeBool(newVal) {// 返回 false 阻止切换if (newVal && !this.hasPermission) {uni.showToast({ title: '无权限开启', icon: 'none' })return false}return true}}}</script>
示例5：禁用与尺寸
禁用状态：
<!-- 禁用-开 --><cxl-switch:value=”true”disabled /><!-- 禁用-关 --><cxl-switch:value=”false”disabled />
不同尺寸：
<cxl-switchv-model=”v1”:size=”20” /> <!-- 小号 --><cxl-switchv-model=”v2”:size=”30” /> <!-- 中号（默认） --><cxl-switchv-model=”v3”:size=”40” /> <!-- 大号 --><cxl-switchv-model=”v4”:size=”50” /> <!-- 超大号 -->
常见使用场景
<cxl-switch v-model="form.open" /> | ||
<cxl-switch :beforeChange="checkPerm" /> | ||
<cxl-switch :beforeChange="confirmFn" /> | ||
<cxl-switch v-model="dto.status" :activeValue="1" :inactiveValue="0" /> | ||
<cxl-switch :value="true" disabled /> |
总结
cxl-switch 是一个简洁而强大的 uni-app 开关组件。v-model 双向绑定让使用极简，自定义颜色和尺寸满足各种 UI 风格，beforeChange 异步校验机制解决了开关前需确认或校验的痛点。
如果你的项目中需要开关组件，不妨试试 cxl-switch，一行代码即可使用！
Gitee 地址
本文示例代码已开源：
👉 git clone -b cxl-switch https://gitee.com/hszcxl/TestUniapp
如果觉得本文对你有帮助，欢迎点赞、评论、转发支持！
