组件：列表框

列表框组件是一个高度可定制的列表容器，基于 div 标签封装，用于展示一系列项目。它不预设每个项目的样式，而是通过回调函数让开发者自定义每个项目的渲染内容，从而实现灵活的列表展示。支持添加、插入、删除、更新项目等数据操作，以及分隔线自定义、内容拉伸等布局控制。适用于任何需要列表展示的场景，尤其是每个列表项布局不一致或需要复杂交互的情况。

典型使用场景：

联系人列表（头像 + 姓名 + 状态）
消息通知列表（标题 + 时间 + 未读标记）
商品列表（缩略图 + 名称 + 价格）
设置菜单（图标 + 标题 + 右侧箭头）
任何需要自定义列表项布局的数据展示

📌 继承自视图的成员速查

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

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

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

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

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

常用操作速查

操作	属性/方法	示例
设置是否拉伸内容（隐藏滚动条）	`拉伸内容`	`列表框1.拉伸内容 = 真`
自定义分隔线样式	`分隔线样式`、`分隔线颜色`、`分隔线高度` 等	`列表框1.分隔线颜色 = "#eee"`
添加单个项目	`添加项目(项目对象)`	`列表框1.添加项目({标题:"张三", 标记:1})`
批量添加项目	`添加项目集(项目对象数组)`	`列表框1.添加项目集([{...}, {...}])`
插入项目	`插入项目(索引, 项目对象)`	`列表框1.插入项目(0, {标题:"置顶项"})`
删除项目	`删除项目(索引)`	`列表框1.删除项目(2)`
更新项目	`更新项目(索引, 项目对象)`	`列表框1.更新项目(1, {标题:"新名称"})`
获取所有项目	`取项目集合()`	`变量全部 = 列表框1.取项目集合()`
清空列表	`清空()`	`列表框1.清空()`
触发渲染	`渲染()`	`列表框1.渲染()`
自定义每个项目的渲染	`置请求加载项目回调(回调函数)`	`列表框1.置请求加载项目回调((集合, 索引) => { ... 返回组件 ... })`

样式美化参考

列表框本身的样式可通过继承的视图属性调整，而每个项目的样式由自定义渲染回调决定。

整体容器：设置 宽度、高度、背景颜色、边框、边框圆角 等，可控制列表整体的外观。
内容拉伸：当 拉伸内容 = 真 时，列表框高度会自动适应所有项目的高度总和，且不显示滚动条；当为 假（默认）时，超出高度会出现滚动条。
分隔线控制：
- 分隔线样式：可选 solid（实线）、dashed（虚线）、dotted（点线）等。
- 分隔线颜色：自定义分隔线颜色。
- 分隔线高度：分隔线的粗细。
- 分隔线间距：分隔线上下留白。
- 分隔线左右间距：分隔线左右缩进。
- 也可通过 置自定义分隔线配置 传入完整的 CSS 样式对象，进行更精细的控制。
项目渲染：在回调中返回任意视图组件（如 标签、弹性布局 等），可自由组合图文、按钮、图标等，实现高度定制化。

基础示例

创建一个简单的文本列表，每个项目显示一个标题，并添加分隔线。

变量 列表框1 = 创建 列表框()
列表框1.左边 = 50
列表框1.顶边 = 50
列表框1.宽度 = 300
列表框1.高度 = 200
列表框1.拉伸内容 = 假
列表框1.分隔线样式 = "solid"
列表框1.分隔线颜色 = "#e0e0e0"
列表框1.分隔线高度 = 1
列表框1.分隔线间距 = 4

' 添加数据
列表框1.添加项目({标题: "选项一", 标记: 1})
列表框1.添加项目({标题: "选项二", 标记: 2})
列表框1.添加项目({标题: "选项三", 标记: 3})

' 自定义渲染回调
列表框1.置请求加载项目回调((项目集合, 索引) => {
    变量 项 = 项目集合[索引]
    变量 标签 = 创建 标签()
    标签.文本 = 项.标题
    标签.内边距 = "8px 12px"
    返回 标签
})

