feat: enhance description component, update property panel with tabs, and refine docs

2025-12-22 16:41:24 +08:00
parent ed0414c75b
commit e1bb5558ff
19 changed files with 2640 additions and 1856 deletions
--- a/docs/components/collapse.md
+++ b/docs/components/collapse.md
@@ -1,69 +1,97 @@
-# Collapse 组件文档
-
-> **注意**: 本组件为 UI 组件，必须通过 Manager（如 `PropertyPanelManager`）封装后使用，不可直接在业务代码中实例化。
-
-## 1. 组件概述
+# Collapse 折叠面板组件

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

-## 2. API 参考
+## 1. 组件概述

-### 2.1 配置项 `CollapseOptions`
+- **类名**: `BimCollapse`
+- **文件路径**: `src/components/collapse/index.ts`
+- **样式文件**: `src/components/collapse/index.css`
+- **类型定义**: `src/components/collapse/types.ts`
+
+该组件实现了 `IBimComponent` 接口，具备完整的生命周期管理、主题响应和国际化支持能力。
+
+## 2. API 文档
+
+### 2.1 构造函数

 ```typescript
-interface CollapseOptions {
-    container: HTMLElement | string;  // 挂载容器
-    items: CollapseItemConfig[];      // 面板项列表
-    accordion?: boolean;              // 是否开启手风琴模式 (默认 false)
-    activeIds?: string[];             // 初始展开的 ID 列表
-    bordered?: boolean;               // 是否显示边框 (默认 true)
-    ghost?: boolean;                  // 是否幽灵模式 (默认 false)
-    className?: string;               // 自定义类名
-    onChange?: (activeIds: string[]) => void; // 切换回调
-}
+const collapse = new BimCollapse(options: CollapseOptions);
 ```

-### 2.2 面板项配置 `CollapseItemConfig`
+### 2.2 CollapseOptions 配置项

