@qi-tian-da-sheng/bin-project-ui 1.0.0

package/packages/components/switch/__tests__/switch.spec.ts

@@ -0,0 +1,259 @@
+/**
+ * @description Switch 组件测试
+ * @author MC.Yang
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { nextTick } from 'vue'
+import Switch from '../src/switch.vue'
+import { hasClass } from '../../__tests__/utils'
+
+describe('Switch', () => {
+  describe('基础功能', () => {
+    it('应该正确渲染', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+        },
+      })
+      expect(wrapper.find('.p-switch').exists()).toBe(true)
+      expect(wrapper.find('.p-switch__inner').exists()).toBe(true)
+      expect(wrapper.find('.p-switch__trigger').exists()).toBe(true)
+    })
+
+    it('应该正确显示选中状态', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: true,
+        },
+      })
+      expect(hasClass(wrapper, 'is-checked')).toBe(true)
+    })
+
+    it('应该正确显示未选中状态', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+        },
+      })
+      expect(hasClass(wrapper, 'is-checked')).toBe(false)
+    })
+  })
+
+  describe('Props', () => {
+    it('disabled 属性应该禁用开关', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          disabled: true,
+        },
+      })
+      expect(hasClass(wrapper, 'is-disabled')).toBe(true)
+    })
+
+    it('loading 属性应该显示加载状态', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          loading: true,
+        },
+      })
+      expect(hasClass(wrapper, 'is-loading')).toBe(true)
+      const icons = wrapper.findAllComponents({ name: 'PIcon' })
+      const loadingIcon = icons.find(icon => icon.props('target') === 'loading')
+      expect(loadingIcon).toBeDefined()
+      if (loadingIcon) {
+        expect(loadingIcon.props('rotating')).toBe(true)
+      }
+    })
+
+    it('size 属性应该生效', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          size: 'large',
+        },
+      })
+      expect(hasClass(wrapper, 'p-switch--large')).toBe(true)
+    })
+
+    it('activeText 和 inactiveText 应该正确显示', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          activeText: '开启',
+          inactiveText: '关闭',
+          textStatus: 'outside',
+        },
+      })
+      expect(wrapper.text()).toContain('开启')
+      expect(wrapper.text()).toContain('关闭')
+    })
+
+    it('textStatus 为 inside 时应该在内部显示文本', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          activeText: 'ON',
+          inactiveText: 'OFF',
+          textStatus: 'inside',
+        },
+      })
+      const innerText = wrapper.find('.p-switch__text')
+      expect(innerText.exists()).toBe(true)
+    })
+
+    it('activeIcon 应该在选中状态显示', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: true,
+          activeIcon: 'check',
+          textStatus: 'outside',
+        },
+      })
+      const icons = wrapper.findAllComponents({ name: 'PIcon' })
+      const activeIcon = icons.find(icon => icon.props('target') === 'check')
+      expect(activeIcon).toBeDefined()
+    })
+
+    it('inactiveIcon 应该在未选中状态显示', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          inactiveIcon: 'close',
+          textStatus: 'outside',
+        },
+      })
+      const icons = wrapper.findAllComponents({ name: 'PIcon' })
+      const inactiveIcon = icons.find(icon => icon.props('target') === 'close')
+      expect(inactiveIcon).toBeDefined()
+    })
+
+    it('triggerIcon 应该在滑块上显示', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          triggerIcon: 'star',
+        },
+      })
+      const triggerIcon = wrapper.find('.p-switch__trigger__icon')
+      expect(triggerIcon.exists()).toBe(true)
+    })
+
+    it('color 属性应该自定义颜色', async () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: true,
+          color: '#ff0000',
+        },
+      })
+      const style = wrapper.attributes('style')
+      expect(style).toContain('--pixel-switch-color')
+      expect(style).toContain('#ff0000')
+    })
+
+    it('type 属性应该设置主题色', async () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: true,
+          type: 'success',
+        },
+      })
+      const style = wrapper.attributes('style')
+      expect(style).toContain('--pixel-switch-color')
+    })
+  })
+
+  describe('事件', () => {
+    it('点击应该切换状态', async () => {
+      const onUpdateModelValue = vi.fn()
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          'onUpdate:modelValue': onUpdateModelValue,
+        },
+      })
+
+      await wrapper.trigger('click')
+      expect(onUpdateModelValue).toHaveBeenCalledWith(true)
+    })
+
+    it('change 事件应该正确触发', async () => {
+      const onChange = vi.fn()
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          onChange,
+        },
+      })
+
+      await wrapper.trigger('click')
+      expect(onChange).toHaveBeenCalledWith('on')
+
+      await wrapper.setProps({ modelValue: true })
+      await wrapper.trigger('click')
+      expect(onChange).toHaveBeenCalledWith('off')
+    })
+
+    it('禁用状态下不应该切换', async () => {
+      const onUpdateModelValue = vi.fn()
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          disabled: true,
+          'onUpdate:modelValue': onUpdateModelValue,
+        },
+      })
+
+      await wrapper.trigger('click')
+      expect(onUpdateModelValue).not.toHaveBeenCalled()
+    })
+
+    it('加载状态下不应该切换', async () => {
+      const onUpdateModelValue = vi.fn()
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+          loading: true,
+          'onUpdate:modelValue': onUpdateModelValue,
+        },
+      })
+
+      await wrapper.trigger('click')
+      expect(onUpdateModelValue).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('组合场景', () => {
+    it('应该支持同时设置多个属性', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: true,
+          size: 'large',
+          disabled: true,
+          activeText: '开',
+          inactiveText: '关',
+        },
+      })
+
+      expect(hasClass(wrapper, 'is-checked')).toBe(true)
+      expect(hasClass(wrapper, 'is-disabled')).toBe(true)
+      expect(hasClass(wrapper, 'p-switch--large')).toBe(true)
+    })
+  })
+
+  describe('可访问性', () => {
+    it('应该正确渲染可交互元素', () => {
+      const wrapper = mount(Switch, {
+        props: {
+          modelValue: false,
+        },
+      })
+
+      // Switch 应该有基本的可交互结构
+      expect(wrapper.find('.p-switch').exists()).toBe(true)
+      expect(wrapper.find('.p-switch__inner').exists()).toBe(true)
+      expect(wrapper.find('.p-switch__trigger').exists()).toBe(true)
+    })
+  })
+})

package/packages/components/switch/index.ts

@@ -0,0 +1,13 @@
+/*
+ * @description: 开关
+ * @author: MC.Yang
+ */
+import _Switch from "./src/switch.vue";
+import {withInstall} from "@bin-ui/tools";
+
+const Switch = withInstall(_Switch);
+
+export type PSwitchInstance = InstanceType<typeof _Switch>;
+
+export default {Switch};
+export {Switch};