列表框1.渲染()
添加组件(列表框1)

综合示例：联系人列表

本示例展示一个带头像和状态的联系人列表，每个项目使用弹性布局水平排列，并响应用户点击。

' ========== 创建列表框 ==========
变量 联系人列表 = 创建 列表框()
联系人列表.左边 = 20
联系人列表.顶边 = 20
联系人列表.宽度 = 360
联系人列表.高度 = 400
联系人列表.背景颜色 = "#ffffff"
联系人列表.边框 = "1px solid #e8e8e8"
联系人列表.边框圆角 = 8
联系人列表.内边距 = "8px"
联系人列表.分隔线样式 = "solid"
联系人列表.分隔线颜色 = "#f0f0f0"
联系人列表.分隔线高度 = 1
联系人列表.分隔线左右间距 = 12
添加组件(联系人列表)

' ========== 准备数据 ==========
变量 数据 = [
    { 姓名: "张三", 头像: "https://i.pravatar.cc/40?img=1", 状态: "在线" },
    { 姓名: "李四", 头像: "https://i.pravatar.cc/40?img=2", 状态: "离线" },
    { 姓名: "王五", 头像: "https://i.pravatar.cc/40?img=3", 状态: "忙碌" },
    { 姓名: "赵六", 头像: "https://i.pravatar.cc/40?img=4", 状态: "在线" }
]
联系人列表.添加项目集(数据)

' ========== 自定义渲染回调 ==========
联系人列表.置请求加载项目回调((项目集合, 索引) => {
    变量 项 = 项目集合[索引]
    
    ' 创建一个水平弹性布局作为项目容器
    变量 容器 = 创建 弹性布局()
    容器.方向 = "row"
    容器.侧轴对齐 = "center"
    容器.内边距 = "6px 0"
    容器.宽度 = 匹配父
    容器.高度 = 48
    
    ' 头像（使用图片框）
    变量 头像 = 创建 图片框()
    头像.图片宽度 = 36
    头像.图片高度 = 36
    头像.边框圆角 = "18px"  ' 圆形
    头像.图片 = 项.头像
    头像.替代文本 = 项.姓名
    容器.添加组件(头像)
    
    ' 姓名标签
    变量 姓名标签 = 创建 标签()
    姓名标签.文本 = 项.姓名
    姓名标签.字体大小 = "15px"
    姓名标签.字体粗细 = "bold"
    姓名标签.文本颜色 = "#333"
    姓名标签.左边距 = 12
    姓名标签.宽度 = 100
    容器.添加组件(姓名标签)
    
    ' 状态标签（带颜色点）
    变量 状态容器 = 创建 弹性布局()
    状态容器.方向 = "row"
    状态容器.侧轴对齐 = "center"
    状态容器.主轴对齐 = "flex-end"
    状态容器.宽度 = "flex-grow"  ' 占满剩余空间
    
    变量 状态点 = 创建 标签()
    状态点.文本 = "●"
    状态点.字体大小 = 12
    判断(项.状态)
        分支 "在线"
            状态点.文本颜色 = "#52c41a"
        分支 "离线"
            状态点.文本颜色 = "#d9d9d9"
        分支 "忙碌"
            状态点.文本颜色 = "#ff4d4f"
        分支 默认
            状态点.文本颜色 = "#d9d9d9"
    结束 判断
    状态容器.添加组件(状态点)
    
    变量 状态文本 = 创建 标签()
    状态文本.文本 = " " + 项.状态
    状态文本.字体大小 = 12
    状态文本.文本颜色 = "#999"
    状态容器.添加组件(状态文本)
    
    容器.添加组件(状态容器)
    
    返回 容器
})

' ========== 渲染列表 ==========
联系人列表.渲染()

' ========== 添加点击事件（整体点击） ==========
' 由于每个项目是动态生成的，我们可以为列表框本身添加点击回调，
' 然后通过事件对象判断点击的具体项目（需结合 DOM 层级判断），
' 此处演示简单的点击弹出提示。
联系人列表.置被单击回调((源对象, 事件对象) => {
    ' 在实际项目中，可以通过事件对象获取点击的目标元素，
    ' 然后向上查找对应的项目容器，获取绑定的数据索引。
    ' 简化演示：直接弹出提示
    弹出提示("您点击了列表项")
})

