组件：组合框

组合框组件用于提供下拉选择功能，允许用户从预定义的选项列表中选择一个值。它基于 HTML <select> 元素封装，支持添加/清空选项、设置选中项以及值变化回调。常用于表单中的选项选择、数据筛选、分类切换等场景。

典型使用场景：

表单中的下拉选择（性别、城市、职业等）
数据筛选与查询（按分类、状态、时间筛选）
设置选项（语言选择、主题选择）
分类导航（产品分类、文章栏目）

📌 继承自视图的成员速查

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

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

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

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

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

常用操作速查

操作	属性/方法	示例
添加选项	`添加项目(文本, 值)`	`组合框1.添加项目("北京", "BJ")`
清空所有选项	`清空()`	`组合框1.清空()`
渲染选项到界面	`渲染()`	`组合框1.渲染()`
设置选择变化回调	`置项目被选择回调(回调函数)`	`组合框1.置项目被选择回调((源对象, 事件, 值, 文本) => { ... })`
获取当前选中值	通过 `取属性值("value")`	`变量值 = 组合框1.取属性值("value")`
获取当前选中文本	通过 `文本` 属性	`变量文本 = 组合框1.文本`
禁用/启用组合框	`禁用`	`组合框1.禁用 = 真`
设置默认选中项	通过 `置属性值("value", 值)`	`组合框1.置属性值("value", "SH")`

样式美化参考

组合框的样式主要通过继承的视图属性和 CSS 类进行美化：

整体容器：通过 宽度、高度、背景颜色、边框（建议 "1px solid #d9d9d9"）、边框圆角（建议 "6px"）等属性调整外观。
字体样式：通过 字体大小（建议 "14px"）、文本颜色 控制选项文字外观。
内边距：使用 内边距（如 "4px 12px"）控制下拉框内边距。
禁用状态：禁用 = 真 时，组合框变灰且不可交互。
下拉箭头：默认浏览器样式，可通过 CSS 自定义（需了解 <select> 伪元素）。

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

.my-combobox {
    padding: 6px 12px;
    border: 1px solid #d9d9d9;
    border-radius: 6px;
    font-size: 14px;
    background-color: #ffffff;
    appearance: auto;  /* 保留原生下拉箭头 */
    cursor: pointer;
}
.my-combobox:focus {
    border-color: #1890ff;
    outline: none;
    box-shadow: 0 0 0 2px rgba(24, 144, 255, 0.2);
}
.my-combobox:disabled {
    background-color: #f5f5f5;
    cursor: not-allowed;
}

在代码中应用样式类：组合框1.添加样式类("my-combobox")

基础示例

创建一个简单的城市选择组合框，包含三个选项，选中时弹出提示。

变量 组合框1 = 创建 组合框()
组合框1.左边 = 50
组合框1.顶边 = 50
组合框1.宽度 = 200
组合框1.高度 = 36
组合框1.字体大小 = "14px"
组合框1.边框 = "1px solid #d9d9d9"
组合框1.边框圆角 = "6px"
组合框1.内边距 = "4px 12px"

' 添加选项
组合框1.添加项目("北京", "BJ")
组合框1.添加项目("上海", "SH")
组合框1.添加项目("深圳", "SZ")
组合框1.添加项目("广州", "GZ")

' 渲染到界面
组合框1.渲染()

' 设置选择回调
组合框1.置项目被选择回调((源对象, 事件对象, 选中值, 选中文本) => {
    弹出提示("选择了：" + 选中文本 + "（值：" + 选中值 + "）")
})

添加组件(组合框1)

综合示例：商品筛选面板

本示例构建一个商品筛选面板，包含城市、品类、排序三个组合框，联动筛选并更新商品列表。

' ========== 创建筛选面板 ==========
变量 筛选面板 = 创建 弹性布局()
筛选面板.方向 = "row"
筛选面板.左边 = 20
筛选面板.顶边 = 20
筛选面板.宽度 = 500
筛选面板.间距 = 16
筛选面板.侧轴对齐 = "center"
添加组件(筛选面板)

' ========== 城市选择 ==========
变量 标签_城市 = 创建 标签()
标签_城市.文本 = "城市："
标签_城市.字体大小 = "14px"
筛选面板.添加组件(标签_城市)

变量 组合框_城市 = 创建 组合框()
组合框_城市.宽度 = 120
组合框_城市.高度 = 32
组合框_城市.边框 = "1px solid #d9d9d9"
组合框_城市.边框圆角 = "4px"
组合框_城市.添加项目("全部", "all")
组合框_城市.添加项目("北京", "BJ")
组合框_城市.添加项目("上海", "SH")
组合框_城市.添加项目("深圳", "SZ")
组合框_城市.渲染()
筛选面板.添加组件(组合框_城市)

' ========== 品类选择 ==========
变量 标签_品类 = 创建 标签()
标签_品类.文本 = "品类："
标签_品类.字体大小 = "14px"
筛选面板.添加组件(标签_品类)

变量 组合框_品类 = 创建 组合框()
组合框_品类.宽度 = 120
组合框_品类.高度 = 32
组合框_品类.边框 = "1px solid #d9d9d9"
组合框_品类.边框圆角 = "4px"
组合框_品类.添加项目("全部", "all")
组合框_品类.添加项目("电子产品", "elec")
组合框_品类.添加项目("家居用品", "home")
组合框_品类.添加项目("图书文具", "book")
组合框_品类.渲染()
筛选面板.添加组件(组合框_品类)

' ========== 排序选择 ==========
变量 标签_排序 = 创建 标签()
标签_排序.文本 = "排序："
标签_排序.字体大小 = "14px"
筛选面板.添加组件(标签_排序)

