X-Next

Appearance

Switch 开关 ​

用于表达启用/停用、打开/关闭这类二元状态。

基础用法 ​

已关闭
vue
<template>
  <x-switch v-model="enabled" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const enabled = ref(false);
</script>

文案和自定义值 ​

enabled
vue
<template>
  <x-switch
    v-model="status"
    checked-value="enabled"
    unchecked-value="disabled"
    checked-text="开"
    unchecked-text="关"
  />
  <span>{{ status }}</span>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const status = ref<'enabled' | 'disabled'>('enabled');
</script>

类型 ​

vue
<template>
  <x-switch v-model="enabled" type="circle" />
  <x-switch v-model="enabled" type="round" />
  <x-switch v-model="enabled" type="line" />
</template>

尺寸 ​

vue
<template>
  <x-switch v-model="enabled" size="medium" checked-text="开" unchecked-text="关" />
  <x-switch v-model="enabled" size="medium" checked-text="启用" unchecked-text="停用" />
  <x-switch v-model="enabled" size="small" />
  <x-switch v-model="enabled" size="small" checked-text="开" unchecked-text="关" />
</template>

禁用 ​

vue
<template>
  <x-switch disabled />
  <x-switch :model-value="true" disabled />
</template>

加载中 ​

vue
<template>
  <x-switch loading />
  <x-switch :model-value="true" loading />
</template>

自定义颜色 ​

vue
<template>
  <x-switch
    v-model="enabled"
    checked-color="#0f766e"
    unchecked-color="#94a3b8"
    checked-text="启用"
    unchecked-text="停用"
  />
  <x-switch
    v-model="enabled"
    type="line"
    checked-color="#0f766e"
    unchecked-color="#94a3b8"
  />
</template>

切换前校验 ​

异步校验期间会自动显示 loading，只允许切换到开启
vue
<template>
  <x-switch v-model="enabled" :before-change="beforeChange" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const enabled = ref(false);
const beforeChange = async (nextValue: boolean | string | number) => {
  await new Promise((resolve) => window.setTimeout(resolve, 600));
  return nextValue === true;
};
</script>

自定义图标 ​

vue
<template>
  <x-switch v-model="enabled">
    <template #checked-icon>✓</template>
    <template #unchecked-icon>×</template>
  </x-switch>
</template>

事件回调 ​

等待操作
vue
<template>
  <x-switch v-model="enabled" @change="handleChange" @click="handleClick" />
  <span>{{ eventLog }}</span>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const enabled = ref(false);
const eventLog = ref('等待操作');
const clickCount = ref(0);
const handleChange = (value: boolean | string | number) => {
  eventLog.value = `当前值：${value}`;
};
const handleClick = (value: boolean | string | number) => {
  clickCount.value += 1;
  eventLog.value = `点击第 ${clickCount.value} 次，目标值：${value}`;
};
</script>

原生属性 ​

支持 id、name、tabindex、aria-* 等原生 button 属性透传
vue
<template>
  <x-switch
    id="notification-switch"
    name="notification"
    autofocus
    aria-label="通知开关"
  />
</template>

方法 ​

vue
<template>
  <x-switch ref="switchRef" v-model="enabled" />
  <x-button @click="switchRef?.focus()">聚焦</x-button>
  <x-button @click="switchRef?.blur()">失焦</x-button>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const enabled = ref(false);
const switchRef = ref();
</script>

按需导入 ​

ts
import { Switch } from 'x-next';

Props ​

参数说明类型默认值
modelValue绑定值string | number | booleanundefined
defaultChecked默认选中状态，非受控模式booleanfalse
disabled是否禁用booleanfalse
loading是否加载中booleanfalse
autofocus是否自动获取焦点booleanfalse
type开关类型'circle' | 'round' | 'line''circle'
size开关尺寸'small' | 'medium'跟随全局配置
checkedValue选中时的值string | number | booleantrue
uncheckedValue未选中时的值string | number | booleanfalse
checkedColor选中时颜色string-
uncheckedColor未选中时颜色string-
beforeChange切换前钩子，返回 false 或 Promise reject 时阻止切换(value) => boolean | void | Promise<boolean | void>-
checkedText选中时文案，type="line" 时不显示string-
uncheckedText未选中时文案，type="line" 时不显示string-

Events ​

事件名说明回调参数
update:modelValue值更新时触发value
change值变化时触发value, event
click点击时触发，返回本次尝试切换的目标值value, event
focus获取焦点时触发event
blur失去焦点时触发event

Slots ​

插槽名说明
checked选中时文案
unchecked未选中时文案
checked-icon选中时按钮图标
unchecked-icon未选中时按钮图标

Methods ​

方法名说明
focus()聚焦开关
blur()取消聚焦