组件：描述列表

描述列表组件用于以键值对（标签-值）的形式展示结构化信息，支持多列布局，适用于展示用户信息、配置参数、产品规格、订单详情等只读数据。它提供清晰的视觉层次，便于用户快速浏览信息。

典型使用场景：

用户个人信息展示（姓名、年龄、邮箱、电话等）
产品规格参数（尺寸、重量、颜色、材质）
订单详情（订单号、金额、状态、支付方式）
系统配置信息（数据库连接、缓存设置等）
任何需要以“字段名-字段值”形式展示的只读数据

📌 继承自视图的成员速查

本组件继承自 视图 类，可直接使用以下属性和方法：

属性： ID、左边、顶边、右边、底边、宽度、高度、背景、背景颜色、背景图像、文本、文本颜色、字体、字体大小、字体粗细、行高、边框、边框圆角、边框宽度、光标样式、显示模式、透明度、外边距、外边距底、外边距左、外边距右、外边距顶、最大高度、最大宽度、最小高度、最小宽度、内边距、内边距底、内边距左、内边距右、内边距顶、定位、CLASS、InnerHTML、OuterHTML、内容水平对齐方式、首行缩进、可视、显示层级、内联样式、禁用

方法： 追加内联样式(样式文本)、置内联样式(名称,值)、取内联样式值(名称)、取Style对象()、添加事件(事件名称, 回调函数)、删除事件(事件名称, 回调函数)、获取焦点()、清除焦点()、添加样式类(类名称)、移除样式类(类名称)、取样式类列表()、取样式类()、执行单击()、取属性值(属性名)、取属性节点(属性名)、取布局参数()、取渲染宽度()、取渲染高度()、取渲染顶边()、取渲染左边()、左侧对齐到(目标组件,偏移量)、右侧对齐到(目标组件,偏移量)、顶边对齐到(目标组件,偏移量)、底边对齐到(目标组件,偏移量)、右侧对齐到左(目标组件, 偏移量)、左侧对齐到右(目标组件, 偏移量)、底边对齐到顶(目标组件, 偏移量)、顶边对齐到底(目标组件, 偏移量)、有指定属性(属性名)、有属性()、内容可编辑()、包含CSS类(类名)、取命名空间()、取下个节点()、取下个元素()、取节点名称()、取节点类型()、取父节点()、取父元素()、取上个节点()、取上个元素()、销毁()、删除属性(属性名)、删除属性节点(属性名)、置属性值(属性名, 属性值)、置属性节点(属性节点)、取标签名()、移动(左边顶边, 宽度, 高度)、取原生对象()、置被单击回调(回调函数)、置被双击回调(回调函数)、置鼠标被进入回调(回调函数)、置鼠标被移出回调(回调函数)、置鼠标被移动回调(回调函数)、置鼠标被按下回调(回调函数)、置鼠标被抬起回调(回调函数)、置鼠标滚轮被滚动回调(回调函数)、置键盘被按下回调(回调函数)、置按键被抬起回调(回调函数)、置按键被压下回调(回调函数)、置被失去焦点回调(回调函数)、置被获得焦点回调(回调函数)

事件： 被单击(源对象,事件源)、被双击(源对象,事件源)、鼠标被进入(源对象,事件源)、鼠标被移出(源对象,事件源)、鼠标被移动(源对象,事件源)、鼠标被按下(源对象,事件源)、鼠标被抬起(源对象,事件源)、鼠标滚轮被滚动(源对象,事件源)、键盘被按下(源对象,事件源)、按键被抬起(源对象,事件源)、按键被压下(源对象,事件源)、被失去焦点(源对象,事件源)、被获得焦点(源对象,事件源)

💡 完整成员列表及详细说明请参考：视图 类

常用操作速查