变量 组合框_排序 = 创建 组合框()
组合框_排序.宽度 = 120
组合框_排序.高度 = 32
组合框_排序.边框 = "1px solid #d9d9d9"
组合框_排序.边框圆角 = "4px"
组合框_排序.添加项目("默认", "default")
组合框_排序.添加项目("价格从低到高", "price_asc")
组合框_排序.添加项目("价格从高到低", "price_desc")
组合框_排序.添加项目("销量优先", "sales")
组合框_排序.渲染()
筛选面板.添加组件(组合框_排序)

' ========== 商品列表显示 ==========
变量 商品列表标签 = 创建 标签()
商品列表标签.左边 = 20
商品列表标签.顶边 = 80
商品列表标签.宽度 = 500
商品列表标签.文本 = "商品列表将根据筛选条件更新"
商品列表标签.字体大小 = "14px"
商品列表标签.背景颜色 = "#f5f5f5"
商品列表标签.边框圆角 = "6px"
商品列表标签.内边距 = "16px"
添加组件(商品列表标签)

' ========== 模拟商品数据 ==========
变量 模拟商品 = [
    {名称: "手机", 城市: "BJ", 品类: "elec", 价格: 2999},
    {名称: "电脑", 城市: "SH", 品类: "elec", 价格: 5999},
    {名称: "沙发", 城市: "SZ", 品类: "home", 价格: 3999},
    {名称: "小说", 城市: "BJ", 品类: "book", 价格: 39},
    {名称: "电视", 城市: "GZ", 品类: "elec", 价格: 4999},
    {名称: "床垫", 城市: "SH", 品类: "home", 价格: 2999},
    {名称: "杂志", 城市: "SZ", 品类: "book", 价格: 25}
]

' ========== 筛选函数 ==========
函数 筛选商品()
    变量 城市 = 组合框_城市.取属性值("value")
    变量 品类 = 组合框_品类.取属性值("value")
    变量 排序 = 组合框_排序.取属性值("value")
    
    ' 筛选
    变量 结果 = []
    变量循环(i = 0, 取数组成员数(模拟商品), 1)
        变量 商品 = 模拟商品[i]
        变量 匹配城市 = (城市 == "all" 或 商品.城市 == 城市)
        变量 匹配品类 = (品类 == "all" 或 商品.品类 == 品类)
        如果(匹配城市 且 匹配品类)
            添加成员(结果, 商品)
        结束 如果
    结束循环
    
    ' 排序（简化为按价格）
    如果(排序 == "price_asc")
        数组排序(结果, 真)  ' 正序
    否则 如果(排序 == "price_desc")
        数组排序(结果, 假)  ' 倒序
    结束 如果
    
    ' 更新显示
    变量 显示文本 = "找到 " + 取数组成员数(结果) + " 件商品：\n"
    变量循环(i = 0, 取数组成员数(结果), 1)
        变量 商品 = 结果[i]
        显示文本 = 显示文本 + "• " + 商品.名称 + "（¥" + 商品.价格 + "）\n"
    结束循环
    商品列表标签.文本 = 显示文本
结束 函数

' ========== 绑定筛选事件 ==========
组合框_城市.置项目被选择回调((源对象, 事件对象, 选中值, 选中文本) => {
    筛选商品()
})

组合框_品类.置项目被选择回调((源对象, 事件对象, 选中值, 选中文本) => {
    筛选商品()
})

组合框_排序.置项目被选择回调((源对象, 事件对象, 选中值, 选中文本) => {
    筛选商品()
})

' 初始化筛选
筛选商品()

属性详解

组合框除了继承自 视图 的通用属性外，本身没有定义额外的专属属性。但以下继承属性在组合框中尤为常用：

属性	类型	说明
`宽度`	数值型	设置下拉框宽度，建议根据选项长度合理设置
`高度`	数值型	设置下拉框高度，通常为 `32px` ~ `40px`
`字体大小`	文本型	设置选项文字大小，建议 `"14px"`
`边框`	文本型	设置边框样式，如 `"1px solid #d9d9d9"`
`边框圆角`	文本型	设置边框圆角，建议 `"4px"` 或 `"6px"`
`禁用`	逻辑型	设为 `真` 时禁用下拉框
`文本`	文本型	获取当前选中的选项显示文本（只读）

函数详解

添加项目(文本, 值)

功能： 向组合框的数据集合中添加一个选项。
参数：
- 文本：文本型，必填，显示在下拉列表中的文字。
- 值：文本型，可选，选项对应的值，用于程序识别。若不传，默认与 文本 相同。
返回值： 无。
示例： 组合框1.添加项目("北京", "BJ")

清空()

功能： 清空组合框中所有选项，并清除选中状态。
返回值： 无。
示例： 组合框1.清空()

渲染()

功能： 将数据集合中的选项渲染到界面上（生成 <option> 元素）。在添加项目后必须调用此方法，否则选项不会出现在下拉列表中。
返回值： 无。
示例： 组合框1.渲染()

置项目被选择回调(回调函数)

功能： 设置当用户选择（改变）选项时的回调函数。
参数： 回调函数，拉姆达表达式，格式为 (源对象, 事件对象, 选中值, 选中文本) => { ... }。
- 源对象：触发的组合框组件本身。
- 事件对象：原生事件对象。
- 选中值：当前选中项的 值。
- 选中文本：当前选中项的显示文本。
返回值： 无。

示例：

组合框1.置项目被选择回调((源对象, 事件, 值, 文本) => {
    调试输出("选中值：" + 值 + "，选中文本：" + 文本)
})

事件说明

项目被选择(源对象, 事件对象, 选中值, 选中项文本)

功能： 与 置项目被选择回调 等效，适用于设计文件（.spldg）中定义的组件。