组件：文本列表框

文本列表框组件用于显示纯文本列表项，每个列表项仅展示一行文本，支持单击事件回调。它是一个轻量级的列表组件，适用于不需要复杂自定义渲染的场景，如菜单列表、选项列表、数据展示等。

典型使用场景：

导航菜单（侧边栏菜单、顶部导航选项）
设置选项列表（系统设置、个人偏好）
简单数据展示（新闻标题列表、公告列表）
历史记录或日志列表

📌 继承自视图的成员速查

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

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

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

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

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

常用操作速查

操作	属性/方法	示例
设置是否拉伸内容（隐藏滚动条）	`拉伸内容`	`文本列表框1.拉伸内容 = 真`
添加单个项目	`添加项目(标题, 标记)`	`文本列表框1.添加项目("选项一", 1)`
删除指定项目	`删除项目(索引)`	`文本列表框1.删除项目(2)`
更新指定项目	`更新项目(索引, 项目对象)`	`文本列表框1.更新项目(1, {标题:"新名称", 标记:2})`
获取所有项目	`取项目集合()`	`变量全部 = 文本列表框1.取项目集合()`
获取项目数量	`取项目数()`	`变量数量 = 文本列表框1.取项目数()`
清空所有项目	`清空()`	`文本列表框1.清空()`
触发渲染	`渲染()`	`文本列表框1.渲染()`
设置项目点击回调	`置项目被单击回调(回调函数)`	`文本列表框1.置项目被单击回调((源对象, 索引) => { ... })`

样式美化参考

文本列表框的样式主要通过继承的视图属性以及 CSS 类进行美化：

整体容器：设置 宽度、高度、背景颜色、边框、边框圆角 等。建议边框圆角设置 "8px" 以得圆润效果。
文本样式：通过 字体大小（建议 "14px"）、文本颜色、字体粗细 调整列表项的文字外观。
内边距：使用 内边距 控制列表项与边框的距离，使内容不贴边。
列表项样式：每个列表项默认显示为一行文本，可自定义悬停、选中状态的样式（通过 CSS 类）。
拉伸内容：当 拉伸内容 = 真 时，列表高度自动适应所有项目，不出现滚动条；为 假（默认）时，超出高度会显示滚动条。

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

.my-text-list .list-item {
    padding: 10px 16px;
    border-bottom: 1px solid #f0f0f0;
    cursor: pointer;
    transition: background-color 0.2s;
}
.my-text-list .list-item:hover {
    background-color: #f5f5f5;
}
.my-text-list .list-item:active {
    background-color: #e6f7ff;
}

在代码中应用样式类：文本列表框1.添加样式类("my-text-list")

基础示例

创建一个简单的文本列表，包含三个选项，点击时弹出提示。

变量 文本列表框1 = 创建 文本列表框()
文本列表框1.左边 = 50
文本列表框1.顶边 = 50
文本列表框1.宽度 = 200
文本列表框1.高度 = 150
文本列表框1.字体大小 = "14px"
文本列表框1.文本颜色 = "#333"
文本列表框1.边框 = "1px solid #d9d9d9"
文本列表框1.边框圆角 = "6px"
文本列表框1.内边距 = "0px"

' 添加项目
文本列表框1.添加项目("首页", "home")
文本列表框1.添加项目("产品", "product")
文本列表框1.添加项目("关于", "about")

' 设置单击回调
文本列表框1.置项目被单击回调((源对象, 索引) => {
    变量 项目 = 源对象.取项目集合()[索引]
    弹出提示("您点击了：" + 项目.标题)
})

' 渲染并添加到父容器
文本列表框1.渲染()
添加组件(文本列表框1)

综合示例：动态菜单列表

本示例展示一个动态菜单，支持添加、删除菜单项，并实时响应点击事件。

' ========== 创建文本列表框 ==========
变量 菜单列表 = 创建 文本列表框()
菜单列表.左边 = 30
菜单列表.顶边 = 30
菜单列表.宽度 = 240
菜单列表.高度 = 300
菜单列表.背景颜色 = "#ffffff"
菜单列表.边框 = "1px solid #e8e8e8"
菜单列表.边框圆角 = "8px"
菜单列表.字体大小 = "14px"
菜单列表.文本颜色 = "#333"
菜单列表.内边距 = "4px"
添加组件(菜单列表)

' ========== 准备初始数据 ==========
变量 初始菜单 = [
    {标题: "控制台", 标记: "dashboard"},
    {标题: "用户管理", 标记: "users"},
    {标题: "系统设置", 标记: "settings"}
]
变量循环(i = 0, 取数组成员数(初始菜单), 1)
    变量 项 = 初始菜单[i]
    菜单列表.添加项目(项.标题, 项.标记)
