更新记录

1.0.0（2026-06-11）

v1.0.0

• 初始版本
• 支持轨道内文本和滑块上文本
• 支持多种动效
• 支持自定义样式
• 多端兼容

平台兼容性

uni-app(3.7.9)

hx-switch 开关组件

一个功能丰富的 UniApp 开关组件，支持轨道内文本、滑块上文字、多种动效，宽度自适应。

✨ 特性

• ✅ 支持轨道内文本显示
• ✅ 支持滑块上文字显示（适合"是/否"单字）
• ✅ 多种动效：缩放弹回、水滴拉伸、拉丝效果
• ✅ 宽度自适应
• ✅ 可分别控制开启/关闭状态的文本颜色
• ✅ 自定义文本与滑块间距
• ✅ 自定义轨道左右内边距
• ✅ 完全自定义样式支持
• ✅ 多端兼容（H5、小程序、App）
• ✅ 无障碍访问支持

📦 安装

方式一：复制文件

将组件目录复制到 src/uni_modules/ 目录下即可。

🚀 使用

自动引入（推荐）

在 pages.json 中配置 easycom，组件会自动引入：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^hx-switch$": "@/uni_modules/hx-switch/components/hx-switch/hx-switch.vue"
    }
  }
}

基本用法

<template>
  <view>
    <!-- 基础开关 -->
    <hx-switch v-model="isOn" />

    <!-- 带文本的开关 -->
    <hx-switch v-model="isOn" text="已上架" />

    <!-- 带动效的开关 -->
    <hx-switch v-model="isOn" text="已上架" thumbEffect="stretch" :thumbScale="1.6" />
  </view>
</template>

<script setup>
import { ref } from 'vue'

const isOn = ref(true)
</script>

📋 Props

🎬 动效说明

📡 Events

🔧 示例

基础示例

<!-- 最简单的开关 -->
<hx-switch v-model="isOn" />

<!-- 改变大小 -->
<hx-switch v-model="isOn" :thumbSize="40" :thumbPadding="6" />

<!-- 改变圆角 -->
<hx-switch v-model="isOn" :trackBorderRadius="8" />

颜色配置

<!-- 自定义开/关颜色 -->
<hx-switch v-model="isOn" activeColor="#52C41A" inactiveColor="#BFBFBF" />

<!-- 红色危险开关 -->
<hx-switch v-model="isOn" activeColor="#FF4D4F" inactiveColor="#D9D9D9" />

<!-- 蓝色主题 -->
<hx-switch v-model="isOn" activeColor="#1890FF" inactiveColor="#D9D9D9" />

<!-- 紫色主题 -->
<hx-switch v-model="isOn" activeColor="#722ED1" inactiveColor="#D9D9D9" />

文本配置

<!-- 轨道内文本 -->
<hx-switch v-model="isOn" text="已上架" />

<!-- 动态文本 -->
<hx-switch v-model="status" :text="status ? '已上架' : '已下架'" />

<!-- 滑块上的文字 -->
<hx-switch v-model="agree" text="是" :textOnThumb="true" />

<!-- 分别控制开/关文本颜色 -->
<hx-switch 
  v-model="isOn" 
  text="状态"
  textOpenColor="#FFFFFF" 
  textCloseColor="#999999" 
/>

<!-- 调整文本与滑块间距 -->
<hx-switch v-model="isOn" text="开关" :textGap="10" />

<!-- 调整轨道内边距（文本与按钮边缘距离） -->
<hx-switch v-model="isOn" text="开关" :trackPadding="10" />

<!-- 同时调整多个间距参数 -->
<hx-switch v-model="isOn" text="开关" :textGap="8" :trackPadding="6" />

<!-- 自定义文本字号 -->
<hx-switch v-model="isOn" text="开关" :textSize="28" />

<!-- 自定义文本内边距 -->
<hx-switch v-model="isOn" text="开关" :textPadding="12" />

<!-- 完整文本样式配置 -->
<hx-switch 
  v-model="isOn" 
  text="已上架"
  textColor="#FFFFFF"
  textOpenColor="#00FF00"
  textCloseColor="#FF0000"
  :textSize="24"
  :textPadding="10"
  :textGap="6"
  :textStyle="{ fontWeight: 'bold' }"
/>

动效配置

<!-- 无动效 -->
<hx-switch v-model="isOn" thumbEffect="none" />

<!-- 缩放弹回 -->
<hx-switch v-model="isOn" thumbEffect="scale" :thumbScale="0.3" />

<!-- 水滴拉伸 -->
<hx-switch v-model="isOn" thumbEffect="droplet" :thumbScale="1.4" />

<!-- 拉丝效果 -->
<hx-switch v-model="isOn" thumbEffect="stretch" :thumbScale="1.6" />

<!-- 文本渐隐 -->
<hx-switch v-model="isOn" thumbEffect="fade" />

<!-- 不同强度的动效 -->
<hx-switch v-model="isOn" thumbEffect="scale" :thumbScale="0.5" />
<hx-switch v-model="isOn" thumbEffect="droplet" :thumbScale="1.8" />
<hx-switch v-model="isOn" thumbEffect="stretch" :thumbScale="2.0" />

禁用状态

<!-- 禁用开关 -->
<hx-switch v-model="isOn" :disabled="true" />

<!-- 禁用带文本 -->
<hx-switch v-model="isOn" text="已禁用" :disabled="true" />

自定义样式