操作	属性/方法	示例
设置列表标题	`标题`	`描述列表1.标题 = "用户信息"`
设置每行列数	`列数`	`描述列表1.列数 = 2`
添加单个键值对	`添加项(标签, 值)`	`描述列表1.添加项("姓名", "张三")`
批量设置键值对	`置项目数组(项目数组)`	`描述列表1.置项目数组([{label:"姓名", value:"张三"}, ...])`
清空所有键值对	`清空()`	`描述列表1.清空()`

样式美化参考

描述列表的外观可通过继承的视图属性以及 CSS 类进行美化：

整体容器：通过 宽度、背景颜色、边框（如 "1px solid #e8e8e8"）、边框圆角（建议 "8px"）等属性美化。
标题区域：标题 文本的样式可通过 字体大小（建议 "16px"）、字体粗细（"bold"）、文本颜色 控制。标题默认显示在列表顶部，背景色可单独设置。
列表项：每个键值对由标签和值组成，标签通常加粗显示（font-weight: bold），值正常显示。可通过 CSS 类自定义标签宽度、颜色、对齐方式等。
列数：列数 控制每行显示的键值对数量，布局为网格形式，列数越多，每列宽度越窄。当 列数 = 1 时，每个键值对独占一行。
内边距：通过 内边距（建议 "16px"）控制列表整体内边距，使内容不贴边。

CSS 美化示例（在项目 CSS 文件中定义）：

.my-description .desc-item {
    padding: 8px 12px;
    border-bottom: 1px solid #f0f0f0;
}
.my-description .desc-label {
    font-weight: bold;
    color: #666;
    width: 100px;
}
.my-description .desc-value {
    color: #333;
}

在代码中应用样式类：描述列表1.添加样式类("my-description")

基础示例

创建一个用户信息描述列表，包含姓名、年龄、邮箱、电话，每行显示 2 列。

变量 描述列表1 = 创建 描述列表()
描述列表1.左边 = 50
描述列表1.顶边 = 50
描述列表1.宽度 = 600
描述列表1.边框 = "1px solid #e8e8e8"
描述列表1.边框圆角 = "8px"
描述列表1.背景颜色 = "#ffffff"
描述列表1.内边距 = "16px"
描述列表1.标题 = "用户信息"
描述列表1.字体大小 = "14px"
描述列表1.列数 = 2

' 添加键值对
描述列表1.添加项("姓名", "张三")
描述列表1.添加项("年龄", "25 岁")
描述列表1.添加项("邮箱", "zhangsan@example.com")
描述列表1.添加项("电话", "138-0000-0000")

添加组件(描述列表1)

综合示例：产品规格展示

本示例展示一个产品规格表，包含多行键值对，采用 3 列布局，并显示标题“产品规格”。

' ========== 创建描述列表 ==========
变量 规格列表 = 创建 描述列表()
规格列表.左边 = 30
规格列表.顶边 = 30
规格列表.宽度 = 720
规格列表.边框 = "1px solid #e8e8e8"
规格列表.边框圆角 = "8px"
规格列表.背景颜色 = "#ffffff"
规格列表.内边距 = "16px"
规格列表.标题 = "产品规格"
规格列表.标题字体大小 = "18px"
规格列表.标题字体粗细 = "bold"
规格列表.标题颜色 = "#333"
规格列表.列数 = 3
规格列表.字体大小 = "14px"

' ========== 添加规格项 ==========
变量 规格数据 = [
    {label: "品牌", value: "VcnTech"},
    {label: "型号", value: "VT-2024"},
    {label: "颜色", value: "太空灰"},
    {label: "材质", value: "铝合金 + 玻璃"},
    {label: "重量", value: "178g"},
    {label: "屏幕尺寸", value: "6.7 英寸"},
    {label: "处理器", value: "Vcn A17"},
    {label: "存储容量", value: "256GB"},
    {label: "电池容量", value: "4500mAh"}
]

变量循环(i = 0, 取数组成员数(规格数据), 1)
    变量 项 = 规格数据[i]
    规格列表.添加项(项.label, 项.value)
