bim_engine/docs-old/components/描述列表组件-Description.md

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 构造函数

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 基础使用

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)

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 自定义样式

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() 函数进行翻译。

import { t } from 'iflow-engine/services/locale';

new BimDescription({
    // ...
    items: [
        { label: t('panel.property.id'), value: '123' }
    ]
});