标签页 tabs

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

示例

基础用法

标签清单交给 collection，default-value 指定初始选中项；面板常挂，靠 hidden 显隐

概览面板：默认 automatic，方向键移动焦点时顺带切换选中。

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

const tabs = [
  { value: "overview", label: "概览" },
  { value: "usage", label: "用法" },
  // 禁用写在数据里，方向键会跳过它
  { value: "api", label: "API（禁用）", disabled: true },
];

// 面板正文按条目取
const panels: Record<string, string> = {
  overview: "概览面板：默认 automatic，方向键移动焦点时顺带切换选中。",
  usage: "用法面板：面板不做懒挂载，切走再切回来，里面的滚动位置与表单态都还在。",
  api: "API 面板。",
};
</script>

<template>
  <XhTabsRoot
    :collection="tabs"
    default-value="overview"
    style="inline-size: 100%"
  >
    <!-- 面板内容归作者，走 panel 插槽 -->
    <template #panel="node">{{ panels[node.value] }}</template>
  </XhTabsRoot>
</template>

受控

传了 value 就由宿主说了算，组件自己不再改选中值；v-model:value 是它的语法糖

账户面板

当前：account

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

const value = ref("account");
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <XhTabsRoot v-model:value="value">
      <XhTabsList>
        <XhTabsTrigger value="account">账户</XhTabsTrigger>
        <XhTabsTrigger value="security">安全</XhTabsTrigger>
        <XhTabsTrigger value="notice">通知</XhTabsTrigger>
      </XhTabsList>

      <XhTabsContent value="account">账户面板</XhTabsContent>
      <XhTabsContent value="security">安全面板</XhTabsContent>
      <XhTabsContent value="notice">通知面板</XhTabsContent>
    </XhTabsRoot>

    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton variant="outline" @click="value = 'security'">
        跳到安全
      </XhButton>
      <span>当前：{{ value }}</span>
    </div>
  </div>
</template>

手动激活

activation-mode="manual" 时方向键只搬焦点，按 Enter 或空格才真的切面板

日报面板

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

const tabs = [
  { value: "daily", label: "日报" },
  { value: "weekly", label: "周报" },
  { value: "monthly", label: "月报" },
];
</script>

<template>
  <XhTabsRoot
    :collection="tabs"
    default-value="daily"
    activation-mode="manual"
    style="inline-size: 100%"
  >
    <template #panel="node">{{ node.label }}面板</template>
  </XhTabsRoot>
</template>

竖排

orientation 换掉方向键收哪一对键：竖排认上下键，左右键原样放行给页面

通用设置面板

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

const tabs = [
  { value: "general", label: "通用" },
  { value: "appearance", label: "外观" },
  { value: "advanced", label: "高级" },
];
</script>

<template>
  <XhTabsRoot
    :collection="tabs"
    default-value="general"
    orientation="vertical"
    style="inline-size: 100%"
  >
    <template #panel="node">{{ node.label }}设置面板</template>
  </XhTabsRoot>
</template>

形态

variant 只改选中态怎么画，切换行为与键盘操作三档一致；不写 variant 即 line 档

line（缺省）

概览面板

card

概览面板

segment

概览面板

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

// 第一档不写 variant，用 undefined 表达 line 缺省
const variants = [
  { variant: undefined, label: "line（缺省）" },
  { variant: "card", label: "card" },
  { variant: "segment", label: "segment" },
] as const;

