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

This commit is contained in:
yuding
2025-12-22 16:41:24 +08:00
parent ed0414c75b
commit e1bb5558ff
19 changed files with 2640 additions and 1856 deletions

View File

@@ -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' }
]
});
```