加载指示器 spinner

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

示例

基础用法

root 是 role=status 的活区，转圈图形由皮肤画在伪元素上；label 给出这一处在等什么

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

<template>
  <XhSpinner label="加载中" />
</template>

尺寸

size 只换直径，缺省档 md 不输出 data-size

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

<template>
  <XhSpinner size="sm" label="加载中" />
  <XhSpinner label="加载中" />
  <XhSpinner size="lg" label="加载中" />
</template>

可见文案

label 部件不写内容时显示解析后的 label，屏幕上看到的与读屏念的因此是同一段字

正在加载数据正在提交表单

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

<template>
  <!-- 文案只写在 label prop 上，部件自己把它显示出来 -->
  <XhSpinner label="正在加载数据">
    <XhSpinnerLabel />
  </XhSpinner>

  <!-- 换语言包同理：label → translations.label → 内置默认值，取第一段有字的 -->
  <XhSpinner :translations="{ label: '正在提交表单' }">
    <XhSpinnerLabel />
  </XhSpinner>
</template>

语气

tone 只换圆环起始边那一段颜色，轨道留在中性描边上，转到哪儿才看得出来

brandneutralsuccesswarningdangerinfo

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

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

<template>
  <!-- 语气名写在旁边的普通文字上，转圈自身的可及名字仍是"加载中" -->
  <span
    v-for="t in tones"
    :key="t"
    style="display: inline-flex; align-items: center; gap: 6px"
  >
    <XhSpinner :tone="t" label="加载中" />
    <span style="font-size: 13px">{{ t }}</span>
  </span>
</template>

盖住等待中的内容

转圈浮在内容上方，容器同时报 aria-busy，看得见的与念得出的是同一件事

本季新增客户 128 家，环比增长 12%。

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

const busy = ref(true);

// 遮罩铺满被等待的那块内容，底色兑透明，下面的内容还看得见轮廓
const overlayStyle = [
  "position: absolute",
  "inset: 0",
  "display: grid",
  "place-items: center",
  "border-radius: 8px",
  "background: color-mix(in oklab, var(--xh-bg-surface) 72%, transparent)",
].join("; ");
</script>

<template>
  <div style="inline-size: 100%; display: grid; gap: 12px; justify-items: start">
    <button type="button" @click="busy = !busy">
      {{ busy ? "数据回来了" : "重新加载" }}
    </button>

    <!-- 内容留在原位，转圈叠在上面，加载前后布局不跳 -->
    <div
      :aria-busy="busy"
      style="
        position: relative;
        inline-size: 260px;
        padding: 16px;
        border: 1px solid var(--xh-border-default);
        border-radius: 8px;
      "
    >
      <p style="margin: 0">本季新增客户 128 家，环比增长 12%。</p>
      <div v-if="busy" :style="overlayStyle">
        <XhSpinner label="正在刷新报表" />
      </div>
    </div>
  </div>
</template>

换掉转圈图形

内置圆环画在伪元素上，把直径与描边归零它就不占位；自绘的图形写进默认插槽

正在同步仓库正在生成摘要

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

// 三个公开令牌一起归零：圆环既不占位也不留间距，间距改由插槽里的内容自己给
const noRing = [
  "--xh-spinner-size: 0",
  "--xh-spinner-thickness: 0",
  "--xh-spinner-gap: 0",
].join("; ");

const ArcIcon = {
  name: "arc",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2.5",
    "stroke-linecap": "round",
  },
  nodes: [
    { tag: "path", attrs: { d: "M12 3A9 9 0 1 1 5.64 5.64" } },
    { tag: "path", attrs: { d: "M12 8.5A3.5 3.5 0 0 1 15.5 12" } },
  ],
} as const;

// 三个点错开相位地明灭：延迟各差一档，看起来就是一串跑动的点
const dots = [0, 160, 320];

function dotStyle(delay: number): string {
  return [
    "inline-size: 6px",
    "block-size: 6px",
    "border-radius: var(--xh-radius-full)",
    "background: var(--xh-bg-brand)",
    `animation: xh-fade-in 600ms var(--xh-ease-standard) ${delay}ms infinite alternate`,
  ].join("; ");
}
</script>

<template>
  <!-- 自绘图形：转动复用皮肤里的 xh-spin 关键帧，图形本身随便画 -->
  <XhSpinner label="正在同步仓库" :style="noRing">
    <XhIcon
      :icon="ArcIcon"
      size="lg"
      style="--xh-icon-fg: var(--xh-bg-brand); animation: xh-spin 900ms linear infinite"
    />
    <XhSpinnerLabel style="margin-inline-start: 8px" />
  </XhSpinner>

  <!-- 点阵：图形不必是一个整体，几个方块也能当指示器 -->
  <XhSpinner label="正在生成摘要" :style="noRing">
    <span style="display: inline-flex; gap: 4px">
      <span v-for="d in dots" :key="d" :style="dotStyle(d)" />
    </span>
    <XhSpinnerLabel style="margin-inline-start: 8px" />
  </XhSpinner>
</template>

产物

层	值
自定义元素	<xh-spinner>
Vue 组件	XhSpinner XhSpinnerLabel
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/spinner.css

解剖

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

data-scope="spinner"：root · label

Props

属性	类型	必填	说明
label	string		这一处的可及名字，写在 root 上。 label 部件显示的应当是同一段文案：aria-label 会盖过节点里的文字，两者不一致时 读屏念的与屏幕上看到的就对不上了。
size	Size		直径档位，缺省 md；缺省档不输出 data-size。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色
translations	Partial<SpinnerTranslations>

connect API

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

成员	类型	说明
label	string	解析后的文案：label → translations.label → 内置默认值。
getRootProps	() => T['element']
getLabelProps	() => T['element']

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。