bim_engine/docs-old/components/标签页组件-Tab.md

1. 组件概述

• 名称：BimTab
• 位置：src/components/tab/
• 功能：渲染固定标签页（不支持运行期增删），支持点击切换、禁用、可选内容托管。主题由全局 ThemeManager 提供，文案通过 t() 翻译。
• 使用方式：直接通过构造函数 + init() 创建；本项目内目前仅在 ConstructTreeManagerBtn 弹窗中使用（无专门 Manager）。

2. 组件类 API（BimTab）

• constructor(options: TabOptions)：创建实例并挂载到 options.container。
• init(): void：渲染头部与内容，订阅主题/语言。
• activateTab(tabId: string): void：切换激活标签，触发 onChange。
• setTheme(theme: ThemeConfig): void：应用主题变量。
• setLocales(): void：刷新标题文案。
• destroy(): void：解绑事件、取消订阅、移除 DOM。

3. 分化组件

• 当前无子类或变体，后续可扩展滚动、溢出折叠等能力。

4. 使用场景说明

• ConstructTreeManagerBtn 弹窗：顶部三段标签（构件/系统/空间），构件标签承载原有 Tree，系统/空间暂为空容器。
• 适用于固定分区切换，内容简单或由外部回调控制。

5. UI 结构

div.bim-tab
  div.bim-tab__nav [role=tablist]
    button.bim-tab__item[role=tab][aria-selected][aria-disabled?]
      span.bim-tab__icon? (可选)
      span.bim-tab__title
  div.bim-tab__content
    div.bim-tab__panel[role=tabpanel][aria-labelledby=tab-xxx]
    ...

• 状态类：.is-active、.is-disabled。
• 内容区：仅切换显示，不强制填充（可为空）。

6. 逻辑流程

1. constructor：创建根节点、头部、内容容器；缓存 tab 数据；挂载到传入容器。
2. init：渲染头部按钮与内容面板，设置初始激活；应用当前主题/语言；订阅主题、语言变更。
3. 交互：点击非禁用按钮 → activateTab 更新头部/面板状态 → 回调 onChange。
4. 销毁：解绑点击监听、取消订阅、清空映射并移除 DOM。

7. 国际化

• 标题：t(tab.title)，若翻译键不存在则回退原文。
• 新增翻译键：tab.component / tab.system / tab.space（已在 zh-CN.ts、en-US.ts 注册）。
• setLocales()：遍历头部按钮刷新标题文案；订阅 localeManager 自动响应语言切换。

8. 主题支持

• 来自 themeManager，不从配置传入。
• 使用的变量（设置在根节点上）：
  • --bim-tab-bg、--bim-tab-nav-bg
  • --bim-tab-text、--bim-tab-text-secondary、--bim-tab-text-active
  • --bim-tab-border、--bim-tab-hover-bg、--bim-tab-active-bg
  • --bim-tab-icon
• setTheme(theme)：根据 ThemeConfig 写入上述 CSS 变量。

9. 使用示例

const tabMount = document.createElement('div');
const tab = new BimTab({
  container: tabMount,
  tabs: [
    { id: 'component', title: 'tab.component', content: componentEl },
    { id: 'system', title: 'tab.system', content: systemEl },
    { id: 'space', title: 'tab.space', content: spaceEl },
  ],
  activeId: 'component',
  onChange: (id) => {
    // 根据 id 做额外逻辑（如埋点、动态加载）
  },
});
tab.init();

10. 实现细节

• 仅支持固定 tabs：TabOptions.tabs 为初始化列表，不提供新增/删除接口。
• 内容托管两种方式：content: HTMLElement（append）或 content: string（innerHTML）。未提供内容时面板为空。
• 事件绑定：头部使用事件委托绑定 click，销毁时移除。
• 访问性：头部 role=tab、aria-selected、aria-disabled；面板 role=tabpanel 且 aria-labelledby 对应头部 id。
• 主题/语言订阅：localeManager.subscribe、themeManager.subscribe，销毁时必须取消。

11. 类型定义

• 位置：src/components/tab/index.type.ts
• 主要类型：
  • TabItem: { id; title; disabled?; icon?; content?; meta? }
  • TabOptions: { container; tabs; activeId?; onChange? }

12. 文件清单

• src/components/tab/index.ts：组件实现
• src/components/tab/index.type.ts：类型定义
• src/components/tab/index.css：样式
• （无 Manager）当前仅在 ConstructTreeManagerBtn 中直接使用