Tab 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在同一区域的多个视图或内容面板之间切换，支持数据生成或自定义按钮组合，并提供键盘导航。

使用选择

用于同一区域的内容面板或视图切换；截图中的下划线标签页可选 underline 变体。只改变过滤参数时使用 Segmented。

• items 提供唯一 value 与 label；显式 Button as="item" 替换 items。

• bind:value 同步当前项；缺失或不匹配时仅视觉回退，不写回值。内容面板按当前值由页面展示。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Tab } from '@snowui-design-system/components';</script> <Tab itemRole="tab" size="lg" value="preview" aria-label="Component example view" items={[{ value: 'preview', label: 'Preview' }, { value: 'code', label: 'Code' }, { value: 'api', label: 'API' }]} />

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

默认内置模式 / 显式组合模式

• 默认内置模式（推荐）：items 自动生成 <Button as="item">；item 可用 icon 声明图标，Tab 内置生成 Icon + Text，适用于 icon-toggle；parts.Button / parts.Icon / parts.Text 配置统一 Props。

• 显式组合模式：显式书写 Button，用于 Icon、Text、复杂内容或逐项 Props 差异。

设计原则

• 子项即 Button:不新增 TabItem 组件。子项直接使用 Button,在 Button 上声明 value="..." 即可。Button 的 size 档位决定 Item 的 padding / radius / font-size / line-height(完全继承 Button SM/MD/LG)。

• 容器接管激活态视觉:Tab 不修改 Button 源码,而是通过 CSS 上下文 override Button 的三层桥接变量(--snowui-button-background-override / --snowui-button-color-override / --snowui-button-opacity-override / --snowui-button-padding-override)在 Tab 上下文内接管视觉,不污染外部 Button。

• 共享 indicator FLIP 动效:激活态的"白底"/"灰底"/"下划线"通过一个共享的 .snowui-tab-indicator 元素绝对定位,在 Item 间通过 transform/width/height 平滑过渡,而非每个 Item 各自 fade。

• 复合控件 hover:Item 默认关闭 Button 的 scale hover，保留 Tab 自己的背景/透明度反馈与 indicator；子 Button 或 parts.Button.scaleOnHover=true 可显式重新开启。

2.2 子项约定

子项必须是 <Button as="item">,在 Button 上声明:

• value="xxx" —— 必填,项标识值(通过 Button rest-spread 落到根 <button> 元素的 value 属性)

• 可选 disabled —— 禁用单项

• 可选 href —— 通过 Button 的 href 实现路由型 Tab(Button 会渲染为 <a>)

• 可选 bare —— 使用无 padding / radius / 背景且不限制内容类型的 Button；Tab 继续通过 Button 根节点上的 --snowui-button-opacity-override 独立接管 inactive / hover / active 透明度，因此不依赖 Button bare 的默认强调级别

variant="pill"(样式1, 默认)

容器有 --black-4 背景 + padding，并使用与 SearchBox 一致的 blur(1.25rem)（20px）背景模糊。激活项:--static-white-80 白底 + 0 2px 4px rgba(0,0,0,0.1) shadow。未激活项 Text / Icon 使用 --black-100 × opacity: 0.4；激活项 Text / Icon 使用 --static-black-100 与 opacity: 1；未激活项 hover 时仅将 opacity 提升到 1。

variant="solid"(样式2)

容器无背景、无 padding。激活项:--black-4 背景,无 shadow。激活项 Text / Icon 保持 Button 默认颜色链；未激活项 Text / Icon 使用 --black-100 × opacity: 0.4。

variant="underline"(样式3)

容器无背景、无圆角。子项 padding 0(override Button)。激活项底部 2px 横向下划线(垂直时为左侧 2px 竖线),颜色 --primary；激活项 Text / Icon 同样使用 --primary。未激活项 Text / Icon 使用 --black-100 × opacity: 0.4。子项间距更大:SM=--gap-3(12) / MD=--gap-4(16) / LG=--gap-5(20)。

variant="icon-toggle"(样式4)

容器视觉与 pill 相同，包含与 SearchBox 一致的 blur(1.25rem)（20px）背景模糊。未激活项隐藏 .snowui-text,只显示图标(子项内部需包含 Icon + Text 节点);激活项显示 icon + text,文字渐显时消费 Frame 生命周期进入 bridge 时序,宽度通过 Frame size motion bridge 平滑展开。