package/packages/components/switch/src/switch-txt.vue

@@ -0,0 +1,61 @@
+<template>
+	<span ref="txt">
+		{{ props.txt }}
+	</span>
+</template>
+
+<script setup lang="ts">
+import {ref, watch} from "vue";
+import {unrefElement} from "@vueuse/core";
+
+const props = defineProps({
+  active: Boolean,
+  txt: String,
+})
+
+const txt = ref<HTMLElement | null>(null);
+
+const leftKeyframes: Keyframe[] = [
+  {
+    opacity: '0',
+    transform: 'translateX(15px)',
+  },
+  {
+    opacity: '1',
+    transform: 'translateX(0)',
+  }
+]
+
+const rightKeyframes: Keyframe[] = [
+  {
+    opacity: '0',
+    transform: 'translateX(-15px)',
+
+  },
+  {
+    opacity: '1',
+    transform: 'translateX(0)',
+  }
+]
+
+watch(() => props.active, (active) => {
+  const el = unrefElement(txt);
+  if (!el) return;
+  if (active) {
+    el.animate(leftKeyframes, {
+      duration: 200,
+      fill: 'forwards',
+      easing: 'linear'
+    })
+  } else {
+    el.animate(rightKeyframes, {
+      duration: 200,
+      fill: 'forwards',
+      easing: 'linear'
+    })
+  }
+}, {immediate: false});
+
+</script>
+
+

