bim_engine/docs/components/折叠面板组件-Collapse.md

Collapse 折叠面板组件

BimCollapse 是一个通用的折叠面板组件，支持手风琴模式、自定义内容和标题。常用于属性面板、设置菜单等场景。

1. 组件概述

• 类名: BimCollapse
• 文件路径: src/components/collapse/index.ts
• 样式文件: src/components/collapse/index.css
• 类型定义: src/components/collapse/types.ts

该组件实现了 IBimComponent 接口，具备完整的生命周期管理、主题响应和国际化支持能力。

2. API 文档

2.1 构造函数

const collapse = new BimCollapse(options: CollapseOptions);

2.2 CollapseOptions 配置项

属性	类型	默认值	说明
container	HTMLElement | string	-	(必填) 挂载容器或其 ID
items	CollapseItemConfig[]	-	(必填) 面板项列表
accordion	boolean	false	是否开启手风琴模式（一次只能展开一项）
activeIds	string[]	[]	初始展开的面板 ID 列表
bordered	boolean	true	是否显示外边框
ghost	boolean	false	是否开启幽灵模式（无背景、无边框）
className	string	-	自定义类名
onChange	(activeIds: string[]) => void	-	切换面板时的回调函数

2.3 CollapseItemConfig 面板项配置

属性	类型	说明
id	string	(必填) 唯一标识符
title	string	(必填) 标题文本的翻译键 (例如 'panel.property.base')
content	string | HTMLElement	(必填) 面板内容
icon	string	标题左侧图标 (SVG 字符串)
extra	string | HTMLElement	标题栏右侧额外内容
disabled	boolean	是否禁用该面板
className	string	自定义面板类名

2.4 实例方法

• toggleItem(id: string): 切换指定面板的展开/折叠状态。
• setTheme(theme: ThemeConfig): 设置组件主题 (CSS 变量映射)。
• setLocales(): 更新组件文本 (标题翻译)。
• destroy(): 销毁组件，清理资源。

3. 使用示例

import { BimCollapse } from '../components/collapse/index';

const collapse = new BimCollapse({
    container: document.getElementById('panel'),
    accordion: true,
    activeIds: ['base'],
    items: [
        {
            id: 'base',
            title: 'panel.property.base', // 必须是翻译键
            content: document.createElement('div'), // 或 HTML 字符串
            icon: '<svg>...</svg>'
        },
        {
            id: 'advanced',
            title: 'panel.property.advanced',
            content: 'Advanced Content',
            disabled: true
        }
    ],
    onChange: (ids) => {
        console.log('Current active panels:', ids);
    }
});

4. 主题支持

组件自动订阅主题变更，并通过 CSS 变量控制样式：

• 面板背景: theme.panelBackground
• 边框颜色: theme.border
• 文本颜色: theme.textPrimary
• 标题栏背景: theme.componentHover (默认) / theme.componentBackground
• 禁用态颜色: theme.textSecondary

5. 国际化支持

组件自动订阅语言变更：

• 标题 (title): 会自动使用 t(config.title) 进行翻译。确保传入的是有效的翻译键。
• 内容 (content): 如果内容包含文本，请确保内容生成时已翻译，或内容本身具有响应国际化的能力（如使用 BimDescription）。