默认items模式在icon-toggle中使用每项label作为可访问名称，文字隐藏时仍可识别；显式children模式由调用方给每个Button提供aria-label。内部图文间距复用Button所有者，不给每个控件外包Frame。

variant="bare"

容器无背景、padding 和圆角，不显示 indicator；Item 无背景、padding 和圆角，只通过 opacity: 0.4 -> 1 表达未激活、hover 与激活状态。内容可以是文字、单 Icon 或 Icon + 文字。Item gap 复用 underline 的尺寸梯度：SM=12px / MD=16px / LG=20px。

动效

Item 颜色、透明度继续消费 Frame 默认动效系统。Tab 根注入 TAB_INDICATOR_MOTION_STYLE；共享 indicator 的位移消费 Frame control bridge，宽高变化消费 Frame size bridge，两者统一使用 Tab indicator preset。icon-toggle 因文字显隐触发的重测也保持动效，不再被 ResizeObserver 瞬间贴位覆盖。

Tab indicator 的具体时序以 TAB_INDICATOR_MOTION 为准；TAB_INDICATOR_MOTION_STYLE 将同一 preset 注入 Frame control / size 两组 bridge，禁止分别维护位移和尺寸数值。

布局模型

主布局模型:内联外壳布局(同 Button)。Tab 自身是一个 flex 容器(inline-flex,column 时 flex-direction: column),内部:

• 第一个 child:绝对定位的 <div class="snowui-tab-indicator">,跟随激活 Button 通过 transform/width/height 过渡

• 之后是用户传入的 Button 子项;Button position: relative; z-index: 1 确保文字在 indicator 之上

fill={true} 时,横向子项使用 flex: 1 1 0 等宽填满容器可用宽度。通常配合 style="width: ..." / 宽度工具类使用;未定义容器宽度时仍按内容自然宽度布局。

详见 LayoutProtocol.md §12.3（源码参考：specs/maintainers/LayoutProtocol.md）。

键盘行为

• ← / →(row)或 ↑ / ↓(column):移动焦点。当 selectionFollowsFocus=true(Segmented)时直接激活。

• Home / End:跳到首/末项,行为同上。

• Enter / Space:由 Button 原生 click 行为触发,激活当前焦点项。

• Roving tabindex:激活项 tabindex=0,其他项 tabindex=-1。整个 Tab 在外部 Tab 键序列中只占一位。

使用示例

<script lang="ts">  import { Button, Icon, Text } from '@snowui-design-system/components';  import { Tab } from '@snowui-design-system/components';  import { FourLeafClover, Star } from '@snowui-design-system/resource-svelte';  let value = $state('web');</script>  <Tab bind:value variant="pill" size="sm">  <Button as="item" value="web"><Icon><FourLeafClover /></Icon>Web</Button>  <Button as="item" value="mobile"><Icon><Star /></Icon>Mobile</Button></Tab>  <Tab variant="solid" size="md">  <Button as="item" value="web"><Icon><FourLeafClover /></Icon>Web</Button>  <Button as="item" value="mobile"><Icon><Star /></Icon>Mobile</Button></Tab>  <Tab variant="underline" size="lg">  <Button as="item" value="overview"><Icon><FourLeafClover /></Icon>Overview</Button>  <Button as="item" value="details"><Icon><Star /></Icon>Details</Button></Tab>  <Tab variant="icon-toggle">  <Button as="item" value="web" aria-label="Web"><Icon><FourLeafClover /></Icon><Text>Web</Text></Button>  <Button as="item" value="mobile" aria-label="Mobile"><Icon><Star /></Icon><Text>Mobile</Text></Button></Tab>  <Tab  variant="icon-toggle"  value="web"  items={[    { value: "web", label: "Web", icon: FourLeafClover },    { value: "mobile", label: "Mobile", icon: Star }  ]}/>  <Tab variant="bare" size="md" value="all">  <Button as="item" value="all">All</Button>  <Button as="item" value="random" iconOnly aria-label="收藏"><Icon><Star /></Icon></Button></Tab>  <Tab column variant="underline">  <Button as="item" value="a">A</Button>  <Button as="item" value="b">B</Button></Tab>  <Tab fill style="width: calc(var(--size-20) * 4)" value="web">  <Button as="item" value="web">Web</Button>  <Button as="item" value="mobile">Mobile</Button></Tab>  <Tab variant="bare" value="random">  <Button as="item" value="all">All</Button>  <Button as="item" value="random">Random</Button></Tab>