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`	String/Number/Boolean	`false`	当前值，支持 v-model
`activeColor`	String	`'#108ee9'`	打开时的背景色
`inactiveColor`	String	`'#fff'`	关闭时的背景色
`size`	Number	`30`	开关尺寸（px）
`disabled`	Boolean	`false`	是否禁用
`activeValue`	String/Number/Boolean	`true`	打开时的值
`inactiveValue`	String/Number/Boolean	`false`	关闭时的值
`beforeChange`	Function	`null`	切换前校验函数
`extraData`	Any	`null`	传递给 beforeChange 的额外数据
`contextLevel`	Number	`1`	beforeChange 上下文层级

快速开始

在 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” />

三种值类型的使用场景：

值类型	示例	适用场景
布尔值	`true` / `false`	前端内部状态切换
数字值	`1` / `0`	直接对接后端 status 字段
字符串	`'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” /> <!-- 超大号 -->

常见使用场景

场景	推荐用法	示例
表单开关	v-model 布尔值	`<cxl-switch v-model="form.open" />`
权限开关	beforeChange 校验	`<cxl-switch :beforeChange="checkPerm" />`
确认操作	beforeChange Promise	`<cxl-switch :beforeChange="confirmFn" />`
对接后端	数字值 1/0	`<cxl-switch v-model="dto.status" :activeValue="1" :inactiveValue="0" />`
展示状态	disabled	`<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

如果觉得本文对你有帮助，欢迎点赞、评论、转发支持！