package/packages/components/switch/src/switch.ts

@@ -0,0 +1,225 @@
+/**
+ * @file Switch 开关组件的类型定义文件
+ * @description 定义开关组件的所有属性、事件和类型
+ * @author MC.Yang
+ * @see {@link https://tdesign.tencent.com/vue-next/components/switch TDesign Switch}
+ */
+import { PropType } from "vue";
+import { ElementSizes, ElementTypes } from "@bin-ui/typings";
+
+/**
+ * 开关组件属性定义
+ * @description 包含开关的所有可配置属性
+ * @example
+ * ```vue
+ * <p-switch
+ *   v-model="value"
+ *   size="large"
+ *   active-text="开启"
+ *   inactive-text="关闭"
+ *   :loading="isLoading"
+ * />
+ * ```
+ */
+export const PSwitchProps = {
+
+    /**
+     * @property {boolean} modelValue - 开关的绑定值
+     * @description 控制开关的开/关状态
+     * @default false
+     * @example
+     * <p-switch v-model="isOpen" />
+     * // isOpen: true - 开启, false - 关闭
+     */
+    modelValue: Boolean,
+
+    /**
+     * @property {ElementSizes} size - 组件大小（高度）
+     * @description 控制开关的尺寸大小
+     * @default undefined (默认尺寸)
+     * @values 'small' | 'large'
+     * @example
+     * <p-switch size="small" />
+     * <p-switch size="large" />
+     */
+    size: String as PropType<ElementSizes>,
+    
+    /**
+     * @property {ElementTypes | 'cyan'} type - 开关的类型主题
+     * @description 控制开关开启状态的颜色主题
+     * @default undefined (默认 primary)
+     * @values 'success' | 'info' | 'warning' | 'danger' | 'cyan'
+     * @example
+     * <p-switch type="success" />
+     * <p-switch type="danger" />
+     */
+    type: String as PropType<ElementTypes | 'cyan'>,
+
+    /**
+     * @property {string} inactiveText - 开关关闭状态时的文字
+     * @description 开关状态为 off 时显示的文本
+     * @default undefined
+     * @example
+     * <p-switch inactive-text="关闭" />
+     */
+    inactiveText: String,
+
+    /**
+     * @property {string} activeText - 开关开启状态时的文字
+     * @description 开关状态为 on 时显示的文本
+     * @default undefined
+     * @example
+     * <p-switch active-text="开启" inactive-text="关闭" />
+     */
+    activeText: String,
+
+    /**
+     * @property {string} inactiveIcon - 开关关闭状态时的图标
+     * @description 开关状态为 off 时显示的图标名称
+     * @default undefined
+     * @example
+     * <p-switch inactive-icon="close" active-icon="check" />
+     */
+    inactiveIcon: String,
+
+    /**
+     * @property {string} activeIcon - 开关开启状态时的图标
+     * @description 开关状态为 on 时显示的图标名称
+     * @default undefined
+     * @example
+     * <p-switch active-icon="check" />
+     */
+    activeIcon: String,
+
+    /**
+     * @property {string} triggerIcon - 开关滑块中的图标
+     * @description 显示在开关滑块中心的图标名称
+     * @default undefined
+     * @example
+     * <p-switch trigger-icon="star" />
+     */
+    triggerIcon: String,
+
+    /**
+     * @property {string} color - 开关的自定义颜色
+     * @description 自定义开关开启状态的颜色，优先级高于 type
+     * @default undefined
+     * @example
+     * <p-switch color="#67C23A" />
+     * <p-switch color="var(--custom-color)" />
+     */
+    color: String,
+
+    /**
+     * @property {boolean} disabled - 是否禁用开关
+     * @description 禁用后开关不可点击，且显示禁用样式
+     * @default false
+     * @example
+     * <p-switch :disabled="true" />
+     */
+    disabled: Boolean,
+
+    /**
+     * @property {boolean} loading - 是否处于加载中
+     * @description 加载状态下显示加载图标，开关不可点击
+     * @default false
+     * @example
+     * <p-switch :loading="isSubmitting" />
+     */
+    loading: Boolean,
+
+    /**
+     * @property {string} textStatus - 文本显示位置
+     * @description 控制 on/off 文本是否显示在开关轨道内部
+     * @default undefined (显示在外部)
+     * @values 'inside' | 'outside'
+     * - inside: 文本显示在轨道内，会忽略图标
+     * - outside: 文本显示在轨道外两侧
+     * @example
+     * <p-switch text-status="inside" active-text="ON" inactive-text="OFF" />
+     */
+    textStatus: String as PropType<'inside' | 'outside'>,
+
+    /**
+     * @property {Function} beforeChange - 开关状态改变前的回调
+     * @description 异步控制开关状态的切换，需要手动调用 done 函数
+     * @default undefined
+     * @param {Function} done - 完成状态切换的函数
+     * @example
+     * ```vue
+     * <p-switch
+     *   v-model="value"
+     *   :before-change="handleBeforeChange"
+     * />
+     * 
+     * <script setup>
+     * const handleBeforeChange = (done) => {
+     *   // 执行异步操作，如 API 请求
+     *   fetch('/api/toggle')
+     *     .then(() => {
+     *       done()  // 成功后切换状态
+     *     })
+     *     .catch(() => {
+     *       // 失败时不调用 done，状态不变
+     *     })
+     * }
+     * </script>
+     * ```
+     */
+    beforeChange: Function as PropType<(done: () => void) => void>
+
+}
+
+/**
+ * 开关组件触发事件定义
+ * @interface PSwitchEmits
+ * @description 定义开关组件可以发出的所有事件
+ * @example
+ * ```vue
+ * <p-switch
+ *   v-model="value"
+ *   @change="handleChange"
+ * />
+ * 
+ * <script setup>
+ * const handleChange = (status) => {
+ *   console.log('开关状态变为:', status)  // 'on' 或 'off'
+ * }
+ * </script>
+ * ```
+ */
+export interface PSwitchEmits {
+
+    /**
+     * 更新绑定值
+     * @event update:modelValue
+     * @param {boolean} value - 新的绑定值
+     * @description v-model 双向绑定的更新事件
+     * @example
+     * <p-switch v-model="isOpen" />
+     */
+    (e: 'update:modelValue', value: boolean): void;
+
+    /**
+     * 开关状态改变事件
+     * @event change
+     * @param {string} status - 开关状态 'on' 或 'off'
+     * @description 当开关状态发生改变时触发
+     * @example
+     * ```vue
+     * <p-switch @change="handleChange" />
+     * 
+     * <script setup>
+     * const handleChange = (status) => {
+     *   if (status === 'on') {
+     *     console.log('开关已开启')
+     *   } else {
+     *     console.log('开关已关闭')
+     *   }
+     * }
+     * </script>
+     * ```
+     */
+    (e: 'change', status: 'off' | 'on'): void;
+
+}

