切换按钮 toggle

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

示例

基础用法

按下态由 pressed 表达，非受控时组件自己维护

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

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

<template>
  <XhToggle>加粗</XhToggle>
  <XhToggle v-model:pressed="bold">受控：{{ bold ? "已按下" : "未按下" }}</XhToggle>
</template>

禁用

disabled 同时挡住指针与键盘，按下态保持原样

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

<template>
  <XhToggle disabled>未按下</XhToggle>
  <XhToggle disabled default-pressed>已按下</XhToggle>
</template>

排成一组

多个独立的 toggle 各管各的按下态；要互斥或单一 Tab 位请改用切换按钮组

underline

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

const marks = ref({ bold: false, italic: false, underline: true });
</script>

<template>
  <XhToggle v-model:pressed="marks.bold">B</XhToggle>
  <XhToggle v-model:pressed="marks.italic">I</XhToggle>
  <XhToggle v-model:pressed="marks.underline">U</XhToggle>
  <span>{{ Object.entries(marks).filter(([, on]) => on).map(([k]) => k).join(" ") || "无" }}</span>
</template>

形态

variant 决定颜色怎么用，未按下与已按下两档一起看才完整

未按下

已按下

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

const variants = ["solid", "subtle", "outline", "ghost"] as const;
</script>

<template>
  <div style="display: grid; gap: 8px">
    <div style="display: flex; align-items: center; gap: 8px">
      <span style="min-width: 64px">未按下</span>
      <XhToggle v-for="v in variants" :key="v" :variant="v">{{ v }}</XhToggle>
    </div>
    <div style="display: flex; align-items: center; gap: 8px">
      <span style="min-width: 64px">已按下</span>
      <XhToggle v-for="v in variants" :key="v" :variant="v" default-pressed>{{ v }}</XhToggle>
    </div>
  </div>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 solid 形态并置于按下态，语气差别最明显

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

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

<template>
  <XhToggle v-for="t in tones" :key="t" variant="solid" :tone="t" default-pressed>{{ t }}</XhToggle>
</template>

尺寸

size 只改高度、内边距与字号，不写就是缺省档

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

<template>
  <div style="display: flex; align-items: center; gap: 8px">
    <XhToggle variant="outline" size="sm">小</XhToggle>
    <XhToggle variant="outline">缺省</XhToggle>
    <XhToggle variant="outline" size="lg">大</XhToggle>
  </div>
</template>

图标

默认插槽收任意内容，图标与文字之间的空隙由 --xh-toggle-gap 给；只放图标时按钮没有可见文字，名字得由 aria-label 补上

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

const StarIcon = {
  name: "star",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "path", attrs: { d: "M12 4L14.4 8.9L19.8 9.7L15.9 13.5L16.8 18.9L12 16.4L7.2 18.9L8.1 13.5L4.2 9.7L9.6 8.9Z" } },
  ],
} as const;

const EyeIcon = {
  name: "eye",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "path", attrs: { d: "M2 12C4.7 7.7 8 5.5 12 5.5C16 5.5 19.3 7.7 22 12C19.3 16.3 16 18.5 12 18.5C8 18.5 4.7 16.3 2 12Z" } },
    { tag: "circle", attrs: { cx: "12", cy: "12", r: "3" } },
  ],
} as const;

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

<template>
  <!-- 图标配文字：文字自己说清楚这颗按钮是干什么的，图标不必再给名字 -->
  <XhToggle v-model:pressed="starred" variant="outline">
    <XhIcon :icon="StarIcon" />{{ starred ? "已收藏" : "收藏" }}
  </XhToggle>

  <!-- 只放图标：内边距收窄成方形，名字由 aria-label 给 -->
  <XhToggle
    variant="outline"
    aria-label="显示预览"
    style="--xh-toggle-px: var(--xh-space-2);"
  >
    <XhIcon :icon="EyeIcon" />
  </XhToggle>
</template>

变化回调

pressed-change 每次带着 details 报一次按下意图；不接 v-model 时它就是拿到新值的唯一出口

最近三次：（还没动过）

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

const trail = ref<string[]>([]);

function onPressedChange(details: { pressed: boolean }) {
  // 只留最近三次
  trail.value = [details.pressed ? "开" : "关", ...trail.value].slice(0, 3);
}
</script>

<template>
  <XhToggle variant="outline" @pressed-change="onPressedChange">静音</XhToggle>
  <span style="font-size: 13px;">
    最近三次：{{ trail.join(" · ") || "（还没动过）" }}
  </span>
</template>

请求在途

受控的 pressed 不写回就不会动，在途期间来的意图直接丢掉；忙碌反馈由 aria-busy 与一枚转圈补在按钮上

点一下，落定要等 1.2 秒

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

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

function onPressedChange(details: { pressed: boolean }): void {
  // 在途期间不写回 pressed，按钮就停在原来的按下态上
  if (pending.value)
    return;
  pending.value = true;
  setTimeout(() => {
    subscribed.value = details.pressed;
    pending.value = false;
  }, 1200);
}
</script>

<template>
  <!-- aria-disabled 而非 disabled：焦点留得住，读屏也报得出「这颗按不动」 -->
  <XhToggle
    :pressed="subscribed"
    variant="outline"
    :aria-busy="pending"
    :aria-disabled="pending"
    style="min-inline-size: 108px"
    @pressed-change="onPressedChange"
  >
    <!-- 转圈自带活区与名字，「在等什么」由它的 label 念出来 -->
    <XhSpinner v-if="pending" size="sm" label="正在提交" />
    {{ subscribed ? "已订阅" : "订阅" }}
  </XhToggle>

  <span style="font-size: 13px">
    {{ pending ? "请求在飞，这时候再点没有反应" : "点一下，落定要等 1.2 秒" }}
  </span>
</template>

产物

层	值
自定义元素	<xh-toggle>
Vue 组件	XhToggle
组合式函数	useToggle
状态机	toggleMachine
皮肤	@xihan-ui/styles/toggle.css

解剖

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

data-scope="toggle"：root

Props

属性	类型	必填	说明
pressed	boolean
defaultPressed	boolean
disabled	boolean
variant	ActionVariant		形态：solid / subtle / outline / ghost，决定颜色怎么用
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色
size	Size		尺寸：sm / md / lg
onPressedChange	(details: TogglePressedChangeDetails) => void		pressed 变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。

状态机

状态：off · on

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

判据：isPressedControlled

connect API

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

成员	类型	说明
pressed	boolean
setPressed	(next: boolean) => void
getRootProps	() => T['button']

键盘

规格出处：W3C APG

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