UI组件前端【免费下载链接】varletA Vue3 component library based on Material Design 2 and 3, supporting mobile and desktop.项目地址https://gitcode.com/gh_mirrors/va/varlet点击查看免费下载本文是 Varlet 组件库中Switch开关选择器组件的完整技术指南。基于仓库内 switch/docs/en-US.md 与 switch/docs/zh-CN.md 官方文档展开并结合 Switch.vue、props.ts、switch.less 等源码与单元测试深入讲解该组件的全部 Props、Events、CSS 变量、表单校验含 Zod、异步变更等实战能力。读完本文你将能熟练使用 Switch 完成从简单双向绑定到服务端确认变更、从基础校验到 Zod Schema 校验、从默认 Material 风格到 Variant 变体模式的全场景开发并理解其底层实现原理。组件定位与快速上手Switch 是 Varlet 提供的开关选择器组件用于在“开 / 关”两种状态之间切换是移动端设置项、权限开关、偏好配置等交互中最常见的控件之一。组件注册名与全局导入均为VarSwitch前缀命名空间为var-switch见 index.ts 中withInstall(Switch)的安装逻辑。基本使用v-model 双向绑定最简单的方式是直接通过v-model绑定一个响应式状态script setup import { ref } from vue const value ref(true) /script template var-switch v-modelvalue / /template默认情况下v-model的值为布尔值开关打开时组件会向modelValue写入true关闭时写入false。组件根元素带有roleswitch与:aria-checkedmodelValue无障碍属性见 Switch.vue原生语义完善。自定义开关值active-value / inactive-value如果业务状态不是布尔值例如需要区分1/2、字符串或其他枚举可以通过active-value与inactive-value指定“打开”与“关闭”分别对应的值二者的类型为_any_默认分别为true与false见 props.tsscript setup import { ref } from vue const value ref(1) /script template var-switch v-modelvalue active-value1 inactive-value2 / /template组件内部通过isActive computed(() props.modelValue props.activeValue)判断当前是否处于激活状态Switch.vue即modelValue与activeValue严格相等时视为打开。这一点在tests/index.spec.js 中有直接测试当modelValue由1切换为2时track 元素的--active类随之消失。状态控制禁用、只读与加载Switch 提供了三种阻断交互的状态适用场景各不相同。禁用 disabled禁用后组件不可点击、不可聚焦视觉上通过filter: opacity(var(--switch-disabled-opacity))降低透明度并显示cursor: not-allowed见 switch.lesstemplate var-switch v-modelvalue disabled / /template只读 readonly只读状态下组件仍可被点击并触发click事件但不会发生状态变更template var-switch v-modelvalue readonly / /template从源码看点击处理函数switchActive中的判断顺序为先拦截disabled含表单级禁用form?.disabled.value随后照常触发onClick再拦截loading || readonly || form?.readonly.value之后才计算新值并发出变更事件Switch.vue。这一行为在测试 index.spec.js 中得到了精确验证禁用状态下点击click与change均不触发value保持不变只读状态下点击click触发 1 次change不触发value保持不变。加载状态 loadingloading会在开关手柄内渲染一个旋转的 SVG 圆环阻止状态变更常用于“提交中 / 等待接口返回”的场景template var-switch :model-valuetrue loading / /template加载图标由 Switch.vue 中的内联svg viewBox25 25 50 50circle//svg绘制并通过--switch-loading-size默认16px控制尺寸旋转与描边动画定义在 switch.less 的circle/circularkeyframes 中。视觉定制颜色、尺寸与交互效果自定义颜色color / close-color / loading-color三个颜色属性分别控制不同状态下的配色color开关打开时的背景色close-color开关关闭时的背景色loading-color加载图标的颜色。script setup import { ref } from vue const value ref(true) /script template var-switch v-modelvalue colorvar(--color-warning) close-colorvar(--color-info) / /template属性值可以直接传 CSS 颜色也可以像示例一样传入 Varlet 的主题 CSS 变量如var(--color-warning)。从源码看styleComputed.handle.backgroundColor在激活态取color、非激活态取closeColorstyleComputed.track.backgroundColor同理Switch.vue。测试 index.spec.js 验证了打开时 handle 背景为red、加载色为yellow关闭后变为blue。调整尺寸size通过size属性可以整体缩放开关接受_string | number_类型。传数字时按px处理也可传带单位的字符串script setup import { ref } from vue const value ref(true) /script template var-switch v-modelvalue :size15 / var-switch v-modelvalue / var-switch v-modelvalue :size25 / /templatesize并非简单设置容器宽高而是作为基准单位参与整套尺寸计算handle、track、ripple、switch 容器的宽高与位置都会基于size按比例推导见 Switch.vue 中styleComputed内multiplySizeUnit(size, 系数)的调用。例如 track 宽高为size * 1.9与size * 0.72ripple 为size * 2。其底层实现是 utils/elements.ts 中的multiplySizeUnit先将数值统一转为带单位的合法尺寸toSizeUnit会把数字补上px识别vh / % / rem / em / px / vw / vmin / vmax等单位再提取单位、乘以系数后拼接返回例如25px * 1.9 47.5px。因此size也支持传入vmin、vw等响应式单位——仓库示例 example/index.vue 就使用了size4.266vmin、size6.4vmin实现移动端自适应。水波纹与手柄海拔ripple / button-elevationripple是否启用水波纹反馈默认true。点击时手柄区域会产生 Material 风格的水波扩散动画。源码通过v-ripple指令实现并在disabled / loading / readonly以及表单级禁用、只读时自动禁用波纹Switch.vue。button-elevation自3.2.7起控制手柄按钮的海拔阴影效果默认true。文档将其标注为_boolean_源码类型实为[Boolean, String, Number]props.ts即也支持传入数字指定海拔等级如4。渲染时经formatElevation(buttonElevation, 2)转为var-elevation--2之类的工具类见 utils/components.ts默认等级为 2传入false则不加任何海拔。测试验证了默认生成var-elevation--2、传入4后生成var-elevation--4index.spec.js。表单校验rules 与 ZodSwitch 内置了与 Varlet 表单体系统一的校验能力这也是它区别于纯展示型开关组件的关键特性。校验规则数组通过rules传入一个校验器数组也可传单个校验器。每个校验器接收当前值v返回true表示校验通过返回其他任意值都会被转换为字符串作为错误提示文本展示script setup import { ref } from vue const value ref(true) /script template var-switch v-modelvalue :rulesv v true || Error! / /template校验失败时错误信息会显示在组件下方的var-form-details区域同时 track 与 handle 会套用--error类背景色切换为var(--color-danger)见 [Switch.vue](https://link.gitcode.com/i/b05e35d3767f3b0b4b1a41f26d45fbd5#L14-L16, L29-L37) 与 [switch.less](https://link.gitcode.com/i/a4f83aeadf20c92a0abe527e221ca4c2#L69-L72, L110-L113)。使用 Zod 校验自 3.5.0 起从3.5.0版本开始rules还支持直接传入 Zod Schema。结合 Zod 的refine可以编写更复杂的校验逻辑script setup import { ref } from vue import { z } from zod const value ref(true) /script template var-switch v-modelvalue :rulesz.boolean().refine(v v true, Error!) / /template校验实现位于 utils/components.ts 的useValidationisZodRule通过检测对象上是否存在safeParseAsync函数来区分 Zod Schema 与普通函数校验器校验时把所有规则归一化为数组Promise.all并行执行——Zod 规则走safeParseAsync(value)普通函数直接rule(value, apis)只要存在一条失败规则即判定失败Zod 规则失败时取result.error.issues[0].message作为错误文案普通规则失败时String(result)作为文案。仓库的单元测试 index.spec.js 直接以z.boolean().refine((v) v, value must be true)验证了 Zod 校验链路其渲染结果记录在snapshots/index.spec.js.snap 中。Zod 与 Varlet 表单体系的整体协作方式可参考 zodValidation.zh-CN.md。触发时机validate-triggervalidate-trigger控制验证触发的时机可选值为onChange与onLazyChange默认两者都触发[onChange, onLazyChange]见 props.ts触发值含义onChange每次状态正常切换时验证onLazyChange异步变更模式下before-change回调中执行change(value)更新后验证两者在switchActive的不同分支中分别调用validateWithTrigger(onChange)与validateWithTrigger(onLazyChange)Switch.vue最终由useValidation中的validateWithTrigger依据validateTrigger数组决定是否真正执行验证utils/components.ts。异步变更lazy-change 与 before-change某些场景下状态变更需要先经过服务端确认例如“开启某个敏感权限”需要等待接口返回成功后再更新界面。此时可以开启lazy-change开启后组件自身不再直接更新绑定值点击时触发before-change事件回调参数为(value, change)由你决定何时调用change(value)手动完成更新实现“先请求、后变更”的异步流程。script setup import { ref } from vue const value ref(true) function handleBeforeChange(value, change) { setTimeout(() change(value), 500) } /script template var-switch lazy-change v-modelvalue before-changehandleBeforeChange / /template从源码看lazy-change分支的完整调用链为Switch.vueswitchActive(event) └─ 计算 newValue isActive ? inactiveValue : activeValue └─ call(onBeforeChange, newValue, changeFn) └─ 业务侧异步等待后调用 changeFn(value) └─ call(updateModelValue, value) // 触发 update:modelValue └─ validateWithTrigger(onLazyChange) // 触发校验注意change回调接收的值由业务代码决定并不强制等于newValue——这意味着你可以在回调中写入接口返回的最终状态实现完全受控。测试 index.spec.js 模拟了 500ms 延迟后调用change(value)的过程并断言点击后立即检查value仍为true未更新600ms 后变为false更新完成。Variant 变体模式自 3.2.3 起从3.2.3版本开始Switch 提供了variant变体模式可一键切换为另一种视觉形态script setup import { ref } from vue const value ref(true) /script template var-switch variant v-modelvalue / /template开启variant后组件根元素会附加var-switch--variant类Switch.vue样式上呈现以下差异见 switch.less容器尺寸从40px × 24px变为52px × 32px对应--switch-variant-width/heighttrack 变为通栏width: 100%圆角变为胶囊形calc(var(--switch-variant-height) / 2)关闭态带2px边框--switch-variant-track-border-color: #888背景使用--color-surface-container-highesthandle 为24px × 24px关闭态transform: scale(2 / 3)缩小内嵌激活态恢复scale(1)并切换为--color-on-primary背景、--color-primary前景色波纹定位偏移量也不同--switch-variant-ripple-left: -4px激活态16px。变体模式的快照在 index.spec.js.snap 中可以看到普通模式与 variant 模式完整 DOM 结构的差异。键盘可访问性与无障碍Switch 对键盘操作做了完整支持保证桌面端可达性[Switch.vue](https://link.gitcode.com/i/b05e35d3767f3b0b4b1a41f26d45fbd5#L24-L26, L147-L171)手柄元素可聚焦tabindex默认在未禁用时为0也可通过tabindex属性自定义该属性自3.12.2起支持与原生 input 的tabindex语义一致聚焦后按Enter或空格键Space即可切换开关监听 window 级keydown/keyup并对默认行为调用preventDefault避免页面滚动根元素提供roleswitch与aria-checked辅助读屏。对应的键盘测试见 index.spec.jsEnter 按下触发一次click空格键按下 抬起也触发一次click。此外桌面端悬停时手柄会出现 hover 反馈v-hover:desktop指令 var-hover-overlay遮罩层[Switch.vue](https://link.gitcode.com/i/b05e35d3767f3b0b4b1a41f26d45fbd5#L3, L54-L57)进一步贴近桌面交互习惯。与 Form 表单体系、StyleProvider 的集成表单联动Switch 通过useForm()与 Varlet 的Form组件联动[Switch.vue](https://link.gitcode.com/i/b05e35d3767f3b0b4b1a41f26d45fbd5#L100, L139-L145)位于var-form内时自动继承表单级disabled/readonly状态判断逻辑见 [Switch.vue](https://link.gitcode.com/i/b05e35d3767f3b0b4b1a41f26d45fbd5#L198, L204)通过SwitchProvider类型即表单的Validation接口见 provide.ts向 Form 暴露validate/resetValidation/reset三个方法reset会将modelValue重置为inactiveValue并清空校验错误Switch.vue。因此 Switch 可以直接参与 Form 的全局校验与重置与 Input、Select 等表单项行为一致。样式定制组件全部尺寸与颜色均通过 CSS 变量暴露可以使用 StyleProvider 组件进行主题级定制文档中 Style Variables 一节即为此用途。所有变量的默认值定义在 switch.less 的:root中。API 参考Props参数说明类型默认值v-model开关选中状态anyfalseactive-value开关打开时的值anytrueinactive-value开关关闭时的值anyfalsedisabled是否禁用booleanfalsereadonly是否只读booleanfalseloading是否为加载状态booleanfalseripple是否启用水波纹booleantruebutton-elevation3.2.7控制按钮的海拔效果源码类型为Boolean \| String \| Number支持数字海拔等级booleantruecolor打开状态下的颜色string-close-color关闭状态下的颜色string-loading-color加载图标的颜色string-sizeswitch 的大小数值按 px 处理支持带单位字符串string | number-rules验证规则返回true表示验证通过其它类型的值将转换为文本作为用户提示。自3.5.0起支持 Zod 验证((v: any) any) | ZodType | Array((v: any) any) | ZodType-lazy-change是否允许触发before-change事件booleanfalsevalidate-trigger触发验证的时机可选值onChange、onLazyChangeSwitchValidateTrigger[][onChange, onLazyChange]variant3.2.3变体模式booleanfalsetabindex3.12.2与原生 input 的 tabindex 属性一致string-说明v-model在 props 层面对应modelValue/onUpdate:modelValue[props.ts](https://link.gitcode.com/i/1863a9d1be2e8fb81eab0279be8429cb#L7-L9, L42)SwitchValidateTrigger联合类型定义于 props.ts。Events事件名说明回调参数click点击时触发event: Eventchange开关状态切换时触发value: anybefore-change变更之前仅限lazy-change模式触发value: anychange: (value: any) void事件触发顺序值得留意正常模式下点击会先触发update:modelValue更新绑定值随后触发change测试 index.spec.js 断言调用顺序为[update, change]。样式变量Style Variables以下为组件使用的 CSS 变量可通过 StyleProvider 进行主题定制默认值均可在 switch.less 中查看与覆盖变量名默认值--switch-track-background#fff--switch-track-active-backgroundvar(--color-primary)--switch-track-error-backgroundvar(--color-danger)--switch-ripple-colorvar(--color-primary)--switch-handle-backgroundvar(--color-on-primary)--switch-handle-colorvar(--color-primary)--switch-handle-active-colorvar(--color-on-primary)--switch-handle-active-backgroundvar(--color-primary)--switch-handle-error-backgroundvar(--color-danger)--switch-disabled-opacityvar(--opacity-disabled)--switch-variant-width52px--switch-variant-height32px--switch-variant-track-border-color#888--switch-variant-track-backgroundvar(--color-surface-container-highest)--switch-variant-handle-width24px--switch-variant-handle-height24px--switch-variant-handle-colorvar(--color-on-primary)--switch-variant-handle-active-colorvar(--color-primary)--switch-variant-handle-background#888--switch-variant-handle-active-backgroundvar(--color-on-primary)--switch-width40px--switch-height24px--switch-track-width38px--switch-track-height14.4px--switch-track-border-radiuscalc(20px * 2 / 3)--switch-handle-width20px--switch-handle-height20px--switch-ripple-size40px--switch-ripple-left-10px--switch-ripple-active-left10px--switch-loading-size16px--switch-variant-ripple-left-4px--switch-variant-ripple-active-left16px小结Varlet 的 Switch 组件虽然是一个“小”控件但在工程能力上并不简单active-value/inactive-value支持任意业务取值size通过multiplySizeUnit实现整套比例缩放rules同时支持函数校验器与 Zod Schema3.5.0lazy-changebefore-change为服务端确认型交互提供了官方解法variant模式3.2.3则让同一组件能适配两种视觉体系。配合键盘操作、无障碍属性、Form 联动与完整的 CSS 变量体系它足以覆盖移动端与桌面端绝大多数开关场景。若想深入验证文中行为可直接查看仓库内的组件源码 Switch.vue、属性定义 props.ts、样式 switch.less 及单元测试 index.spec.js。赞分享UI组件前端【免费下载链接】varletA Vue3 component library based on Material Design 2 and 3, supporting mobile and desktop.项目地址https://gitcode.com/gh_mirrors/va/varlet点击查看免费下载相关推荐Varlet 单选框Radio组件完全指南API 详解、表单校验与源码实现Varlet 单选框Radio组件完全指南API 详解、表单校验与源码实现 本指南围绕 Varlet UI 中 var radio 单选框及其配套的 vaUI组件前端Varlet 组件库 Zod 表单验证指南从安装到源码原理Varlet 组件库 Zod 表单验证指南从安装到源码原理 导读 本指南面向使用 VarletVue3 组件库的开发者系统讲解自 3.5.0 版本起内置UI组件前端ToolJet Toggle Switch 组件完整指南属性、事件、CSA 动作、校验与样式配置实战ToolJet Toggle Switch 组件完整指南属性、事件、CSA 动作、校验与样式配置实战 Toggle Switch 是 ToolJet 应用构建低代码后端前端AI 应用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考