Tabs

Tabs 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 Tabs 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，Tabs 使用 Tab 子组件，通过 title prop 设置标题，子节点作为面板内容：

1import { Tabs, Tab } from "@lenso/ui";2
3export default function App() {4  return (5    <Tabs aria-label="Options">6      <Tab key="photos" title="Photos">7        <Card>Content here</Card>8      </Tab>9    </Tabs>10  );11}

在 v3 中，Tabs 改为复合组件，Tab 与 Panel 分别独立：

1import { Tabs } from "@lenso/ui";2
3export default function App() {4  return (5    <Tabs>6      <Tabs.ListContainer>7        <Tabs.List aria-label="Options">8          <Tabs.Tab id="photos">9            Photos10            <Tabs.Indicator />11          </Tabs.Tab>12        </Tabs.List>13      </Tabs.ListContainer>14      <Tabs.Panel id="photos">15        <Card>Content here</Card>16      </Tabs.Panel>17    </Tabs>18  );19}

主要变化

1. 组件结构

v2： Tabs 与 Tab 子节点（title prop + 子节点作为面板）
v3： 复合组件（Tabs.ListContainer、Tabs.List、Tabs.Tab、Tabs.Indicator、Tabs.Separator、Tabs.Panel）

2. Prop 变更

v2 prop	v3 位置	说明
`key`（在 Tab 上）	`id`（在 Tab 与 Panel 上）	prop 名称变更
`title`（在 Tab 上）	—	内容直接放入 `Tabs.Tab`
`isVertical`	`orientation`	改为 `"horizontal"` \| `"vertical"`
`placement`	—	通过 `orientation` 与布局表达
`variant`	`variant`	简化为仅 `primary` \| `secondary`
`color`	—	已移除（请改用 Tailwind CSS）
`size`	—	已移除（请改用 Tailwind CSS）
`radius`	—	已移除（请改用 Tailwind CSS）
`classNames`	—	改在各子组件上使用 `className` prop
`disableCursorAnimation`	—	改用 `Tabs.Indicator` 子组件控制
`disableAnimation`	—	已移除（动画机制已不同）
`fullWidth`	—	已移除（请改用 Tailwind CSS）

3. 组件层面的变化

Tab 标识：key → id（Tabs.Tab 与 Tabs.Panel 之间必须一致）
Tab 内容：title prop → 直接将子节点放入 Tabs.Tab
Panel 内容：原本作为 Tab 子节点 → 改为独立的 Tabs.Panel 组件
指示器：自动光标 → 显式的 Tabs.Indicator 子组件
分隔符：新增 Tabs.Separator 组件，用于在 Tab 之间显示分隔线

迁移示例

受控 Tabs

1import { useState } from "react";2
3const [selected, setSelected] = useState("photos");4
5<Tabs selectedKey={selected} onSelectionChange={setSelected}>6  <Tab key="photos" title="Photos">Content</Tab>7  <Tab key="music" title="Music">Content</Tab>8</Tabs>

带图标

1<Tabs aria-label="Options">2  <Tab key="photos" title={<><PhotoIcon /> Photos</>}>3    Content4  </Tab>5</Tabs>

带分隔符

在 v3 中，你可以在每个 Tabs.Tab 内部（除第一个之外）放入 Tabs.Separator 来显示 Tab 之间的分隔线。这是 v2 没有的新增能力。

1<Tabs>2  <Tabs.ListContainer>3    <Tabs.List aria-label="Options">4      <Tabs.Tab id="photos">5        Photos6        <Tabs.Indicator />7      </Tabs.Tab>8      <Tabs.Tab id="music">9        <Tabs.Separator />10        Music11        <Tabs.Indicator />12      </Tabs.Tab>13      <Tabs.Tab id="videos">14        <Tabs.Separator />15        Videos16        <Tabs.Indicator />17      </Tabs.Tab>18    </Tabs.List>19  </Tabs.ListContainer>20  <Tabs.Panel id="photos">Photos content</Tabs.Panel>21  <Tabs.Panel id="music">Music content</Tabs.Panel>22  <Tabs.Panel id="videos">Videos content</Tabs.Panel>23</Tabs>

组件结构

v3 Tabs 遵循以下结构：

1Tabs (Root)2  ├── Tabs.ListContainer3  │   └── Tabs.List4  │       └── Tabs.Tab5  │           ├── Tabs.Separator (optional, omit on first tab)6  │           └── Tabs.Indicator (optional)7  └── Tabs.Panel (one per tab, matching id)

总结

组件结构：必须使用复合组件（Tabs.ListContainer、Tabs.List、Tabs.Tab、Tabs.Indicator、Tabs.Separator、Tabs.Panel）
Tab 标识：key → id（Tab 与 Panel 之间需保持一致）
Tab 内容：移除 title prop——内容直接放入 Tabs.Tab
Panel 分离：面板内容移至独立的 Tabs.Panel 组件
指示器：必须显式在每个 Tab 内使用 Tabs.Indicator
方向：isVertical → orientation prop
样式：variant 简化为 primary | secondary；color、size、radius、placement 已移除——更多自定义请使用 Tailwind
移除 classNames：改在各子组件上使用 className prop
分隔符（新增）：在 Tabs.Tab 内使用 Tabs.Separator 显示 Tab 之间的分隔线（v2 无对应能力）