97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# Collapse 折叠面板组件
|
|
|
|
`BimCollapse` 是一个通用的折叠面板组件，支持手风琴模式、自定义内容和标题。常用于属性面板、设置菜单等场景。
|
|
|
|
## 1. 组件概述
|
|
|
|
- **类名**: `BimCollapse`
|
|
- **文件路径**: `src/components/collapse/index.ts`
|
|
- **样式文件**: `src/components/collapse/index.css`
|
|
- **类型定义**: `src/components/collapse/types.ts`
|
|
|
|
该组件实现了 `IBimComponent` 接口，具备完整的生命周期管理、主题响应和国际化支持能力。
|
|
|
|
## 2. API 文档
|
|
|
|
### 2.1 构造函数
|
|
|
|
```typescript
|
|
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. 使用示例
|
|
|
|
```typescript
|
|
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`）。 |