属性详解

拉伸内容

类型： 逻辑型
说明： 设置是否拉伸列表内容以填满容器高度。当为 真 时，列表项会全部展示，隐藏滚动条；当为 假（默认）时，超出容器高度会出现垂直滚动条。

分隔线样式

类型： 文本型
说明： 设置项目之间的分隔线边框样式，支持 "solid"、"dashed"、"dotted" 等，默认为 "solid"。

分隔线间距

类型： 整数型|文本型
说明： 设置分隔线上下方的间距，默认为 "1px"。可传入数值（单位 px）或字符串。

分隔线颜色

类型： 文本型
说明： 设置分隔线的颜色，支持 CSS 颜色值，默认 "#e0e0e0"。

分隔线高度

类型： 整数型|文本型
说明： 设置分隔线的粗细（高度），默认为 "1px"。

分隔线左右间距

类型： 整数型|文本型
说明： 设置分隔线左右两侧的缩进距离，默认为 0。例如 12 会使分隔线两端各留出 12px 空白。

函数详解

置自定义分隔线配置(值)

功能： 通过传入一个样式对象，自定义分隔线的所有 CSS 样式，覆盖单独设置的分隔线属性。
参数： 值，对象类型，键为 CSS 属性名（驼峰式），值为属性值。例如 {"height": "2px", "backgroundColor": "#ccc", "margin": "4px 0"}。
返回值： 无。

示例：

列表框1.置自定义分隔线配置({"height": "2px", "backgroundColor": "#eee", "margin": "6px 0"})

添加项目(项目对象)

功能： 向列表数据集合末尾添加一个项目。
参数： 项目对象，可以是任意数据类型（对象、字符串、数字等），推荐使用对象以便包含多个字段。
返回值： 无。
示例： 列表框1.添加项目({标题: "新项目", 值: 123})

插入项目(索引, 项目对象)

功能： 在指定索引位置插入一个项目。
参数： 索引（数值型，从0开始），项目对象（任意类型）。
返回值： 无。
示例： 列表框1.插入项目(0, {标题: "置顶项"})

添加项目集(项目对象数组)

功能： 批量添加多个项目到末尾。
参数： 项目对象数组，数组中的每个元素为任意类型。
返回值： 无。
示例： 列表框1.添加项目集([{标题:"A"}, {标题:"B"}])

插入项目集(索引, 项目对象数组)

功能： 在指定索引位置批量插入多个项目。
参数： 索引（数值型），项目对象数组。
返回值： 无。

删除项目(索引)

功能： 删除指定索引的项目。
参数： 索引（数值型）。
返回值： 无。

更新项目(索引, 项目对象)

功能： 替换指定索引的项目为新数据。
参数： 索引（数值型），项目对象（新数据）。
返回值： 无。

取项目集合()

功能： 获取当前列表的数据集合（数组）。
返回值： 数组，包含所有项目对象。
示例： 变量所有项目 = 列表框1.取项目集合()

取项目数()

功能： 获取当前列表项目数量。
返回值： 数值型。
示例： 变量数量 = 列表框1.取项目数()

清空()

功能： 清空所有数据，列表变为空。
返回值： 无。

渲染()

功能： 根据当前数据集合和自定义渲染回调，重新生成列表项 DOM。通常在添加/修改数据后调用。
返回值： 无。

置请求加载项目回调(回调函数)

功能： 设置每个项目的渲染回调函数。这是列表框最核心的方法，开发者在此回调中创建并返回一个视图组件（如 标签、弹性布局 等），用于表示每个列表项的内容。
参数： 回调函数，格式为 (项目集合, 索引) => { ... 返回组件 }。
- 项目集合：当前列表的所有数据数组。
- 索引：当前正在渲染的项目索引。
返回值： 必须返回一个视图组件（继承自 视图 的实例），该组件将被添加到列表项中。