---
name: fms-vue-tabs
overview: 在 fms-vue 组件库中新增 Tabs 标签页组件：line 线型 + top/left/right 三种标签方向，同时支持 items 数组与 TabPane 插槽双数据源，含键盘方向键导航、懒渲染缓存、禁用态与完整 ARIA，并在演示站 App.vue 中新增展示。
design:
  architecture:
    framework: vue
  styleKeywords:
    - 克制简洁
    - 清晰分层
    - 主色指示条
  fontSystem:
    fontFamily: PingFang SC
    heading:
      size: 14px
      weight: 600
    subheading:
      size: 14px
      weight: 500
    body:
      size: 14px
      weight: 400
  colorSystem:
    primary:
      - "#0f172b"
    background:
      - "#ffffff"
      - "#f5f6f8"
    text:
      - "#1f2329"
      - "#86909c"
      - "#c9cdd4"
    functional:
      - "#e5e6eb"
todos:
  - id: create-tab-pane-and-normalize
    content: 参考 [skill:antdv-next] 核对 API 语义，创建 tab-pane.vue 并实现 tabs.vue 双数据源归一与激活管理
    status: completed
  - id: implement-tabs-interaction
    content: 在 tabs.vue 完成模板：tablist/方向键导航/懒渲染缓存/ARIA 关联
    status: completed
    dependencies:
      - create-tab-pane-and-normalize
  - id: write-tabs-styles
    content: 用 [skill:ui-ux-pro-max] 校验后编写 index.scss：top/left/right 布局、指示条与各状态样式
    status: completed
    dependencies:
      - create-tab-pane-and-normalize
  - id: add-demo-and-check
    content: App.vue 新增 Tabs 导航项与演示 section，做静态检查并汇报
    status: completed
    dependencies:
      - implement-tabs-interaction
      - write-tabs-styles
---

## 产品概述

为 fms-vue 自研 UI 组件库新增 Tabs 标签页组件，遵循 `fms-vue/开发规范.md` 约束并借鉴 `参考组件库/antdv-next` 的 Tabs 设计语义。包含 Tabs（根）与 TabPane（子声明）两个组件，用于在同一区域内分组展示内容、切换视图。

## 核心功能

- **双数据源**：支持 `items` 数组（`[{ key, label, disabled?, content? }]`）与 TabPane 插槽两种声明方式，与 Select 的 options/插槽模式一致，二选一使用。
- **line 线型指示**：激活标签底部（top）或侧边（left/right）显示主色指示条，标签栏有浅色分隔线。
- **侧边/垂直方向**：`placement` 支持 `top`（默认，横排在上）、`left`、`right`（纵向排列在左/右，内容区自适应剩余宽度）。
- **禁用态**：支持单个 TabPane 禁用与 Tabs 整组禁用，反映到原生属性与视觉（降透明 + not-allowed）。
- **键盘与无障碍**：tablist/tab/tabpanel 语义，方向键循环切换激活（top 用左右键，left/right 用上下键），roving tabindex、aria-selected/aria-controls/aria-labelledby，`:focus-visible` 焦点样式。
- **懒渲染 + 缓存**：非激活面板不渲染，首次激活后缓存（切换不销毁），符合性能优先规范。
- **自定义标签**：`#label` 插槽支持自定义标题内容（TabPane 与 items 两种模式均可用）。

## 技术栈

- Vue 3.5 `<script setup>` + Sass（项目现有技术栈，不引入新依赖）
- 样式复用 `src/theme/tokens.css` 的 `--fms-*` token，图标按需从 `@lucide/vue` 导入（本组件无需图标）
- 参照 `radio-group/radio` 的协作组件写法与 `select` 的"数组 + 插槽"双数据源模式

## 实现思路

Tabs 根组件通过 `slots.default()` 遍历插槽 vnode（展平 Fragment、过滤注释），识别 `type.name === 'TabPane'` 的子组件并提取其 props 与子插槽（default 内容、label 自定义标题）——此机制参考 antdv-next 的 `useLegacyItems`。归一化后的 panes 统一管理激活态、渲染与键盘导航；items 数组模式 normalize 为同构数据结构，两条路径输出一致的渲染结果。

### 关键技术决策

- **vnode 解析而非 provide/inject**：TabPane 是纯数据声明组件（自身渲染空），激活状态必须由根组件统一管理，根组件负责渲染 tab 头列表与内容区；这与 antd 的 TabPane 语义一致，优于 Radio 的 provide/inject 协作模式（radio 每个子项自己渲染视觉）。
- **指示条不加 JS 测量**：line 模式指示条用激活 tab 自身的 `border-bottom`/`border-left`（2px 主色）实现，标签栏底部/侧边用 1px `--fms-border`。不做滑动跟随动画，避免布局读取与高频重排，符合"过渡限低成本属性、不主动构建"的规范。
- **懒渲染 + 缓存**：`renderedKeys` Set 记录已激活 pane，模板 `v-if`（首次激活才渲染）+ `v-show`（激活显示）组合，首屏只渲染激活项且切换不重建内容。
- **激活回退**：`modelValue` 未传或指向不存在/禁用的 pane 时，回退到第一个可用 pane，且不写回 modelValue（保持受控性）。

