Tabs 标签页 | Tuff Docs

TxTabItem 的 name 保持稳定且唯一，与 modelValue / defaultValue 一致。
设置页、后台页优先用 placement="left"；顶部、底部适合短的二级切换。
未激活的面板会卸载，需要保留的状态放在面板之外。
面板高度在加载后变化时，开启直接测量（contentScrollable=false 或 autoHeight），内容稳定后调用 refresh()。
nav-right 保持紧凑，复杂操作放进下拉菜单或抽屉。

API 参考

TxTabs

属性

属性名	类型	默认值	说明
`modelValue`	`string`	-	激活的 tab 名称（受控）。
`defaultValue`	`string`	-	非受控的初始 tab；不匹配任何 tab 时不选中。
`placement`	`'left' \| 'right' \| 'top' \| 'bottom'`	`'left'`	导航位置。
`offset`	`number`	`0`	`line` 指示器沿导航轴的偏移（px）。
`navMinWidth`	`number`	`220`	垂直布局时导航的最小宽度。
`navMaxWidth`	`number`	`320`	垂直布局时导航的最大宽度。
`contentPadding`	`number`	`12`	内容区内边距。
`contentScrollable`	`boolean`	`true`	内容区是否包一层滚动容器；尺寸动画开启时自动移除。
`borderless`	`boolean`	`false`	去掉外边框与背景。
`autoHeight`	`boolean`	`false`	开启高度动画。
`autoWidth`	`boolean`	`false`	开启宽度动画。
`showIndicator`	`boolean`	`true`	显示指示器；关闭后激活项自己绘制底色。
`indicatorVariant`	`'line' \| 'pill' \| 'block' \| 'dot' \| 'outline'`	`'line'`	指示器画法：细线、凸起面、浅染、圆点或内描边。
`indicatorMotion`	`'stretch' \| 'warp' \| 'glide' \| 'snap' \| 'spring'`	`'stretch'`	滑行方式：`stretch` 途中略拉长，`warp` 拉得更长，`glide` 整体平移，`snap` 最快停稳，`spring` 越过落点一次再回来。
`indicatorMotionStrength`	`number`	`1`	途中拉长的幅度；`0` 为整体平移。
`animation`	`TabsAnimation`	-	分别配置 `size`、`nav`、`indicator`、`content` 动画。
`animation.size`	`boolean \| { enabled?; durationMs?; easing? }`	由 `autoHeight` / `autoWidth` 推导	尺寸动画。
`animation.nav`	`boolean \| { enabled?; durationMs?; easing? }`	开启，`220ms ease`	导航宽度过渡。
`animation.indicator`	`boolean \| { enabled?; durationMs?; easing? }`	开启，`350ms`	指示器滑行；`durationMs` 整体缩放弹簧时长，`false` 时直接落位。
`animation.content`	`boolean \| { enabled?; type?; durationMs?; durationRatio?; easing? }`	开启 `zoom`，`180ms ease`	面板入场；`type` 可选 `fade`、`slide`、`zoom`、`blur`、`scale`、`none`。
`autoHeightDurationMs`	`number`	`250`	尺寸动画的默认时长。
`autoHeightEasing`	`string`	`ease`	尺寸动画的默认缓动。

事件

事件名	参数	说明
`update:modelValue`	`value: string`	激活的 tab 改变时触发。
`change`	`value: string`	用户激活 tab 后触发；父级修改 `modelValue` 不触发。

插槽

插槽名	参数	说明
`default`	-	`TxTabItem`、`TxTabItemGroup` 与 `TxTabHeader`；其他节点被忽略。
`nav-right`	-	导航栏末尾的操作区。

暴露方法

名称	类型	说明
`refresh`	`() => void`	重新测量尺寸。
`flip`	`(action: () => void \| Promise<void>) => Promise<void>`	在 FLIP 过渡中执行一次变更。
`action`	`(fn: (el: HTMLElement \| undefined) => void \| Promise<void>, optionsOrDetect?: any) => Promise<{ changedKeys: string[] } \| any>`	透传内部 AutoSizer 的 `action`。
`size`	`() => { width: number; height: number } \| undefined`	最近一次测得的尺寸。

TxTabItem

属性

属性名	类型	默认值	说明
`name`	`string`	必填	唯一名称，同时是激活值。
`iconClass`	`string`	`''`	标签前的图标 class。
`disabled`	`boolean`	`false`	禁止激活。
`activation`	`boolean`	`false`	未指定 `modelValue` 与 `defaultValue` 时作为默认项。
`active`	`boolean`	`false`	是否激活；由 TxTabs 注入，独立使用时才手动传。

事件

事件名	参数	说明
`click`	-	独立使用且未禁用时触发。

插槽

插槽名	参数	说明
`default`	-	面板内容；未激活时不挂载。
`icon`	-	自定义图标，替代 `iconClass`。
`name`	-	自定义标签，默认显示 `name`。

TxTabHeader

属性

属性名	类型	默认值	说明
`node`	`unknown`	-	当前激活的 `TxTabItem` VNode，由 TxTabs 传入。

插槽

插槽名	参数	说明
`default`	`{ props: { node?: unknown } }`	面板上方的吸顶头部。

TxTabItemGroup

属性

属性名	类型	默认值	说明
`name`	`string`	-	导航中的分组标题。

插槽

插槽名	参数	说明
`default`	-	子级 `TxTabItem`。

概述

受控时以 modelValue 为准；未传时依次取 defaultValue、activation。
只识别直接子级 TxTabItem、TxTabItemGroup、TxTabHeader（支持 Fragment），自定义包装组件会被忽略。
未激活的面板不挂载。
指示器是唯一的选中高亮，切换时两端各沿一根弹簧滑到目标，从不缩放。
首次测量时指示器直接落位；尺寸变化、animation.indicator: false 与减少动态效果时也直接落位。
尺寸动画开启时移除内部滚动容器，以便直接测量面板。

技术实现

指示器由 useJellyIndicator 的滑行材质驱动，requestAnimationFrame 只在移动时运行，每帧直接写入样式，不触发重渲染。
TxTabItemGroup 不渲染 DOM，分组由 TxTabs 读取其子级后生成。
源码：packages/tuffex/packages/components/src/tabs/。

查看源码

packages/tuffex/packages/components/src/tabs/index.ts

自定义

CSS 变量	用途
`--tx-border-color`	外边框与导航分隔线。
`--tx-bg-color`	容器背景。
`--tx-fill-color` / `--tx-fill-color-light`	激活项底色（无指示器时）/ 悬停底色。
`--tx-color-primary`	`line`、`dot`、`block`、`outline` 指示器与激活图标。
`--tx-surface-raised` / `--tx-elevation-1` / `--tx-border-color-lighter`	`pill` 凸起面、投影与内描边。
`--tx-text-color-primary` / `--tx-text-color-regular` / `--tx-text-color-secondary`	激活文字、常态文字、图标与分组标题。
`--tx-tab-item-ink` / `--tx-tab-item-icon-ink`	`.tx-tab-item` 的文字与图标颜色。
`--tx-tabs-indicator-duration` / `--tx-tabs-indicator-easing` / `--tx-tabs-indicator-strength`	由指示器 props 生成，仅供宿主读取。
`--tx-tabs-content-duration` / `--tx-tabs-content-easing`	由内容动画 props 生成。
`--tx-tabs-nav-duration` / `--tx-tabs-nav-easing`	由导航动画 props 生成。