开关 switch

数据录入组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

不传 checked 即为非受控，开关自己维护状态

<script setup lang="ts">
import { XhSwitch } from "@xihan-ui/vue";
</script>

<template>
  <XhSwitch />
  <XhSwitch default-checked />
</template>

受控

传了 checked 就由宿主说了算，组件自己不再改状态；v-model:checked 是它的语法糖

当前：开

<script setup lang="ts">
import { ref } from "vue";
import { XhSwitch } from "@xihan-ui/vue";

const checked = ref(true);
</script>

<template>
  <XhSwitch v-model:checked="checked" />
  <span>当前：{{ checked ? "开" : "关" }}</span>
</template>

禁用

disabled 同时挡住指针与键盘，状态机收不到 TOGGLE

<script setup lang="ts">
import { XhSwitch } from "@xihan-ui/vue";
</script>

<template>
  <XhSwitch disabled />
  <XhSwitch disabled default-checked />
</template>

语气

tone 决定选中态轨道用哪族颜色，所以这里都置为开

brandneutralsuccesswarningdangerinfo

<script setup lang="ts">
import { XhSwitch } from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px; flex-wrap: wrap">
    <span v-for="t in tones" :key="t" style="display: inline-flex; align-items: center; gap: 6px">
      <XhSwitch :tone="t" default-checked />
      <span>{{ t }}</span>
    </span>
  </div>
</template>

尺寸

size 同时缩放轨道与滑块，不写就是缺省档

小缺省大

<script setup lang="ts">
import { XhSwitch } from "@xihan-ui/vue";
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhSwitch size="sm" default-checked />
      <span>小</span>
    </span>
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhSwitch default-checked />
      <span>缺省</span>
    </span>
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhSwitch size="lg" default-checked />
      <span>大</span>
    </span>
  </div>
</template>

事件

checked-change 带一份 { checked }，非受控时内部转移也照发一次

翻转 0 次 · 最近落到 （还没动过）

<script setup lang="ts">
import { ref } from "vue";
import { XhSwitch } from "@xihan-ui/vue";

const times = ref(0);
const last = ref("（还没动过）");

function onCheckedChange(details: { checked: boolean }) {
  times.value += 1;
  last.value = details.checked ? "开" : "关";
}
</script>

<template>
  <XhSwitch @checked-change="onCheckedChange" />
  <span>翻转 {{ times }} 次 · 最近落到 {{ last }}</span>
</template>

自定义颜色

开态轨道、关态轨道与滑块各是一个组件令牌，语气档之外的配色写在行内

<script setup lang="ts">
import { XhSwitch } from "@xihan-ui/vue";
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px; flex-wrap: wrap">
    <!-- 只换开态轨道色 -->
    <XhSwitch default-checked style="--xh-switch-bg-checked: #16a34a" />

    <!-- 开关两态各给一色 -->
    <XhSwitch style="--xh-switch-bg: #2080f0; --xh-switch-bg-checked: #d03050" />

    <!-- 滑块也是一个令牌，可以和轨道拉开对比 -->
    <XhSwitch
      default-checked
      style="--xh-switch-bg-checked: #1f2937; --xh-switch-thumb: #facc15"
    />
  </div>
</template>

轨道内文案与滑块标记

自渲外壳时子节点全由作者决定，data-state 同时打在轨道与滑块上

<script setup lang="ts">
import { useSwitch } from "@xihan-ui/vue";

const { api: trackApi } = useSwitch({ defaultChecked: true });
const { api: markApi } = useSwitch({});
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px; flex-wrap: wrap">
    <!-- 文案与滑块同为轨道的直接子节点：开态文案在左、滑块在右，关态反过来 -->
    <button
      v-bind="trackApi.getRootProps()"
      style="
        inline-size: auto;
        min-inline-size: 64px;
        justify-content: space-between;
        gap: 6px;
        padding-inline: 8px;
      "
    >
      <span v-if="trackApi.checked" style="font-size: 12px; color: var(--xh-fg-on-brand)">
        开
      </span>
      <span v-bind="trackApi.getThumbProps()" style="translate: none" />
      <span v-if="!trackApi.checked" style="font-size: 12px">关</span>
    </button>

    <!-- 滑块里也能放东西：属性来自 getThumbProps，内容照写不误 -->
    <button v-bind="markApi.getRootProps()">
      <span
        v-bind="markApi.getThumbProps()"
        style="display: inline-flex; align-items: center; justify-content: center; font-size: 11px"
      >
        {{ markApi.checked ? "✓" : "✕" }}
      </span>
    </button>
  </div>