结束循环
菜单列表.渲染()

' ========== 点击回调 ==========
菜单列表.置项目被单击回调((源对象, 索引) => {
    变量 项目集合 = 源对象.取项目集合()
    变量 选中项 = 项目集合[索引]
    弹出提示("选择菜单：" + 选中项.标题)
})

' ========== 底部操作面板 ==========
变量 操作面板 = 创建 弹性布局()
操作面板.方向 = "row"
操作面板.左边 = 30
操作面板.顶边 = 350
操作面板.宽度 = 240
操作面板.间距 = 8
添加组件(操作面板)

' 输入新菜单名称
变量 输入_新菜单 = 创建 单行输入框()
输入_新菜单.宽度 = "flex-grow"
输入_新菜单.提示文本 = "新菜单名"
操作面板.添加组件(输入_新菜单)

' 添加按钮
变量 按钮_添加 = 创建 按钮()
按钮_添加.文本 = "添加"
按钮_添加.宽度 = 60
按钮_添加.高度 = 32
按钮_添加.背景颜色 = "#1890ff"
按钮_添加.文本颜色 = "#ffffff"
按钮_添加.边框圆角 = "4px"
操作面板.添加组件(按钮_添加)

' 删除按钮（删除最后一项）
变量 按钮_删除最后 = 创建 按钮()
按钮_删除最后.文本 = "删除最后"
按钮_删除最后.宽度 = 80
按钮_删除最后.高度 = 32
按钮_删除最后.背景颜色 = "#ff4d4f"
按钮_删除最后.文本颜色 = "#ffffff"
按钮_删除最后.边框圆角 = "4px"
操作面板.添加组件(按钮_删除最后)

' ========== 事件绑定 ==========
按钮_添加.置被单击回调((源对象, 事件对象) => {
    变量 新名 = 删首尾空(输入_新菜单.内容)
    如果(新名 == "")
        弹出提示("请输入菜单名称")
        返回
    结束 如果
    菜单列表.添加项目(新名, "menu_" + 取现行时间戳())
    菜单列表.渲染()
    输入_新菜单.内容 = ""
    输入_新菜单.获取焦点()
    弹出提示("已添加：" + 新名)
})

按钮_删除最后.置被单击回调((源对象, 事件对象) => {
    变量 数量 = 菜单列表.取项目数()
    如果(数量 > 0)
        菜单列表.删除项目(数量 - 1)
        菜单列表.渲染()
        弹出提示("已删除最后一项")
    否则
        弹出提示("列表已空")
    结束 如果
})

属性详解

拉伸内容

类型： 逻辑型
说明： 设置是否拉伸列表内容以填满容器高度。当为 真 时，列表高度自适应所有项目，不显示滚动条；当为 假（默认）时，超出容器高度会出现滚动条。

函数详解

添加项目(标题, 标记)

功能： 向列表末尾添加一个项目。
参数：
- 标题：文本型，必填，显示在列表项中的文本。
- 标记：任意类型，可选，用于标识该项目，可在回调中区分不同项目。
返回值： 无。
示例： 文本列表框1.添加项目("新选项", "opt_new")

删除项目(索引)

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

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

功能： 替换指定索引的项目为新数据。
参数： 索引（数值型），项目对象 须包含 标题 和 标记 字段（结构同添加项目参数）。
返回值： 无。
示例： 文本列表框1.更新项目(0, {标题: "新标题", 标记: "new_tag"})

取项目集合()

功能： 获取所有项目的数组。
返回值： 数组，每个元素为 {标题: "xxx", 标记: xxx} 格式的对象。
示例： 变量全部 = 文本列表框1.取项目集合()

取项目数()

功能： 获取当前项目数量。
返回值： 数值型。

清空()

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

渲染()

功能： 根据当前数据集合重新生成列表项 DOM。在添加、删除、更新数据后，需要调用该方法刷新界面。
返回值： 无。

置项目被单击回调(回调函数)

功能： 设置项目被单击时的回调函数。
参数： 回调函数，拉姆达表达式，格式为 (源对象, 索引) => { ... }。
- 源对象：触发事件的文本列表框组件本身。
- 索引：被单击项目的索引（从 0 开始）。

示例：

文本列表框1.置项目被单击回调((源对象, 索引) => {
    变量 项目 = 源对象.取项目集合()[索引]
    调试输出("单击：" + 项目.标题 + "，标记：" + 项目.标记)
})

事件：项目被单击(源对象,索引)

功能： 与 置项目被单击回调 等效，适用于设计文件（.spldg）中定义的组件，采用 VB6 风格绑定。