步骤条 steps

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

示例

基础用法

不传 step 即为非受控；方向键只搬焦点，按 Enter 或空格才切步，进退方法由 root 的插槽交出来

面板 1：填写收货地址。

当前：第 1 / 3 步

<script setup lang="ts">
import {
  XhButton,
  XhStepsContent,
  XhStepsDescription,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

const steps = [
  { title: "填写地址", description: "收货人与联系方式" },
  { title: "选择支付", description: "支付方式与优惠" },
  { title: "确认订单", description: "核对金额" },
];
</script>

<template>
  <XhStepsRoot
    v-slot="{ step, count, complete, goToPrevStep, goToNextStep }"
    :count="steps.length"
    style="inline-size: 100%"
  >
    <XhStepsList>
      <XhStepsItem v-for="(s, i) in steps" :key="s.title" :value="i">
        <XhStepsTrigger>
          <!-- 圆点里的字符是作者内容：皮肤只按 data-state 管描边与填充 -->
          <XhStepsIndicator>{{ step > i ? "✓" : i + 1 }}</XhStepsIndicator>
          <XhStepsTitle>{{ s.title }}</XhStepsTitle>
          <XhStepsDescription>{{ s.description }}</XhStepsDescription>
        </XhStepsTrigger>
        <XhStepsSeparator />
      </XhStepsItem>
    </XhStepsList>

    <XhStepsContent :value="0">面板 1：填写收货地址。</XhStepsContent>
    <XhStepsContent :value="1">面板 2：选择支付方式。</XhStepsContent>
    <XhStepsContent :value="2">面板 3：核对金额并提交。</XhStepsContent>
    <!-- value 等于 count 的这块是完成页：走完最后一步之后的那一格 -->
    <XhStepsContent :value="steps.length">全部完成：订单已提交。</XhStepsContent>

    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton variant="outline" :disabled="step === 0" @click="goToPrevStep()">
        上一步
      </XhButton>
      <XhButton variant="solid" :disabled="complete" @click="goToNextStep()">
        下一步
      </XhButton>
      <span>{{ complete ? "当前：全部完成" : `当前：第 ${step + 1} / ${count} 步` }}</span>
    </div>
  </XhStepsRoot>
</template>

受控

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

当前 step：1

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

const steps = ["提交申请", "主管审批", "财务复核", "归档"];
const current = ref(1);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <XhStepsRoot v-model:step="current" :count="steps.length">
      <XhStepsList>
        <XhStepsItem v-for="(s, i) in steps" :key="s" :value="i">
          <XhStepsTrigger>
            <XhStepsIndicator>{{ current > i ? "✓" : i + 1 }}</XhStepsIndicator>
            <XhStepsTitle>{{ s }}</XhStepsTitle>
          </XhStepsTrigger>
          <XhStepsSeparator />
        </XhStepsItem>
      </XhStepsList>
    </XhStepsRoot>

    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton variant="outline" @click="current = 0">回到第一步</XhButton>
      <XhButton variant="outline" @click="current = steps.length">直接完成</XhButton>
      <span>当前 step：{{ current }}</span>
    </div>
  </div>
</template>

线性模式

linear 下还没走到的步一律禁用，只能回头看走过的；它只拦界面上的乱跳，逐步前进照常

面板 1：上传证件照。

<script setup lang="ts">
import {
  XhButton,
  XhStepsContent,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

const steps = ["实名认证", "绑定银行卡", "签署协议"];
</script>

<template>
  <XhStepsRoot
    v-slot="{ step, complete, goToPrevStep, goToNextStep }"
    :count="steps.length"
    linear
    style="inline-size: 100%"
  >
    <XhStepsList>
      <XhStepsItem v-for="(s, i) in steps" :key="s" :value="i">
        <XhStepsTrigger>
          <XhStepsIndicator>{{ step > i ? "✓" : i + 1 }}</XhStepsIndicator>
          <XhStepsTitle>{{ s }}</XhStepsTitle>
        </XhStepsTrigger>
        <XhStepsSeparator />
      </XhStepsItem>
    </XhStepsList>

    <XhStepsContent :value="0">面板 1：上传证件照。</XhStepsContent>
    <XhStepsContent :value="1">面板 2：填写卡号。</XhStepsContent>
    <XhStepsContent :value="2">面板 3：勾选并签署。</XhStepsContent>
    <XhStepsContent :value="steps.length">全部完成。</XhStepsContent>

    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton variant="outline" :disabled="step === 0" @click="goToPrevStep()">
        上一步
      </XhButton>
      <XhButton variant="solid" :disabled="complete" @click="goToNextStep()">
        下一步
      </XhButton>
    </div>
  </XhStepsRoot>
</template>

竖排

orientation="vertical" 把步骤列与面板并排摆，方向键随之改收上下键

面板 2：测试报告。

<script setup lang="ts">
import {
  XhStepsContent,
  XhStepsDescription,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

const steps = [
  { title: "打包", description: "生成产物" },
  { title: "测试", description: "跑单元测试" },
  { title: "发布", description: "推到镜像仓库" },
];
</script>

<template>
  <XhStepsRoot
    :count="steps.length"
    :default-step="1"
    orientation="vertical"
    style="inline-size: 100%"
  >
    <XhStepsList>
      <XhStepsItem v-for="(s, i) in steps" :key="s.title" :value="i">
        <XhStepsTrigger>
          <XhStepsIndicator>{{ i + 1 }}</XhStepsIndicator>
          <XhStepsTitle>{{ s.title }}</XhStepsTitle>
          <XhStepsDescription>{{ s.description }}</XhStepsDescription>
        </XhStepsTrigger>
        <XhStepsSeparator />
      </XhStepsItem>
    </XhStepsList>

    <XhStepsContent :value="0">面板 1：打包日志。</XhStepsContent>
    <XhStepsContent :value="1">面板 2：测试报告。</XhStepsContent>
    <XhStepsContent :value="2">面板 3：发布记录。</XhStepsContent>
    <XhStepsContent :value="steps.length">流水线跑完了。</XhStepsContent>
  </XhStepsRoot>
</template>

语气

tone 决定已完成与当前这两步的标记、连接线用哪族颜色；示例预置到第 2 步，第 1 步已走完

brand

面板 2：选择支付

neutral

面板 2：选择支付

success

面板 2：选择支付

warning

面板 2：选择支付

danger

面板 2：选择支付

info

面板 2：选择支付

<script setup lang="ts">
import {
  XhStepsContent,
  XhStepsDescription,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
const steps = [
  { title: "填写地址", description: "收货人与联系方式" },
  { title: "选择支付", description: "支付方式与优惠" },
  { title: "确认订单", description: "核对金额" },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%">
    <div v-for="t in tones" :key="t">
      <div style="margin-block-end: 8px; font-size: 12px">{{ t }}</div>
      <XhStepsRoot
        :tone="t"
        :count="steps.length"
        :default-step="1"
        style="inline-size: 100%"
      >
        <XhStepsList>
          <XhStepsItem v-for="(s, i) in steps" :key="s.title" :value="i">
            <XhStepsTrigger>
              <XhStepsIndicator>{{ i === 0 ? "✓" : i + 1 }}</XhStepsIndicator>
              <XhStepsTitle>{{ s.title }}</XhStepsTitle>
              <XhStepsDescription>{{ s.description }}</XhStepsDescription>
            </XhStepsTrigger>
            <XhStepsSeparator />
          </XhStepsItem>
        </XhStepsList>

        <XhStepsContent v-for="(s, i) in steps" :key="s.title" :value="i">
          面板 {{ i + 1 }}：{{ s.title }}
        </XhStepsContent>
        <XhStepsContent :value="steps.length">全部完成。</XhStepsContent>
      </XhStepsRoot>
    </div>
  </div>
</template>

尺寸

size 换序号圆点的直径与标题、说明的字号，不传 size 即默认档

小

面板 2：选择支付

默认

面板 2：选择支付

大

面板 2：选择支付

<script setup lang="ts">
import {
  XhStepsContent,
  XhStepsDescription,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

// 中间一档不写 size，用 undefined 表达
const sizes = [
  { size: "sm", label: "小" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "大" },
] as const;
const steps = [
  { title: "填写地址", description: "收货人与联系方式" },
  { title: "选择支付", description: "支付方式与优惠" },
  { title: "确认订单", description: "核对金额" },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%">
    <div v-for="s in sizes" :key="s.label">
      <div style="margin-block-end: 8px; font-size: 12px">{{ s.label }}</div>
      <XhStepsRoot
        :size="s.size"
        :count="steps.length"
        :default-step="1"
        style="inline-size: 100%"
      >
        <XhStepsList>
          <XhStepsItem v-for="(item, i) in steps" :key="item.title" :value="i">
            <XhStepsTrigger>
              <XhStepsIndicator>{{ i === 0 ? "✓" : i + 1 }}</XhStepsIndicator>
              <XhStepsTitle>{{ item.title }}</XhStepsTitle>
              <XhStepsDescription>{{ item.description }}</XhStepsDescription>
            </XhStepsTrigger>
            <XhStepsSeparator />
          </XhStepsItem>
        </XhStepsList>

        <XhStepsContent v-for="(item, i) in steps" :key="item.title" :value="i">
          面板 {{ i + 1 }}：{{ item.title }}
        </XhStepsContent>
        <XhStepsContent :value="steps.length">全部完成。</XhStepsContent>
      </XhStepsRoot>
    </div>
  </div>
</template>

点击切步与禁用某步

点标签直接切到那一步；单步标了 disabled 就点不动，方向键也跳过它

面板 1：选择商品

当前 step：0（第三步禁用，点它没有反应）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhStepsContent,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

const steps = [
  { title: "选择商品", disabled: false },
  { title: "确认订单", disabled: false },
  { title: "在线支付", disabled: true },
  { title: "等待发货", disabled: false },
];
const current = ref(0);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <XhStepsRoot v-model:step="current" :count="steps.length">
      <XhStepsList>
        <XhStepsItem
          v-for="(s, i) in steps"
          :key="s.title"
          :value="i"
          :disabled="s.disabled"
        >
          <XhStepsTrigger>
            <XhStepsIndicator>{{ current > i ? "✓" : i + 1 }}</XhStepsIndicator>
            <XhStepsTitle>{{ s.title }}</XhStepsTitle>
          </XhStepsTrigger>
          <XhStepsSeparator />
        </XhStepsItem>
      </XhStepsList>

      <XhStepsContent v-for="(s, i) in steps" :key="s.title" :value="i">
        面板 {{ i + 1 }}：{{ s.title }}
      </XhStepsContent>
      <XhStepsContent :value="steps.length">全部完成。</XhStepsContent>
    </XhStepsRoot>

    <span>当前 step：{{ current }}（第三步禁用，点它没有反应）</span>
  </div>
</template>

出错的那一步

步序只认下标，「这一步出错了」是宿主自己的数据：在那一步的 item 上换掉标记与颜色令牌

第二步无论是当前步还是已走过，都停在危险色上

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhStepsDescription,
  XhStepsIndicator,
  XhStepsItem,
  XhStepsList,
  XhStepsRoot,
  XhStepsSeparator,
  XhStepsTitle,
  XhStepsTrigger,
} from "@xihan-ui/vue";

const steps = [
  { title: "提交材料", description: "已通过" },
  { title: "资质审核", description: "材料不齐，被打回" },
  { title: "签署合同", description: "等待中" },
];

// 出错的那一步
const errorAt = 1;

// 当前档与已走过档一起换成危险色，写在 item 上，序号、标题与连接线都从这里继承
const errorTokens = {
  "--xh-steps-indicator-border-current": "var(--xh-fg-danger)",
  "--xh-steps-indicator-fg-current": "var(--xh-fg-danger)",
  "--xh-steps-indicator-border-completed": "var(--xh-fg-danger)",
  "--xh-steps-indicator-bg-completed": "var(--xh-fg-danger)",
  "--xh-steps-title-fg-active": "var(--xh-fg-danger)",
  "--xh-steps-separator-bg-completed": "var(--xh-fg-danger)",
};

const current = ref(1);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <XhStepsRoot v-model:step="current" :count="steps.length">
      <XhStepsList>
        <XhStepsItem
          v-for="(s, i) in steps"
          :key="s.title"
          :value="i"
          :style="i === errorAt ? errorTokens : undefined"
        >
          <XhStepsTrigger>
            <XhStepsIndicator>
              {{ i === errorAt ? "!" : current > i ? "✓" : i + 1 }}
            </XhStepsIndicator>
            <XhStepsTitle>{{ s.title }}</XhStepsTitle>
            <XhStepsDescription>{{ s.description }}</XhStepsDescription>
          </XhStepsTrigger>
          <XhStepsSeparator />
        </XhStepsItem>
      </XhStepsList>
    </XhStepsRoot>

    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton size="sm" variant="outline" @click="current = 2">
        走到第三步
      </XhButton>
      <XhButton size="sm" variant="outline" @click="current = 1">
        退回第二步
      </XhButton>
      <span>第二步无论是当前步还是已走过，都停在危险色上</span>
    </div>
  </div>
</template>

产物

层	值
自定义元素	<xh-steps>
Vue 组件	XhStepsContent XhStepsDescription XhStepsIndicator XhStepsItem XhStepsList XhStepsRoot XhStepsSeparator XhStepsTitle XhStepsTrigger
组合式函数	useSteps
状态机	stepsMachine
皮肤	@xihan-ui/styles/steps.css

解剖

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

data-scope="steps"：root · list · item · trigger · indicator · title · description · separator · content

Props

属性	类型	必填	说明
step	number		当前步序（0 起）。给定即受控：内部不再自改，只发 onStepChange。
defaultStep	number		非受控初值，默认 0。
count	number		总步数，是步序的上界与读屏"第 k 步，共 n 步"的分母。 缺省按 0 处理：此时 root 带 data-empty，步序被夹死在 0。
orientation	Orientation		方向键轴向，默认 horizontal；不同轴的方向键放行给页面滚动与读屏。
linear	boolean		线性模式：只能回头看走过的步。未解锁（index > step）的 trigger 一律禁用。 只拦跳转，goToNextStep 逐步前进照常可用。
disabled	boolean		整组不可交互：trigger 全部退出 Tab 序列，指针与键盘都不认。
dir	Direction		文字方向，默认 ltr；只影响水平轴上 ArrowLeft/ArrowRight 的前后语义。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色。
size	Size		尺寸：sm / md / lg。
onStepChange	(details: StepsStepChangeDetails) => void		步序变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。

状态机

状态：idle

事件：STEP.SET · STEP.PREV · STEP.NEXT · TRIGGER.FOCUS · LIST.BLUR

connect API

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

成员	类型	说明
step	number	当前步序，恒在 [0, count] 内：count 变小后停在越界步也读得到一个可用的值。
count	number
complete	boolean	全部走完（step 走到 count）。此时没有任何一步是 current，作者据此渲染完成页。
focusedStep	number | null	焦点在组外时为 null。
getItemState	(props: StepsItemProps) => StepsItemState
setStep	(next: number) => void	直接跳到某一步；越界会被夹回 [0, count]。 不认 linear：linear 只拦界面上的乱跳，不拦作者的命令式调用。
goToNextStep	() => void
goToPrevStep	() => void
getRootProps	() => T['element']
getListProps	() => T['element']
getItemProps	(props: StepsItemProps) => T['element']
getTriggerProps	(props: StepsItemProps) => T['button']
getIndicatorProps	(props: StepsItemProps) => T['element']
getTitleProps	(props: StepsItemProps) => T['element']
getDescriptionProps	(props: StepsItemProps) => T['element']
getSeparatorProps	(props: StepsItemProps) => T['element']
getContentProps	(props: StepsItemProps) => T['element']	面板按 index 与当前步配对；未命中的常挂并带 hidden。

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowRight / ArrowDown	focus in list, 按键与 orientation 同轴	焦点移到下一个可停留 trigger（禁用与 linear 未解锁的跳过，尽头不回绕）；步序不变
ArrowLeft / ArrowUp	focus in list, 按键与 orientation 同轴	焦点移到上一个可停留 trigger；步序不变
Home	focus in list	焦点移到首个可停留 trigger
End	focus in list	焦点移到末个可停留 trigger
Enter / Space	focus in trigger, 未禁用且已解锁	把当前步切到焦点所在的那一步
Tab / Shift+Tab	focus in list	整组只有锚点 trigger 留在 Tab 序列内，一次 Tab 进出；无锚点时由 list 兜底