<!-- 自定义滑块阴影 -->
<hx-switch v-model="isOn" thumbShadow="0 0 10rpx rgba(0,0,0,0.3)" />

<!-- 方角开关 -->
<hx-switch v-model="isOn"
  :trackBorderRadius="4"
  :thumbStyle="{ borderRadius: '4rpx' }" />

<!-- 渐变滑块 -->
<hx-switch v-model="isOn"
  :thumbStyle="{
    borderRadius: '6rpx',
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    boxShadow: 'none'
  }" />

<!-- 自定义轨道样式 -->
<hx-switch v-model="isOn"
  :trackStyle="{
    border: '2px solid #1890FF',
    opacity: 0.8
  }" />

<!-- 自定义滑块颜色 -->
<hx-switch v-model="isOn" thumbColor="#FFD700" />

<!-- 完整自定义样式 -->
<hx-switch v-model="isOn"
  :trackBorderRadius="12"
  :thumbSize="40"
  :thumbPadding="6"
  thumbColor="#FFFFFF"
  thumbShadow="0 4rpx 12rpx rgba(0,0,0,0.15)"
  :thumbStyle="{
    border: '2px solid #1890FF'
  }"
  :trackStyle="{
    background: 'linear-gradient(90deg, #1890FF, #70C0E1)'
  }" />

尺寸调整

<!-- 小号开关 -->
<hx-switch v-model="isOn" :thumbSize="24" :thumbPadding="2" />

<!-- 中号开关（默认） -->
<hx-switch v-model="isOn" :thumbSize="34" :thumbPadding="4" />

<!-- 大号开关 -->
<hx-switch v-model="isOn" :thumbSize="44" :thumbPadding="6" />

<!-- 超大号开关 -->
<hx-switch v-model="isOn" :thumbSize="54" :thumbPadding="8" />

圆角配置

<!-- 小圆角 -->
<hx-switch v-model="isOn" :trackBorderRadius="8" />

<!-- 中圆角（默认） -->
<hx-switch v-model="isOn" :trackBorderRadius="24" />

<!-- 大圆角 -->
<hx-switch v-model="isOn" :trackBorderRadius="32" />

<!-- 完全圆形 -->
<hx-switch v-model="isOn" :trackBorderRadius="999" />

<!-- 方角 -->
<hx-switch v-model="isOn"
  :trackBorderRadius="4"
  :thumbStyle="{ borderRadius: '4rpx' }" />

完整配置示例

<template>
  <view>
    <!-- 豪华配置开关 -->
    <hx-switch 
      v-model="premiumSwitch"
      text="高级功能"
      :textSize="26"
      :textPadding="12"
      :textGap="8"
      :trackPadding="10"
      :trackBorderRadius="28"
      activeColor="#10B981"
      inactiveColor="#DCDCDC"
      textColor="#FFFFFF"
      textOpenColor="#FFFFFF"
      textCloseColor="#999999"
      :thumbSize="40"
      :thumbPadding="6"
      thumbColor="#FFFFFF"
      thumbShadow="0 4rpx 16rpx rgba(0,0,0,0.2)"
      thumbEffect="stretch"
      :thumbScale="1.8"
      :textStyle="{ fontWeight: 'bold' }"
      :thumbStyle="{
        border: '2px solid #10B981'
      }"
      :trackStyle="{
        background: 'linear-gradient(90deg, #10B981, #34D399)'
      }"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'

const premiumSwitch = ref(true)
</script>

实际应用场景

<template>
  <view class="settings-list">
    <!-- 列表项开关 -->
    <view class="setting-item">
      <text class="label">通知开关</text>
      <hx-switch v-model="notifyEnabled" />
    </view>

    <!-- 带状态文本 -->
    <view class="setting-item">
      <text class="label">上架状态</text>
      <hx-switch 
        v-model="isOnShelf" 
        :text="isOnShelf ? '已上架' : '已下架'"
        :textGap="6"
      />
    </view>

    <!-- 滑块文字 -->
    <view class="setting-item">
      <text class="label">同意协议</text>
      <hx-switch 
        v-model="agreeTerms" 
        text="是" 
        :textOnThumb="true"
      />
    </view>

    <!-- 禁用状态 -->
    <view class="setting-item">
      <text class="label">高级功能</text>
      <hx-switch 
        v-model="premiumFeature" 
        :disabled="!isPremiumUser"
        :text="isPremiumUser ? '可用' : '不可用'"
      />
    </view>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const notifyEnabled = ref(true)
const isOnShelf = ref(true)
const agreeTerms = ref(false)
const premiumFeature = ref(false)
const isPremiumUser = ref(true)
</script>

<style scoped>
.settings-list {
  padding: 20rpx;
}

.setting-item {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 20rpx 0;
  border-bottom: 1rpx solid #EEEEEE;
}

.label {
  font-size: 28rpx;
  color: #333333;
}
</style>

🔄 宽度自适应

🌐 兼容性

📄 License

MIT

📝 更新日志

v1.0.1

• 新增 textGap 参数：控制文本与滑块之间的间距
• 新增 textOpenColor/textCloseColor 参数：分别控制开启/关闭状态的文本颜色
• 新增 trackPadding 参数：控制文本与按钮边缘的距离
• 修复动效被打断的问题
• 优化滑块位置计算逻辑

v1.0.0

• 初始版本
• 支持轨道内文本和滑块上文本
• 支持多种动效
• 支持自定义样式
• 多端兼容