-```typescript
-interface CollapseItemConfig {
-    id: string;                       // 唯一标识
-    title: string;                    // 标题翻译键 (例如 'panel.base')
-    content: string | HTMLElement;    // 内容
-    icon?: string;                    // 标题图标 (SVG)
-    extra?: string | HTMLElement;     // 标题右侧额外内容
-    disabled?: boolean;               // 是否禁用
-    className?: string;               // 自定义类名
-}
-```
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|-------|------|
+| `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 方法
+### 2.3 CollapseItemConfig 面板项配置

-*   `toggleItem(id: string)`: 切换指定面板的展开/折叠状态。
-*   `setLocales()`: 更新组件文本（通常自动调用）。
-*   `destroy()`: 销毁组件。
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | **(必填)** 唯一标识符 |
+| `title` | `string` | **(必填)** 标题文本的**翻译键** (例如 `'panel.property.base'`) |
+| `content` | `string \| HTMLElement` | **(必填)** 面板内容 |
+| `icon` | `string` | 标题左侧图标 (SVG 字符串) |
+| `extra` | `string \| HTMLElement` | 标题栏右侧额外内容 |
+| `disabled` | `boolean` | 是否禁用该面板 |
+| `className` | `string` | 自定义面板类名 |

-## 3. 使用示例 (在 Manager 中)
+### 2.4 实例方法
+
+- **`toggleItem(id: string)`**: 切换指定面板的展开/折叠状态。
+- **`setTheme(theme: ThemeConfig)`**: 设置组件主题 (CSS 变量映射)。
+- **`setLocales()`**: 更新组件文本 (标题翻译)。
+- **`destroy()`**: 销毁组件，清理资源。
+
+## 3. 使用示例

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

-// 在 Manager 的方法中
 const collapse = new BimCollapse({
-    container: this.containerElement,
+    container: document.getElementById('panel'),
    accordion: true,
+    activeIds: ['base'],
    items: [
        {
-            id: 'item1',
-            title: 'my.title.key', // 翻译键
-            content: '<div>Content Here</div>'
+            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. 国际化
+## 4. 主题支持

-组件会自动订阅 `localeManager`。
-*   **标题**: `config.title` 必须是翻译键。
-*   **内容**: 如果内容包含文本，请确保内容生成时已翻译，或内容本身具有响应国际化的能力。
+组件自动订阅主题变更，并通过 CSS 变量控制样式：
+
+- **面板背景**: `theme.panelBackground`
+- **边框颜色**: `theme.border`
+- **文本颜色**: `theme.textPrimary`
+- **标题栏背景**: `theme.componentHover` (默认) / `theme.componentBackground`
+- **禁用态颜色**: `theme.textSecondary`
+
+## 5. 国际化支持
+
+组件自动订阅语言变更：
+- **标题 (`title`)**: 会自动使用 `t(config.title)` 进行翻译。确保传入的是有效的翻译键。
+- **内容 (`content`)**: 如果内容包含文本，请确保内容生成时已翻译，或内容本身具有响应国际化的能力（如使用 `BimDescription`）。
--- a/docs/components/description.md
+++ b/docs/components/description.md
@@ -0,0 +1,127 @@
+# Description 描述列表组件
+
+`BimDescription` 组件用于展示一组键值对（Key-Value）数据，常用于详情页、属性面板等场景。
+
+## 1. 组件概述
+
+- **类名**: `BimDescription`
+- **文件路径**: `src/components/description/index.ts`
+- **样式文件**: `src/components/description/index.css`
+- **类型定义**: `src/components/description/types.ts`
+
+该组件是一个**纯展示组件**，其特点是：
+- **不内置国际化**: 为了最大灵活性，Label 和 Value 均直接显示传入的字符串/元素，不调用翻译函数。调用者应负责传入已翻译的文本。
+- **高度定制化**: 支持全局或行级的颜色、Padding、字体大小定制。
+- **布局灵活**: 支持普通列表模式和带边框的表格模式（Key-Value 间有纵向分割线）。
+
+## 2. API 文档
+
+### 2.1 构造函数
+
+```typescript
+const description = new BimDescription(options: DescriptionOptions);
+```
+
+### 2.2 DescriptionOptions 配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|-------|------|
+| `container` | `HTMLElement \| string` | - | **(必填)** 挂载容器或其 ID |
+| `items` | `DescriptionItem[]` | - | **(必填)** 数据项列表 |
+| `bordered` | `boolean` | `false` | 是否显示边框。开启后会显示行间分割线以及 Key-Value 之间的纵向分割线 |
+| `labelWidth` | `string` | - | 标签列的固定宽度 (如 `'80px'`)，不设置则自适应 |
+| `fontSize` | `string` | `'14px'` | 全局字体大小 (如 `'12px'`) |
+| `labelColor` | `string` | `theme.textSecondary` | 全局标签颜色 |
+| `valueColor` | `string` | `theme.textPrimary` | 全局内容颜色 |
+| `labelPadding` | `string` | `'0 4px'` | 标签单元格内边距 (CSS padding 语法) |
+| `valuePadding` | `string` | `'0 4px'` | 内容单元格内边距 (CSS padding 语法) |
+| `className` | `string` | - | 自定义类名 |
+
+### 2.3 DescriptionItem 数据项
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | 标签文本 (直接显示，在非 bordered 模式下会自动添加冒号) |
+| `value` | `string \| HTMLElement` | 内容文本或 DOM 元素 |
+| `labelColor` | `string` | 行级自定义标签颜色 (优先级高于全局) |
+| `valueColor` | `string` | 行级自定义内容颜色 (优先级高于全局) |
+| `className` | `string` | 自定义行类名 |
+
+### 2.4 实例方法
+
+- **`setItems(items: DescriptionItem[])`**: 动态更新数据列表。
+- **`setTheme(theme: ThemeConfig)`**: <20><>置组件主题 (通常自动调用)。
+- **`destroy()`**: 销毁组件，清理 DOM 和事件订阅。
+
+## 3. 使用示例
+
+### 3.1 基础使用
+
+```typescript
+new BimDescription({
+    container: document.getElementById('container'),
+    labelWidth: '80px',
+    items: [
+        { label: 'Name', value: 'Wall-01' },
+        { label: 'ID', value: 'E-1001' },
+        { label: 'Level', value: 'Level 1' }
+    ]
+});
+```
+
+### 3.2 带边框的表格模式 (Bordered)
+
+```typescript
+new BimDescription({
+    container: document.getElementById('container'),
+    bordered: true,
+    fontSize: '12px',
+    labelPadding: '4px 8px',
+    valuePadding: '4px 8px',
+    items: [
+        { label: 'Material', value: 'Concrete' },
+        { label: 'Density', value: '2400 kg/m³' }
+    ]
+});
+```
+
+### 3.3 自定义样式
+
+```typescript
+new BimDescription({
+    container: 'container',
+    labelColor: '#999',
+    valueColor: '#333',
+    items: [
+        { 
+            label: 'Status', 
+            value: '<span style="color: green">Active</span>',
+            labelColor: 'blue' // 单独覆盖此行的标签颜色
+        }
+    ]
+});
+```
+
+## 4. 主题支持
+
+组件会自动响应系统主题变更。默认映射关系如下：
+
+- **文本颜色**: `theme.textPrimary`
+- **标签颜色**: `theme.textSecondary`
+- **边框颜色**: `theme.border`
+- **标签背景 (仅 Bordered 模式)**: `theme.background` (用于轻微区分 Key 和 Value)
+
+## 5. 国际化支持
+
+**组件内部不进行翻译**。调用者应在传入 `label` 之前使用 `t()` 函数进行翻译。
+
+```typescript
+import { t } from 'bim-engine-sdk/services/locale';
+
+new BimDescription({
+    // ...
+    items: [
+        { label: t('panel.property.id'), value: '123' }
+    ]
+});
+```