结束循环

' ========== 添加底部操作按钮（使用HTML内容） ==========
' 由于描述列表不支持直接添加按钮，我们可以将其放入一个独立的按钮容器
变量 按钮容器 = 创建 弹性布局()
按钮容器.方向 = "row"
按钮容器.间距 = 12
按钮容器.左边 = 30
按钮容器.顶边 = 320
按钮容器.宽度 = 720
按钮容器.内容水平对齐 = "center"

变量 编辑按钮 = 创建 按钮()
编辑按钮.文本 = "编辑规格"
编辑按钮.背景颜色 = "#1890ff"
编辑按钮.文本颜色 = "#ffffff"
编辑按钮.边框圆角 = "6px"
编辑按钮.宽度 = 120
按钮容器.添加组件(编辑按钮)

变量 关闭按钮 = 创建 按钮()
关闭按钮.文本 = "关闭"
关闭按钮.背景颜色 = "#d9d9d9"
关闭按钮.文本颜色 = "#333"
关闭按钮.边框圆角 = "6px"
关闭按钮.宽度 = 120
按钮容器.添加组件(关闭按钮)

添加组件(按钮容器)

' 为按钮绑定事件
编辑按钮.置被单击回调((源对象) => {
    弹出提示("编辑产品规格功能")
})

关闭按钮.置被单击回调((源对象) => {
    弹出提示("已关闭详情")
})

属性详解

标题

类型： 文本型
说明： 设置或获取描述列表的标题文本。若设置为空字符串 ""，标题栏将被隐藏，直接显示键值对列表。标题默认显示在列表顶部，带有下边框或背景色。

列数

类型： 数值型
说明： 设置或获取每行显示的键值对数量，默认 1。当 列数 = 1 时，每个键值对独占一行，标签和值水平排列；当 列数 > 1 时，键值对按网格布局排列，每行显示指定数量的项目。建议根据实际数据量和容器宽度设置合适的列数。

函数详解

添加项(标签, 值)

功能： 向描述列表中添加一个键值对（标签-值）。
参数：
- 标签：文本型，必填，字段名称（如“姓名”）。
- 值：文本型，必填，字段对应的值（如“张三”）。支持任意文本内容，如果值包含 HTML，将原样渲染。
返回值： 数值型，新添加项在内部数组中的索引（从0开始）。
示例： 描述列表1.添加项("邮箱", "user@example.com")

置项目数组(项目数组)

功能： 批量设置所有键值对，会清空当前所有项，然后添加新数组中的项。
参数： 项目数组，由对象组成的数组，每个对象须包含 label 和 value 属性。
返回值： 无。

示例：

描述列表1.置项目数组([
    {label: "姓名", value: "张三"},
    {label: "年龄", value: "28"}
])

清空()

功能： 清空所有键值对，列表变为空。
返回值： 无。
示例： 描述列表1.清空()

事件说明

描述列表组件未定义特有的事件，但继承自 视图 的所有事件均可使用（如 置被单击回调 可为整个列表绑定点击事件）。

⚠️ 注意事项

列数影响布局：列数 改变布局密度，建议根据容器宽度和项数合理设置。若项数不足一行，剩余位置为空。
标签与值的对齐：标签默认左对齐，值也左对齐，但可通过 CSS 类自定义（如将值右对齐）。
值支持 HTML：值 参数支持 HTML 字符串，可用于显示链接、按钮或格式化文本，但注意 XSS 安全风险。
标题隐藏：若 标题 为空，标题栏隐藏，列表直接从键值对开始显示。
数据更新：添加或修改项后，组件会自动重新渲染，无需手动刷新。
样式覆盖：组件内部使用了默认样式（如标签加粗、边框等），可通过 CSS 类或 内联样式 覆盖。
与表格的区别：描述列表更适合展示结构化字段（字段名-值），而表格更适合展示列表数据（多行多列）。

轻语言网站开发SDK文档