const tabs = [
  { value: "overview", label: "概览" },
  { value: "usage", label: "用法" },
  { value: "api", label: "API" },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%">
    <div v-for="v in variants" :key="v.label">
      <div style="margin-block-end: 8px; font-size: 12px">{{ v.label }}</div>
      <XhTabsRoot
        :variant="v.variant"
        :collection="tabs"
        default-value="overview"
        style="inline-size: 100%"
      >
        <template #panel="node">{{ node.label }}面板</template>
      </XhTabsRoot>
    </div>
  </div>
</template>

语气

tone 决定选中态用哪族颜色，与 variant 正交；这里固定 card 形态只看语气的差别

选中面板

选中面板

选中面板

选中面板

选中面板

选中面板

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

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;

// 每族一套标签，选中那张的文本带上语气名
const groups = tones.map((tone) => ({
  tone,
  tabs: [
    { value: "selected", label: `${tone}（选中）` },
    { value: "other", label: "未选" },
  ],
}));

const panels: Record<string, string> = {
  selected: "选中面板",
  other: "另一个面板",
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; inline-size: 100%">
    <XhTabsRoot
      v-for="g in groups"
      :key="g.tone"
      variant="card"
      :tone="g.tone"
      :collection="g.tabs"
      default-value="selected"
      style="inline-size: 100%"
    >
      <template #panel="node">{{ panels[node.value] }}</template>
    </XhTabsRoot>
  </div>
</template>

尺寸

size 换标签的高度、内边距与字号，不传 size 即默认档

小

概览面板

默认

概览面板

大

概览面板

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

// 中间一档不写 size，用 undefined 表达
const sizes = [
  { size: "sm", label: "小" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "大" },
] as const;

const tabs = [
  { value: "overview", label: "概览" },
  { value: "usage", label: "用法" },
  { value: "api", label: "API" },
];
</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>
      <XhTabsRoot
        :size="s.size"
        :collection="tabs"
        default-value="overview"
        style="inline-size: 100%"
      >
        <template #panel="node">{{ node.label }}面板</template>
      </XhTabsRoot>
    </div>
  </div>
</template>

标签栏前后缀

list 里只收 trigger；要在标签栏两侧摆东西，把它们与 list 排进同一行

收件箱

全部邮件。

<script setup lang="ts">
import {
  XhButton,
  XhTabsContent,
  XhTabsList,
  XhTabsRoot,
  XhTabsTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <XhTabsRoot default-value="all" variant="segment" style="inline-size: 100%">
    <!-- 前后缀是这一行的兄弟节点，不进 list：list 里只放标签 -->
    <div style="display: flex; align-items: center; gap: 12px">
      <span style="font-size: 12px">收件箱</span>
      <XhTabsList>
        <XhTabsTrigger value="all">全部</XhTabsTrigger>
        <XhTabsTrigger value="unread">未读</XhTabsTrigger>
        <XhTabsTrigger value="flagged">已标记</XhTabsTrigger>
      </XhTabsList>
      <XhButton size="sm" variant="outline" style="margin-inline-start: auto">
        写邮件
      </XhButton>
    </div>

    <XhTabsContent value="all">全部邮件。</XhTabsContent>
    <XhTabsContent value="unread">未读邮件。</XhTabsContent>
    <XhTabsContent value="flagged">已标记邮件。</XhTabsContent>
  </XhTabsRoot>
</template>

拦截切换

受控下 value-change 只是意图，宿主校验不过就不写回 value，标签页原地不动

草稿面板：内容改过还没保存。

当前：draft

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

const value = ref("draft");
const dirty = ref(true);
const notice = ref("");

// 只单向绑 value，写不写回由这里说了算
function onValueChange(details: { value: string | null }): void {
  if (dirty.value) {
    notice.value = "草稿还没保存，切不过去";
    return;
  }
  notice.value = "";
  value.value = details.value ?? value.value;
}

function save(): void {
  dirty.value = false;
  notice.value = "已保存，现在可以切走了";
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <XhTabsRoot :value="value" @value-change="onValueChange">
      <XhTabsList>
        <XhTabsTrigger value="draft">草稿</XhTabsTrigger>
        <XhTabsTrigger value="preview">预览</XhTabsTrigger>
        <XhTabsTrigger value="publish">发布</XhTabsTrigger>
      </XhTabsList>

      <XhTabsContent value="draft">草稿面板：内容改过还没保存。</XhTabsContent>
      <XhTabsContent value="preview">预览面板。</XhTabsContent>
      <XhTabsContent value="publish">发布面板。</XhTabsContent>
    </XhTabsRoot>

    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton variant="outline" :disabled="!dirty" @click="save">
        保存草稿
      </XhButton>
      <span>{{ notice || `当前：${value}` }}</span>
    </div>
  </div>
</template>

动态增删

标签清单归宿主维护；关掉当前这页时把选中值挪到相邻一项，全关完选中值是 null

文档 1 的内容

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

const tabs = ref([
  { value: "doc-1", label: "文档 1" },
  { value: "doc-2", label: "文档 2" },
]);
const active = ref<string | null>("doc-1");
let seed = 2;

function addTab(): void {
  seed += 1;
  const value = `doc-${seed}`;
  tabs.value.push({ value, label: `文档 ${seed}` });
  active.value = value;
}

function closeTab(value: string): void {
  const index = tabs.value.findIndex((tab) => tab.value === value);
  if (index < 0) {
    return;
  }
  tabs.value.splice(index, 1);
  if (active.value !== value) {
    return;
  }
  // 关掉的正是当前页：往后顺延，没有后一项就退回最后一项
  const next = tabs.value[Math.min(index, tabs.value.length - 1)];
  active.value = next ? next.value : null;
}
</script>

<template>
  <XhTabsRoot v-model:value="active" variant="card" style="inline-size: 100%">
    <div style="display: flex; align-items: center; gap: 8px">
      <XhTabsList>
        <XhTabsTrigger v-for="tab in tabs" :key="tab.value" :value="tab.value">
          {{ tab.label }}
        </XhTabsTrigger>
      </XhTabsList>
      <XhButton size="sm" variant="outline" @click="addTab">新增一页</XhButton>
    </div>

    <XhTabsContent v-for="tab in tabs" :key="tab.value" :value="tab.value">
      <div style="display: flex; align-items: center; gap: 8px">
        <span>{{ tab.label }} 的内容</span>
        <XhButton size="sm" variant="outline" @click="closeTab(tab.value)">
          关闭本页
        </XhButton>
      </div>
    </XhTabsContent>

    <p v-if="tabs.length === 0">已经全部关掉，当前选中值是 null。</p>
  </XhTabsRoot>
</template>

可滚动的标签栏

标签多到一行放不下时，把 list 装进作者自建的横滚容器，两端各摆一个滚动按钮

模块 1 的面板

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

const tabs = Array.from({ length: 12 }, (_, i) => ({
  value: `module-${i + 1}`,
  label: `模块 ${i + 1}`,
}));

const viewport = ref<HTMLElement | null>(null);

function scrollStrip(delta: number): void {
  viewport.value?.scrollBy({ left: delta, behavior: "smooth" });
}
</script>

<template>
  <XhTabsRoot default-value="module-1" style="inline-size: 100%">
    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton
        size="sm"
        variant="outline"
        aria-label="向前滚动"
        @click="scrollStrip(-200)"
      >
        ‹
      </XhButton>

      <!-- 滚动视口是 list 外面的一层普通容器：条目查询只以 list 为界，键盘与切换都不受它影响 -->
      <div ref="viewport" style="flex: 1; min-inline-size: 0; overflow-x: auto">
        <!-- 让 list 撑到内容宽度，基线才跟着标签一起滚 -->
        <XhTabsList style="inline-size: max-content">
          <XhTabsTrigger v-for="t in tabs" :key="t.value" :value="t.value">
            {{ t.label }}
          </XhTabsTrigger>
        </XhTabsList>
      </div>

      <XhButton
        size="sm"
        variant="outline"
        aria-label="向后滚动"
        @click="scrollStrip(200)"
      >
        ›
      </XhButton>
    </div>

    <XhTabsContent v-for="t in tabs" :key="t.value" :value="t.value">
      {{ t.label }} 的面板
    </XhTabsContent>
  </XhTabsRoot>
</template>

切换后滚进视野

每个标签都带 data-value 身份标记，选中值一变就按它取到那个标签，滚到视口正中

第 1 章 的面板

用方向键走位时，标签栏也会跟着滚

<script setup lang="ts">
import { ref, watch } from "vue";
import {
  XhButton,
  XhTabsContent,
  XhTabsList,
  XhTabsRoot,
  XhTabsTrigger,
} from "@xihan-ui/vue";

const tabs = Array.from({ length: 12 }, (_, i) => ({
  value: `chapter-${i + 1}`,
  label: `第 ${i + 1} 章`,
}));

const value = ref("chapter-1");
const viewport = ref<HTMLElement | null>(null);

// 监听选中值而不是切换事件：外部改值、键盘走位、点击三条路都在这里收口
watch(value, (next) => {
  viewport.value
    ?.querySelector<HTMLElement>(`[data-part="trigger"][data-value="${next}"]`)
    ?.scrollIntoView({ block: "nearest", inline: "center", behavior: "smooth" });
});
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <XhTabsRoot v-model:value="value" variant="segment">
      <div ref="viewport" style="overflow-x: auto">
        <XhTabsList style="inline-size: max-content">
          <XhTabsTrigger v-for="t in tabs" :key="t.value" :value="t.value">
            {{ t.label }}
          </XhTabsTrigger>
        </XhTabsList>
      </div>

      <XhTabsContent v-for="t in tabs" :key="t.value" :value="t.value">
        {{ t.label }} 的面板
      </XhTabsContent>
    </XhTabsRoot>

    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton size="sm" variant="outline" @click="value = 'chapter-12'">
        跳到第 12 章
      </XhButton>
      <XhButton size="sm" variant="outline" @click="value = 'chapter-1'">
        回到第 1 章
      </XhButton>
      <span>用方向键走位时，标签栏也会跟着滚</span>
    </div>
  </div>
</template>

标签栏摆在哪一边

root 按书写顺序渲染子节点：把面板写在 list 前面，标签栏就落到内容之后，基线换到另一边

标签在下

概览 的面板

标签在右

概览 的面板

<script setup lang="ts">
import {
  XhTabsContent,
  XhTabsList,
  XhTabsRoot,
  XhTabsTrigger,
} from "@xihan-ui/vue";

const tabs = [
  { value: "overview", label: "概览" },
  { value: "usage", label: "用法" },
  { value: "api", label: "API" },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%">
    <div>
      <div style="margin-block-end: 8px; font-size: 12px">标签在下</div>
      <XhTabsRoot default-value="overview" style="inline-size: 100%">
        <XhTabsContent v-for="t in tabs" :key="t.value" :value="t.value">
          {{ t.label }} 的面板
        </XhTabsContent>
        <!-- 基线跟着换边：横排的基线在 list 底边，标签在下就把它挪到顶边 -->
        <XhTabsList
          style="
            border-block-end: 0;
            border-block-start: var(--xh-stroke-thin) solid var(--xh-border-default);
          "
        >
          <XhTabsTrigger v-for="t in tabs" :key="t.value" :value="t.value">
            {{ t.label }}
          </XhTabsTrigger>
        </XhTabsList>
      </XhTabsRoot>
    </div>

    <div>
      <div style="margin-block-end: 8px; font-size: 12px">标签在右</div>
      <XhTabsRoot
        default-value="overview"
        orientation="vertical"
        style="inline-size: 100%"
      >
        <XhTabsContent
          v-for="t in tabs"
          :key="t.value"
          :value="t.value"
          style="flex: 1"
        >
          {{ t.label }} 的面板
        </XhTabsContent>
        <XhTabsList
          style="
            border-inline-end: 0;
            border-inline-start: var(--xh-stroke-thin) solid var(--xh-border-default);
          "
        >
          <XhTabsTrigger v-for="t in tabs" :key="t.value" :value="t.value">
            {{ t.label }}
          </XhTabsTrigger>
        </XhTabsList>
      </XhTabsRoot>
    </div>
  </div>
</template>

产物

层	值
自定义元素	<xh-tabs>
Vue 组件	XhTabsContent XhTabsList XhTabsRoot XhTabsTrigger
组合式函数	useTabs
状态机	tabsMachine
皮肤	@xihan-ui/styles/tabs.css

解剖

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

data-scope="tabs"：root · list · trigger · content

Props

属性	类型	必填	说明
collection	TabsNode[]		条目数据，标签文本与禁用的事实源。给了它，trigger 部件只需报 value。 缺省即回到「文本与禁用都写在 trigger 上」的老路。
value	string | null		选中值。给定即受控：内部不再自改，只发 onValueChange。
defaultValue	string | null
orientation	Orientation		方向键轴向，默认 horizontal；不同轴的方向键放行给页面滚动与读屏。
dir	Direction		文字方向，默认 ltr；只影响水平轴上 ArrowLeft/ArrowRight 的前后语义。
activationMode	TabsActivationMode		方向键移动焦点时是否顺带切换选中，默认 automatic。
loop	boolean		方向键走到尽头是否回绕，默认 true。
variant	TabsVariant		形态：line / card / segment，决定选中态怎么画。缺省是 line。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色。
size	Size		尺寸：sm / md / lg。
onValueChange	(details: TabsValueChangeDetails) => void		value 变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。

状态机

状态：idle

事件：VALUE.SET · TRIGGER.SELECT · TRIGGER.FOCUS · TRIGGER.NAVIGATE · LIST.BLUR

判据：isAutomatic

connect API

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

成员	类型	说明
value	string | null
collection	readonly TabsNodeMeta[]	collection 推出的条目元信息，按数据顺序排列；没给 collection 即空数组。
focusedValue	string | null	焦点在组外时为 null。
setValue	(next: string | null) => void	传 null 清空选中：context.value 与受控 value 都能表达"无选中"，写入侧同样收得下。
getRootProps	() => T['element']
getListProps	() => T['element']
getTriggerProps	(props: TabsTriggerProps) => T['button']
getContentProps	(props: TabsContentProps) => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowRight / ArrowDown	focus in list, 按键与 orientation 同轴	焦点移到下一个 trigger（禁用项跳过、尽头按 loop 回绕）；automatic 模式顺带切换选中
ArrowLeft / ArrowUp	focus in list, 按键与 orientation 同轴	焦点移到上一个 trigger；automatic 模式顺带切换选中
Home	focus in list	焦点移到首个可停留 trigger
End	focus in list	焦点移到末个可停留 trigger
Enter / Space	focus in trigger, not disabled	把选中切到焦点所在 trigger（manual 模式的确认键）
Tab / Shift+Tab	focus in list	整组只有锚点 trigger 留在 Tab 序列内，一次 Tab 进出；无锚点时由 list 兜底，焦点进来后转投锚点 trigger（即选中项），锚点缺席或被禁用才落首个可停留项