### 实现注意

- 键盘仅遍历 enabled panes 循环移动，禁用项跳过；方向键按 `placement` 映射（top: Left/Right，left/right: Up/Down，Home/End 定位首尾）。
- 切换时先更新内部激活态再 emit `update:modelValue` 与 `change`；点击触发 `tabClick(key, event)`。
- id 用 `useId()` 生成，tab 与 tabpanel 通过 `aria-controls`/`aria-labelledby` 关联。
- 卸载无需清理（无全局监听器、无定时器）。

## 架构设计

```
Tabs（根组件）
 ├─ 数据源归一（items 数组 / TabPane 插槽 vnode 解析）→ mergedPanes
 ├─ 激活管理（modelValue 回退、select、emit）
 ├─ 渲染：nav 列表（role=tablist）+ 内容区（role=tabpanel，v-if/v-show 懒渲染）
 ├─ 键盘导航（方向键循环 + roving tabindex）
 └─ 布局：placement top（纵向堆叠）/ left|right（flex 行）
```

## 目录结构

```
fms-vue/src/components/ui/tabs/
├── tabs.vue        # [NEW] Tabs 根组件。props: modelValue/placement/disabled/items；
│                   # emits: update:modelValue/change/tabClick；实现 vnode 解析、激活管理、
│                   # 懒渲染缓存、键盘导航与 ARIA 完整模板。
├── tab-pane.vue    # [NEW] TabPane 数据声明组件。props: tabKey/label/disabled；
│                   # 插槽: default（面板内容）/ label（自定义标题）；
│                   # defineOptions({ name: 'TabPane' }) 供根组件识别；自身渲染空节点。
└── index.scss      # [NEW] 样式：top/left/right 三种布局、line 指示条、hover/disabled/focus 态、
                    # prefers-reduced-motion；全部复用 --fms-* token，tabs.vue 内 @use 引入。

fms-vue/src/App.vue # [MODIFY] 通用分组新增导航项 { key: 'tabs', label: 'Tabs 标签页' }，
                    # 新增演示 section（基础用法/items 数组/侧边方向/禁用/自定义标签/懒渲染）。
```

## 关键数据结构（伪类型）

```js
// 归一化后的 pane（items 数组与 TabPane 插槽统一输出）
{ key: String, label: String|VNode, disabled: Boolean,
  content: () => VNode[],  // 内容渲染函数（懒渲染时按需调用）
  labelVNode: () => VNode[] // 自定义标题渲染函数，无则 undefined
}
```

## 设计风格

与现有组件库一致的克制现代风格：干净的分层、克制的交互反馈、清晰的状态表达。

## 视觉要点

- **布局**：top 模式标签横排在上、内容在下，标签栏底部 1px `--fms-border` 分隔；left/right 模式为 flex 行，标签纵向排列于左/右，内容区 `flex: 1 1 auto` 自适应。垂直方向标签栏加 `--fms-border` 侧边分隔，激活标签文字主色并配 `--fms-secondary-hover` 浅背景增强选中识别。
- **指示条（line）**：top 模式激活标签自身 2px 主色下边框，left/right 为 2px 主色侧边框，无滑动动画，稳定且零布局读取。
- **状态反馈**：hover 文字变主色；禁用用 `--fms-disabled-text` + `not-allowed` 光标并降透明；选中不单靠颜色，同时用指示条与文字粗细双重表达。
- **间距**：标签 padding 约 0 16px、高度对齐 `--fms-control-height`（32px），标签间距紧凑；内容区 padding 16px 0 与标签栏对齐。
- **焦点**：`:focus-visible` 主色 outline 2px + 2px offset。
- **动画**：仅 hover 文字颜色过渡（低成本属性），`prefers-reduced-motion` 下关闭。

## Agent 扩展

### Skill

- **antdv-next**
- 用途：核对 antdv-next Tabs/TabPane 的 API 语义（tabKey 解析顺序、键盘交互、ARIA 细节），确保借鉴准确。
- 预期产出：tabs.vue 的 props/事件/键盘映射与参考库一致，无遗漏交互。
- **ui-ux-pro-max**
- 用途：辅助校验 Tabs 视觉细节（间距、指示条、禁用/焦点状态表达），与组件库整体风格对齐。
- 预期产出：index.scss 的视觉规格（间距、指示条、状态色）符合现代组件库实践。