package/packages/components/switch/src/switch.vue

@@ -0,0 +1,152 @@
+<!--
+  @component Switch 开关组件
+  @description 表示两种相互对立的状态间的切换，常用于触发「开/关」操作
+  @author MC.Yang
+  @example
+  <p-switch v-model="value" />
+  <p-switch v-model="value" active-text="开启" inactive-text="关闭" />
+  <p-switch v-model="value" :loading="true" />
+-->
+<template>
+  <div
+      :class="classes"
+      :style="style"
+      @click="handleClick"
+  >
+    <!-- 隐藏的原生 radio 输入框，用于表单提交和语义化 -->
+    <input :class="ns.e('input')" type="radio" placeholder="ヾ(≧▽≦*)o">
+
+    <!-- 左侧标签文本（关闭状态） -->
+    <span
+        v-if="props.textStatus !== 'inside'"
+        :class="[
+				ns.e('label'),
+				ns.em('label', 'left'),
+				ns.is('active', !props.modelValue)
+			]"
+    >
+			<p-icon :target="props.inactiveIcon"></p-icon>
+			{{ props.inactiveText }}
+		</span>
+
+    <!-- 开关主体内部轨道 -->
+    <div
+        :class="[
+				 ns.e('inner'),
+				 ns.is('round')
+		     ]"
+        v-bind="$attrs"
+    >
+			<!-- 开关滑块 -->
+			<span :class="[
+					 ns.e('trigger'),
+					 ns.is('round')
+				   ]"
+      >
+				<!-- 滑块中的自定义图标 -->
+				<p-icon
+            v-if="props.triggerIcon && !props.loading"
+            class="p-switch__trigger__icon"
+            :target="props.triggerIcon"
+        ></p-icon>
+				<!-- 加载状态图标 -->
+				<p-icon v-if="props.loading" target="loading" rotating></p-icon>
+			</span>
+
+      <!-- 内部文本（在轨道内显示开/关文字） -->
+      <switch-txt
+          v-if="props.textStatus === 'inside'"
+          :class="ns.e('text')"
+          :txt="text"
+          :active="props.modelValue"
+      ></switch-txt>
+
+    </div>
+
+    <!-- 右侧标签文本（开启状态） -->
+    <span
+        v-if="props.textStatus !== 'inside'"
+        :class="[
+				ns.e('label'),
+				ns.em('label', 'right'),
+				ns.is('active', props.modelValue)
+			]"
+    >
+			<p-icon :target="props.activeIcon"></p-icon>
+			{{ props.activeText }}
+		</span>
+  </div>
+</template>
+<script setup lang="ts">
+import { computed } from "vue";
+import switchTxt from "./switch-txt.vue";
+import PIcon from "../../icon/src/icon.vue";
+import { PSwitchEmits, PSwitchProps } from "./switch";
+import { useNS } from "@bin-ui/hooks";
+import { getClrVar } from "@bin-ui/tools";
+
+// 组件配置
+defineOptions({
+  name: 'PSwitch',
+  inheritAttrs: false
+})
+
+// BEM 命名空间工具
+const ns = useNS('switch');
+
+// 组件属性
+const props = defineProps({...PSwitchProps});
+
+// 组件事件
+const emits = defineEmits<PSwitchEmits>();
+
+// 计算开关的 CSS 类名数组
+const classes = computed(() => {
+  return [
+    ns.namespace,
+    ns.is('checked', props.modelValue),
+    ns.is('disabled', props.disabled),
+    ns.is('loading', props.loading),
+    ns.m(props.size),
+  ]
+})
+
+// 计算开关的动态样式
+const style = computed(() => {
+  const color = props.color ? props.color : props.type ? getClrVar(props.type) : getClrVar('primary');
+  return {
+    [ns.cssVar('color')]: color
+  }
+})
+
+// 计算当前显示的文本
+const text = computed(() => {
+  if (props.modelValue) {
+    return props.activeText;
+  } else {
+    return props.inactiveText;
+  }
+})
+
+// 处理开关点击事件
+const handleClick = () => {
+  const done = () => {
+    if (props.loading || props.disabled) return
+    
+    if (props.modelValue) {
+      emits("update:modelValue", false);
+      emits("change", "off")
+    } else {
+      emits("update:modelValue", true);
+      emits("change", "on");
+    }
+  }
+
+  props.beforeChange && props.beforeChange(done);
+  props.beforeChange || done();
+}
+
+</script>
+
+
+