</template>

异步提交

受控开关在回执到达前不落位，提交期间 disabled 挡住重复点击

已关闭

<script setup lang="ts">
import { ref } from "vue";
import { XhSpinner, XhSwitch } from "@xihan-ui/vue";

const enabled = ref(false);
const pending = ref(false);

// 回执到达才写回 checked，中途开关停在旧值上
function onCheckedChange(details: { checked: boolean }) {
  pending.value = true;
  setTimeout(() => {
    enabled.value = details.checked;
    pending.value = false;
  }, 900);
}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 10px">
    <XhSwitch :checked="enabled" :disabled="pending" @checked-change="onCheckedChange" />
    <XhSpinner v-if="pending" size="sm" label="提交中" />
    <span v-else>{{ enabled ? "已开启" : "已关闭" }}</span>
  </div>
</template>

形状

轨道与滑块共用同一个形状令牌，在实例上覆盖一次两者一起变方

直角圆角缺省

<script setup lang="ts">
import { XhSwitch } from "@xihan-ui/vue";
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhSwitch default-checked style="--xh-shape-pill: 0" />
      <span>直角</span>
    </span>
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhSwitch default-checked style="--xh-shape-pill: 5px" />
      <span>圆角</span>
    </span>
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhSwitch default-checked />
      <span>缺省</span>
    </span>
  </div>
</template>

随表单提交

给了 name 才生出表单影子：开着才提交，值缺省是 on，与原生复选框一致

接收通知（开着，提交 notify=on） 加入内测（没开就整条不进 FormData） 深色主题（提交 theme=dark）

<script setup lang="ts">
import { XhButton, XhSwitch } from "@xihan-ui/vue";
import { ref } from "vue";

const submitted = ref("");

function onSubmit(event: Event) {
  const data = new FormData(event.target as HTMLFormElement);
  const keys = [...data.entries()].map(([k, v]) => `${k}=${v}`);
  submitted.value = keys.length ? keys.join("  ") : "（一个字段都没提交）";
}
</script>

<template>
  <form style="display: grid; gap: 12px" @submit.prevent="onSubmit">
    <label><XhSwitch name="notify" default-checked /> 接收通知（开着，提交 notify=on）</label>
    <label><XhSwitch name="beta" /> 加入内测（没开就整条不进 FormData）</label>
    <!-- value 换掉默认的 on -->
    <label><XhSwitch name="theme" value="dark" default-checked /> 深色主题（提交 theme=dark）</label>

    <div>
      <XhButton type="submit" size="sm">提交</XhButton>
    </div>

    <span v-if="submitted">表单收到：{{ submitted }}</span>
  </form>
</template>

产物

层	值
自定义元素	<xh-switch>
Vue 组件	XhSwitch
组合式函数	useSwitch
状态机	switchMachine
皮肤	@xihan-ui/styles/switch.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="switch"：root · thumb · hidden-input

Props

属性	类型	必填	说明
checked	boolean
defaultChecked	boolean
disabled	boolean
name	string		表单字段名；给了 hidden-input 才带 name 并参与提交。
value	string		提交出去的值，缺省 'on'，与原生复选框一致。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定选中态轨道用哪族颜色。
size	Size		尺寸：sm / md / lg，决定轨道与滑块的几何档位。
onCheckedChange	(details: SwitchCheckedChangeDetails) => void		checked 变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。

状态机

状态：off · on

事件：TOGGLE · CONTROLLED.ON · CONTROLLED.OFF · FORM.RESET

判据：isCheckedControlled · defaultsToChecked

connect API

useSwitch 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
checked	boolean
setChecked	(next: boolean) => void
getRootProps	() => T['button']
getThumbProps	() => T['element']
getHiddenInputProps	() => T['input']	表单影子：勾上才提交。给了 name 才带 name，不给就不参与提交。

键盘

规格出处：W3C APG

按键	生效条件	行为
Space / Enter	focus in root, not disabled	切换 checked 状态