Tabs 标签页

一排标签切换下方的内容面板，同一时刻只显示一块。

基础用法

标签写 pt-tab、面板写 pt-tab-panel，按 value 一一对应。默认 segmented 形态，适合区块内切换视图。受控值走 value + ptChange。

<pt-tabs value="week">
  <pt-tab value="day">日</pt-tab>
  <pt-tab value="week">周</pt-tab>
  <pt-tab value="month">月</pt-tab>
  <pt-tab-panel value="day">按日汇总的访问量</pt-tab-panel>
  <pt-tab-panel value="week">按周汇总的访问量</pt-tab-panel>
  <pt-tab-panel value="month">按月汇总的访问量</pt-tab-panel>
</pt-tabs>

下划线形态与禁用

variant="line" 分量更重，给页面级主标签；disabled 的标签点不中，方向键也会跳过它。

<pt-tabs variant="line" value="overview">
  <pt-tab value="overview">概览</pt-tab>
  <pt-tab value="reports">报表</pt-tab>
  <pt-tab value="settings" disabled>设置</pt-tab>
  <pt-tab-panel value="overview">概览内容</pt-tab-panel>
  <pt-tab-panel value="reports">报表内容</pt-tab-panel>
</pt-tabs>

尺寸

三档控件刻度：24 / 32 / 40。size 只写在 pt-tabs 上，标签跟着变。

<pt-tabs size="sm">
  <pt-tab value="a">小号</pt-tab>
  <pt-tab value="b">标签</pt-tab>
</pt-tabs>
<pt-tabs size="lg">
  <pt-tab value="a">大号</pt-tab>
  <pt-tab value="b">标签</pt-tab>
</pt-tabs>

结构

三个元素：pt-tabs 是根，标签写 pt-tab，面板写 pt-tab-panel，按 value 一一对应， 都作为 pt-tabs 的直接子元素。pt-tab 会自己挂到标签栏上，不用写 slot。

<pt-tabs value="week">
  <pt-tab value="day">日</pt-tab>
  <pt-tab value="week">周</pt-tab>
  <pt-tab-panel value="day">…</pt-tab-panel>
  <pt-tab-panel value="week">…</pt-tab-panel>
</pt-tabs>

value 缺省或对不上任何标签时，显示第一个未禁用的标签，但不改写 value。 value 对上的是禁用标签（外部指定，或选中后才被禁用）时仍显示它和它的面板，Tab 停靠点也留在它上面 —— 禁用只挡用户去选它，不改写外部给的选择，与 Radix Tabs 一致。 pt-tabs 自己的 disabled 禁用整组（Angular 表单的 FormControl.disable() 写的就是它）：不能再切换， 当前选中项与面板照常显示。

两种形态

• segmented（默认）：灰底胶囊，分量轻，给区块内切换视图（日 / 周 / 月）；
• line：下划线，整行宽、底部一条分隔线，分量重，给页面级主标签（概览 / 报表 / 设置）。

嵌套时外层用 line、内层用 segmented，层级一眼可辨。variant 与 size 只写在 pt-tabs 上， 由它同步给每个标签。

受控值

受控属性是 value，事件是 ptChange（detail 是新的 value）：

• Vue：<PtTabs v-model="tab">
• Angular：<pt-tabs [(ngModel)]="tab">，standalone 组件要在 imports 里加上 TextValueAccessor
• React：<PtTabs value={tab} onPtChange={e => setTab(e.detail)}>

ptChange 只在用户切换时发（点击，或键盘选中）；外部改 value 不发。

不冒泡

ptChange 不冒泡：标签页常常嵌套（面板里再放一组标签），而三个框架的双向绑定都挂在宿主上， 冒泡的话切换内层会改写外层的绑定。要在外层容器上统一监听，用捕获阶段 addEventListener('ptChange', fn, true)。

键盘

按 WAI-ARIA Tabs 模式：

按键	行为
Tab	进入标签栏时落在选中的标签上；再按 Tab 进入当前面板
← / →	在标签间移动，首尾循环，跳过禁用的标签；RTL 下方向对调
Home / End	跳到第一个 / 最后一个标签
Enter / Space	选中获得焦点的标签（manual 模式下用）

activation-mode 默认 automatic：方向键移到哪个标签就选中哪个。切换面板开销大（比如要请求数据）时 改成 manual，方向键只移动焦点，按 Enter / Space 才选中。

API

属性

属性	Attribute	类型	默认值	说明
activationMode	activation-mode	"automatic" | "manual"	'automatic'	键盘激活方式：`automatic` 方向键移到哪个标签就选中哪个；`manual` 只移焦点，Enter / Space 才选中
ariaLabelText	aria-label	string | undefined	—	标签栏的无障碍名称（写在 role="tablist" 上）
disabled	disabled	boolean	false	禁用整组标签：不能再切换，当前选中项照常显示（见类注释）
size	size	"lg" | "md" | "sm"	'md'	尺寸档位。三档对应 24 / 32 / 40 的控件刻度
value	value	string	''	当前选中标签的 `value`。用户切换时组件自己改写它并发 `ptChange`；外部直接赋值不发事件
variant	variant	"line" | "segmented"	'segmented'	形态：`segmented` 灰底胶囊（区块内切换）、`line` 下划线（页面级主标签）

事件

事件	detail 类型	说明
ptChange	string	用户切换标签（点击，或键盘选中）后触发，detail 是新的 `value`。外部改 `value` 不发。 **不冒泡**（与其它组件的默认相反）：标签页天然会嵌套（面板里再放一组标签），而三个框架的双向绑定 都挂在宿主上 —— Vue 的 v-model 只按 tagName 过滤冒泡事件，内外层同是 PT-TABS 拦不住；React 的 onPtChange 也会收到内层的事件。冒泡的话切换内层会把内层的 value 写进外层绑定。 要在外层容器上统一监听，用捕获阶段（`addEventListener('ptChange', fn, true)`）。

方法

方法	说明
refresh() => Promise<void>	标签或面板动态增删、改了 value / disabled 后重新同步。pt-tab / pt-tab-panel 会自己调，一般不用手动调

插槽

名称	说明
（默认）	面板 `pt-tab-panel`
tab	标签（`pt-tab` 会自动挂到这里，不用手写）

可定制的内部元素（::part()）

part	说明
list	标签栏（role="tablist"）

pt-tab

属性

属性	Attribute	类型	默认值	说明
disabled	disabled	boolean	false	禁用：点击不选中，方向键跳过它，并标注 aria-disabled
selected	selected	boolean	false	是否选中。由 pt-tabs 维护，不要手动设置
size	size	"lg" | "md" | "sm"	'md'	尺寸。由 pt-tabs 按它自己的 `size` 回写，不要手动设置
value	value	string | undefined	—	标签值，对应同值的 `pt-tab-panel`；选中时写进 pt-tabs 的 `value`
variant	variant	"line" | "segmented"	'segmented'	形态。由 pt-tabs 按它自己的 `variant` 回写，不要手动设置

插槽

名称	说明
（默认）	标签内容（文字，可带图标）

可定制的内部元素（::part()）

part	说明
base	标签内容的包裹层

pt-tab-panel

属性

属性	Attribute	类型	默认值	说明
value	value	string | undefined	—	面板值，与同值的 `pt-tab` 对应

插槽

名称	说明
（默认）	面板内容