TDesign 小程序 Switch 开关组件完全指南：属性、事件与样式定制

前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载导读本文基于 TDesign MiniProgram 仓库 中 uniapp 版本的 Switch 开关组件文档README.en-US.md展开系统讲解t-switch /的完整 API 面全部 Props、change 事件、External Classes 与 27 个 CSS 变量并深入到 switch.vue、props.ts 与 switch.less 的源码实现帮你理解开关值切换的底层逻辑从而能在 uniapp 与微信小程序两端灵活实现基础开关、带文字/图标开关、自定义颜色与多尺寸适配。一、组件定位与使用场景Switch 开关用于控制某个功能的开启和关闭是典型的表单类组件TDesign 分类中属于 form spline。在 uniapp 端组件位于 packages/uniapp-components/switch支持 Skyline 与 WebView 两种渲染框架见 _example/switch.vue 中的 demo 说明。与此同时仓库还维护了一份微信小程序原生版本位于 packages/components/switch两者 API 保持一致。组件引入方式文档推荐使用 easycom 模式引入配置后无需手动 import 即可直接在模板中使用t-switch /。如需手动引入可按以下方式import TSwitch from tdesign/uniapp/switch/switch.vue;二、Switch Props 全解析下表完整罗列了文档中定义的 9 个 Props并结合 props.ts 的默认值与校验逻辑逐项说明| 名称 | 类型 | 默认值 | 说明 | 必传 | | -- | -- | -- | -- | -- | | custom-style | Object | - | 自定义样式 | N | | custom-value | Array | [true, false] | 自定义开关值[打开时的值关闭时的值]例如[1, 0]、[open, close]。TS 类型ArraySwitchValue| N | | disabled | Boolean | undefined | 是否禁用组件优先级Switch.disabled Form.disabled | N | | icon | Array | [] | 开关图标[打开时的图标关闭时的图标]。TS 类型string[]| N | | label | Array | [] | 开关内容[开启时内容关闭时内容]例如[开, 关]。TS 类型string[]| N | | loading | Boolean | false | 是否处于加载中状态 | N | | size | String | medium | 开关尺寸可选项small / medium / large | N | | value | String / Number / Boolean | - | 开关值支持语法糖v-model:value。TS 类型SwitchValue| N | | default-value | String / Number / Boolean | - | 开关值非受控属性。TS 类型SwitchValue| N |其中SwitchValue的类型定义为string | number | boolean完整接口见 type.ts。2.1 受控与不受控value 与 default-value 的分工这是本组件最核心的使用概念。从源码看switch.vue 中通过uniComponent声明了controlledPropscontrolledProps: [ { key: value, event: change, }, ],这意味着value是受控属性点击开关触发change事件后组件内部会同步把value更新为新值因此开发者可以直接使用v-model:value语法实现双向绑定无需手动监听事件回写。而在初始化数据时源码采用coalesce(this.value, this.defaultValue)的取值策略value存在时以value为准否则回退到default-value。同时通过watch监听value与dataValuewatch: { value: { handler(v) { this.dataValue v; }, immediate: true, }, dataValue: { handler(val) { const [activeValue] this.customValue; this.checked val activeValue; }, immediate: true, }, },即组件内部状态checked完全由「当前开关值是否等于customValue[0]」决定。在表单场景中default-value适合不需要外部监听、仅初始化一次的「非受控」用法。2.2 custom-value让开关值不再局限于布尔custom-value默认是[true, false]但可以通过它把开关映射到任意业务值。例如提交给后端的值可能是1/0或者业务枚举open/close。该能力与微信小程序原生版本的实现保持一致原生版 switch.ts 中同样通过customValue的第一个元素判断checkedhandleSwitch() { const { loading, disabled, value, customValue } this.data; const [activeValue, inactiveValue] customValue; if (loading || disabled) return; this._trigger(change, { value: value activeValue ? inactiveValue : activeValue, }); }uniapp 版 switch.vue 的handleSwitch逻辑与之一致handleSwitch() { const { loading, disabled, dataValue, customValue } this; const [activeValue, inactiveValue] customValue; if (loading || disabled) return; this._trigger(change, { value: dataValue activeValue ? inactiveValue : activeValue, }); }也就是说开关的每一次切换本质上是在customValue[0]开与customValue[1]关之间互换这也是change事件参数中value的真实来源。2.3 icon 与 label文字与图标的组合展示label传入两个元素的数组时会在滑块内展示文字开启时显示label[0]关闭时显示label[1]icon传入两个图标名时则展示对应的 TDesign 图标开启时icon[0]关闭时icon[1]。从模板结构可以看到当label.length 2时渲染text当icon.length 2时渲染t-icon且二者共用同一个容器text v-else-iflabel.length 2 {{ checked ? label[0] : label[1] }} /text t-icon v-else-ificon.length 2 :namechecked ? icon[0] : icon[1] :t-classtools.cls(classPrefix __icon, [[checked, checked], size]) /2.4 size 与校验size支持 small / medium / large默认 medium。在 props.ts 中带有运行时校验器size: { type: String, default: medium as TdSwitchProps[size], validator(val: TdSwitchProps[size]): boolean { if (!val) return true; return [small, medium, large].includes(val); }, },传入非法尺寸值时Vue 会给出校验警告。三档尺寸在 switch.less 中对应三组宽高与圆角变量详见第五节渲染效果差异明显。三、Switch Eventschange 事件| 名称 | 参数 | 说明 | | -- | -- | -- | | change |(context: { value: SwitchValue })| 数据发生变化时触发 |点击开关未禁用且非加载中时触发change回调参数携带{ value: SwitchValue }。结合受控属性change事件既可以通过v-model:value隐式消费也可以显式监听例如仓库示例 _example/label/index.vue 中的用法t-switch :valuedefaultVal :label[开, 关] changehandleChange /methods: { handleChange(e) { this.defaultVal e.value; }, },组件根节点还带有无障碍语义属性aria-checked、aria-disabled与aria-roleswitch便于辅助技术识别开关状态见 switch.vue 模板。四、External Classes 外部样式类文档定义了 4 个外部样式类用于从组件外部精准覆盖局部样式而无需改动组件内部样式| 类名 | 说明 | | -- | -- | | t-class | 根节点样式类 | | t-class-body | 轨道滑块容器样式类 | | t-class-dot | 滑块样式类 | | t-class-label | 开关内容文字/图标样式类 |组件声明位置见 switch.vue 中的externalClasses: [t-class, t-class-label, t-class-body, t-class-dot]并分别挂载到根 view、__body、__dot与__label节点上。使用时直接传入同名 class 即可例如t-switch t-classcustom-switch t-class-bodycustom-body t-class-dotcustom-dot t-class-labelcustom-label /需要说明的是微信小程序原生版本同样支持这四个外部类见 packages/components/switch/switch.ts 的externalClasses定义两端用法一致。五、CSS Variables 样式定制全表文档提供了 27 个 CSS 变量覆盖颜色、尺寸、圆角、图标、文字等多个维度。它们全部在 switch.less 中以var(--td-switch-xxx, 默认值)的形式被引用因此可以直接在页面或组件上通过 CSS 变量覆盖实现主题定制。完整清单如下| 变量名 | 默认值 | 说明 | | -- | -- | -- | | --td-switch-checked-color | brand-color | 开启时轨道颜色 | | --td-switch-checked-disabled-color | brand-color-disabled | 开启且禁用时轨道颜色 | | --td-switch-dot-disabled-color | font-white-1 | 禁用时滑块颜色 | | --td-switch-dot-horizontal-margin | 6rpx | 滑块水平边距 | | --td-switch-dot-large-size | 52rpx | 大尺寸滑块大小 | | --td-switch-dot-plain-horizontal-margin | 10rpx | 无内容时滑块水平边距 | | --td-switch-dot-plain-large-size | 44rpx | 大尺寸无内容滑块大小 | | --td-switch-dot-plain-size | 36rpx | 无内容滑块大小 | | --td-switch-dot-plain-small-size | 28rpx | 小尺寸无内容滑块大小 | | --td-switch-dot-shadow | shadow-1 | 滑块阴影 | | --td-switch-dot-size | 44rpx | 滑块大小 | | --td-switch-dot-small-size | 36rpx | 小尺寸滑块大小 | | --td-switch-height | 56rpx | 中尺寸轨道高度 | | --td-switch-icon-large-size | 48rpx | 大尺寸图标大小 | | --td-switch-icon-size | 40rpx | 中尺寸图标大小 | | --td-switch-icon-small-size | 32rpx | 小尺寸图标大小 | | --td-switch-label-checked-color | switch-checked-color | 开启时文字颜色 | | --td-switch-label-color | bg-color-secondarycontainer-active | 文字颜色 | | --td-switch-label-font-size | 28rpx | 中尺寸文字大小 | | --td-switch-label-large-font-size | 32rpx | 大尺寸文字大小 | | --td-switch-label-small-font-size | 24rpx | 小尺寸文字大小 | | --td-switch-large-height | 64rpx | 大尺寸轨道高度 | | --td-switch-large-radius | calc(switch-large-height / 2) | 大尺寸轨道圆角 | | --td-switch-large-width | 104rpx | 大尺寸轨道宽度 | | --td-switch-loading-color | brand-color | 加载指示颜色 | | --td-switch-radius | calc(switch-height / 2) | 中尺寸轨道圆角 | | --td-switch-small-height | 48rpx | 小尺寸轨道高度 | | --td-switch-small-radius | calc(switch-small-height / 2) | 小尺寸轨道圆角 | | --td-switch-small-width | 78rpx | 小尺寸轨道宽度 | | --td-switch-unchecked-color | bg-color-secondarycontainer-active | 关闭时轨道颜色 | | --td-switch-unchecked-disabled-color | bg-color-component-disabled | 关闭且禁用时轨道颜色 | | --td-switch-width | 90rpx | 中尺寸轨道宽度 |5.1 从源码理解默认值如何生效以上默认值并非硬编码在文档里而是由 switch.less 在编译期解析每一条switch-xxx: var(--td-switch-xxx, 默认值)都通过 CSS 变量回退机制兜底。例如switch-checked-color: var(--td-switch-checked-color, brand-color); switch-width: var(--td-switch-width, 90rpx); switch-height: var(--td-switch-height, 56rpx); switch-radius: var(--td-switch-radius, calc(switch-height / 2));三档尺寸的几何关系也由这些变量共同决定medium 为 90×56rpx圆角 28rpx、large 为 104×64rpx、small 为 78×48rpx对应滑块分别为 44 / 52 / 36rpx。切换轨道时滑块通过left: calc(switch-width - switch-dot-size - switch-dot-horizontal-margin)定位到右侧见 switch.less 中的--checked规则。5.2 自定义颜色实战覆盖单个变量即可仓库示例 _example/color/index.vue 展示了最简用法——只需在作用域内覆盖一个变量style .custom-color { --td-switch-checked-color: #00a870; } /style同理如果需要同时调整开启/关闭/禁用三种状态的颜色可以一次性覆盖--td-switch-checked-color、--td-switch-unchecked-color与两个*-disabled-color变量实现完整的品牌化配色。六、典型使用示例对应仓库 Demo仓库在 packages/uniapp-components/switch/_example 下提供了 base基础、label带文字/图标、color自定义颜色、status状态、size尺寸以及 skyline 渲染框架的完整示例以下为最常用的几种场景代码。6.1 基础开关受控与非受控!-- 非受控使用 default-value 初始化 -- t-switch :default-valuetrue / !-- 受控使用 v-model 双向绑定 -- t-switch v-model:valueswitchValue /对应示例见 _example/base/index.vue。6.2 带文字 / 图标开关t-switch :valuedefaultVal :label[开, 关] changehandleChange / t-switch :default-valuetrue :icon[check, close] /对应示例见 _example/label/index.vue。注意label与icon需要成对传入两个元素模板才会在滑块内渲染对应内容。6.3 加载与禁用状态t-switch :default-valuetrue loading / t-switch :default-valuetrue disabled /从handleSwitch源码可见loading与disabled状态下点击事件会被直接拦截if (loading || disabled) return不会触发change。对应示例见 _example/status/index.vue。6.4 三种尺寸t-switch :default-valuetrue sizelarge / t-switch :default-valuetrue / t-switch :default-valuetrue sizesmall /对应示例见 _example/size/index.vue。七、微信小程序原生版本对照若你的项目是原生微信小程序而非 uniapp可参考同仓库的 packages/components/switch 目录。原生版本基于wxComponent/SuperComponent实现switch.ts通过behaviors [wx://form-field]接入表单字段能力并同样声明了controlledPropskey 为value、event 为change与observers监听value变化以同步checked状态。其 Props、Events、External Classes 与 CSS 变量清单和 uniapp 版本完全对齐切换平台时无需调整业务逻辑。结语Switch 组件虽然小巧但通过custom-value的值映射、value/default-value的受控与非受控双模式、四个外部样式类以及一整套可覆盖的 CSS 变量覆盖了开关组件在真实业务中的绝大多数定制诉求。建议在接入前通读 README.md中文版与本文对应的英文文档 README.en-US.md并结合 _example 下的可运行示例快速验证各参数效果。赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐TDesign MiniProgram Switch 开关组件完全指南属性、事件、样式定制与源码原理TDesign MiniProgram Switch 开关组件完全指南属性、事件、样式定制与源码原理 导读 本文以 TDesign MiniProgram 组前端UI组件小程序设计系统移动开发中国电商运营专家智能体实战指南多平台店铺运营、直播带货与 618/双11 大促作战体系中国电商运营专家智能体实战指南多平台店铺运营、直播带货与 618/双11 大促作战体系 本指南以 agency agents zh 仓库中的 中国电商运营专家前端UI组件小程序设计系统移动开发TDesign小程序组件库样式覆盖完全指南TDesign小程序组件库样式覆盖完全指南 前言 在开发微信小程序时我们经常会使用第三方UI组件库来提升开发效率。TDesign作为腾讯出品的小程序组件库提前端UI组件小程序设计系统移动开发上一篇ComfyUI-WanVideoWrapperAI视频生成能力全景图与实战指南下一篇怎样高效识别验证码DdddOcr专业级离线OCR解决方案实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考