f2460fb981
- 将包名从 @fishdingding/bim-engine-sdk 改为 iflow-engine - 将构建输出文件从 bim-engine-sdk.*.js 改为 iflow-engine.*.js - 将全局变量从 LyzBimEngineSDK 改为 IflowEngine - 将第三方引擎SDK从本地引入改为npm包引入 (iflow-engine-base) - 移除本地 src/engine_base 目录，移至回收站 - 更新所有文档和demo中的引用
128 lines
4.1 KiB
Markdown
128 lines
4.1 KiB
Markdown
# 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 'iflow-engine/services/locale';
|
||
|
||
new BimDescription({
|
||
// ...
|
||
items: [
|
||
{ label: t('panel.property.id'), value: '123' }
|
||
]
|
||
});
|
||
```
|