组件：城市级联框

城市级联框组件用于实现省/市/区三级联动选择，通过级联下拉列表让用户按层级选择地区。它支持自定义级别（省、省市、省市区）、自定义数据源、设置默认值、禁用状态以及值改变回调。适用于地址填写、区域筛选、用户注册等需要地区选择的场景。

典型使用场景：

  • 用户注册/收货地址填写（省市区三级选择）
  • 商品筛选（按地区筛选）
  • 数据统计（按区域维度筛选）
  • 物流信息（发货/收货地区选择）

📌 继承自视图的成员速查

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

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

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

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

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

常用操作速查

操作属性/方法示例
设置联动级别（1/2/3）级别城市级联框1.级别 = 2
禁用/启用组件禁用城市级联框1.禁用 = 真
设置数据源置数据(级联数据)城市级联框1.置数据([{name:"广东省", children:[...]}])
设置默认选中值置值(地区数组)城市级联框1.置值(["广东省","深圳市","南山区"])
获取当前选中值取值()变量 地区 = 城市级联框1.取值()
清空所有选择清空()城市级联框1.清空()
设置值改变回调置输入被改变回调(回调函数)城市级联框1.置输入被改变回调((源对象, 值) => { ... })

样式美化参考

城市级联框的外观可通过继承的视图属性进行调整：

  • 整体容器：通过 宽度、高度、背景颜色、边框（如 "1px solid #d9d9d9"）、边框圆角（建议 "6px"）等属性美化。
  • 字体样式：通过 字体大小（建议 "14px"）、文本颜色 控制下拉选项文字外观。
  • 内边距：使用 内边距（如 "4px 12px"）控制下拉框内边距。
  • 禁用状态：禁用 = 真 时，级联框变灰且不可交互。
  • 下拉列表样式：下拉列表的样式由组件内部控制，可通过 CSS 类或全局样式覆盖。

数据格式说明

组件的数据格式为嵌套对象数组，结构如下：

[
  {
    name: "省名称",
    children: [
      {
        name: "市名称",
        children: [
          { name: "区名称" },
          { name: "区名称" }
        ]
      }
    ]
  }
]
  • name：必填，显示名称。
  • children：可选，子级数组，结构同父级。

基础示例

创建一个包含省市区三级联动数据，并设置默认选中“广东省/深圳市/南山区”。

变量 城市级联框1 = 创建 城市级联框()
城市级联框1.左边 = 50
城市级联框1.顶边 = 50
城市级联框1.宽度 = 320
城市级联框1.高度 = 36
城市级联框1.字体大小 = "14px"
城市级联框1.边框 = "1px solid #d9d9d9"
城市级联框1.边框圆角 = "6px"
城市级联框1.内边距 = "4px 12px"
城市级联框1.级别 = 3

' 设置数据
城市级联框1.置数据([
    {
        name: "广东省",
        children: [
            {
                name: "深圳市",
                children: [{name: "南山区"}, {name: "福田区"}, {name: "罗湖区"}]
            },
            {
                name: "广州市",
                children: [{name: "天河区"}, {name: "越秀区"}, {name: "海珠区"}]
            }
        ]
    },
    {
        name: "北京市",
        children: [
            {
                name: "北京市",
                children: [{name: "东城区"}, {name: "西城区"}, {name: "朝阳区"}]
            }
        ]
    },
    {
        name: "上海市",
        children: [
            {
                name: "上海市",
                children: [{name: "浦东新区"}, {name: "黄浦区"}, {name: "静安区"}]
            }
        ]
    }
])

' 设置默认选中
城市级联框1.置值(["广东省", "深圳市", "南山区"])

' 设置值改变回调
城市级联框1.置输入被改变回调((源对象, 当前值) => {
    调试输出("已选地区：" + 数组到文本(当前值, " / "))
})

添加组件(城市级联框1)

综合示例：收货地址表单

本示例构建一个完整的收货地址填写表单，包含城市级联框、详细地址输入框、联系人、电话等字段，并演示数据获取与提交。

' ========== 创建表单容器 ==========
变量 表单容器 = 创建 绝对布局()
表单容器.左边 = 30
表单容器.顶边 = 30
表单容器.宽度 = 420
表单容器.背景颜色 = "#ffffff"
表单容器.边框 = "1px solid #e8e8e8"
表单容器.边框圆角 = "12px"
表单容器.内边距 = "24px"
添加组件(表单容器)

' 标题
变量 标题 = 创建 标签()
标题.文本 = "📦 收货地址"
标题.字体大小 = "20px"
标题.字体粗细 = "bold"
标题.文本颜色 = "#333"
标题.内边距 = "0 0 16px 0"
表单容器.添加组件(标题)

' 城市级联框
变量 城市标签 = 创建 标签()
城市标签.文本 = "所在地区"
城市标签.字体大小 = "14px"
城市标签.文本颜色 = "#666"
城市标签.内边距 = "8px 0 4px"
表单容器.添加组件(城市标签)

变量 城市级联框1 = 创建 城市级联框()
城市级联框1.宽度 = 372
城市级联框1.高度 = 36
城市级联框1.字体大小 = "14px"
城市级联框1.边框 = "1px solid #d9d9d9"
城市级联框1.边框圆角 = "6px"
城市级联框1.内边距 = "4px 12px"
城市级联框1.级别 = 3
' 设置数据（复用基础示例的数据）
城市级联框1.置数据([
    {name:"广东省", children:[
        {name:"深圳市", children:[{name:"南山区"},{name:"福田区"}]},
        {name:"广州市", children:[{name:"天河区"},{name:"越秀区"}]}
    ]},
    {name:"北京市", children:[{name:"北京市", children:[{name:"东城区"},{name:"西城区"}]}]},
    {name:"上海市", children:[{name:"上海市", children:[{name:"浦东新区"},{name:"黄浦区"}]}]}
])
表单容器.添加组件(城市级联框1)

' 详细地址
变量 地址标签 = 创建 标签()
地址标签.文本 = "详细地址"
地址标签.字体大小 = "14px"
地址标签.文本颜色 = "#666"
地址标签.内边距 = "12px 0 4px"
表单容器.添加组件(地址标签)

变量 详细地址输入 = 创建 单行输入框()
详细地址输入.宽度 = 372
详细地址输入.高度 = 36
详细地址输入.提示文本 = "请输入街道、门牌号"
详细地址输入.边框 = "1px solid #d9d9d9"
详细地址输入.边框圆角 = "6px"
详细地址输入.内边距 = "4px 12px"
表单容器.添加组件(详细地址输入)

' 联系人
变量 联系人标签 = 创建 标签()
联系人标签.文本 = "联系人"
联系人标签.字体大小 = "14px"
联系人标签.文本颜色 = "#666"
联系人标签.内边距 = "12px 0 4px"
表单容器.添加组件(联系人标签)

变量 联系人输入 = 创建 单行输入框()
联系人输入.宽度 = 372
联系人输入.高度 = 36
联系人输入.提示文本 = "请输入姓名"
联系人输入.边框 = "1px solid #d9d9d9"
联系人输入.边框圆角 = "6px"
联系人输入.内边距 = "4px 12px"
表单容器.添加组件(联系人输入)

' 手机号
变量 电话标签 = 创建 标签()
电话标签.文本 = "手机号"
电话标签.字体大小 = "14px"
电话标签.文本颜色 = "#666"
电话标签.内边距 = "12px 0 4px"
表单容器.添加组件(电话标签)

变量 电话输入 = 创建 单行输入框()
电话输入.宽度 = 372
电话输入.高度 = 36
电话输入.类型 = "tel"
电话输入.提示文本 = "请输入手机号"
电话输入.边框 = "1px solid #d9d9d9"
电话输入.边框圆角 = "6px"
电话输入.内边距 = "4px 12px"
表单容器.添加组件(电话输入)

' 提交按钮
变量 提交按钮 = 创建 按钮()
提交按钮.文本 = "确认地址"
提交按钮.宽度 = 372
提交按钮.高度 = 44
提交按钮.背景颜色 = "#1890ff"
提交按钮.文本颜色 = "#ffffff"
提交按钮.边框圆角 = "6px"
提交按钮.字体大小 = "16px"
提交按钮.内边距 = "16px 0 0"
表单容器.添加组件(提交按钮)

' ========== 事件回调 ==========
' 城市级联框值改变（实时显示）
城市级联框1.置输入被改变回调((源对象, 当前值) => {
    变量 地区文本 = 数组到文本(当前值, " - ")
    调试输出("已选地区：" + 地区文本)
})

' 提交按钮点击
提交按钮.置被单击回调((源对象, 事件对象) => {
    变量 地区 = 城市级联框1.取值()
    变量 详细 = 删首尾空(详细地址输入.内容)
    变量 联系人 = 删首尾空(联系人输入.内容)
    变量 电话 = 删首尾空(电话输入.内容)
    
    ' 校验
    如果(地区 == 空 或 取数组成员数(地区) < 3)
        弹出提示("请选择完整的省市区")
        返回
    结束 如果
    如果(详细 == "")
        弹出提示("请输入详细地址")
        返回
    结束 如果
    如果(联系人 == "")
        弹出提示("请输入联系人")
        返回
    结束 如果
    如果(电话 == "")
        弹出提示("请输入手机号")
        返回
    结束 如果
    
    ' 组装数据
    变量 地址数据 = {
        "province": 地区[0],
        "city": 地区[1],
        "district": 地区[2],
        "detail": 详细,
        "contact": 联系人,
        "phone": 电话
    }
    弹出提示("地址已保存：" + 地区[0] + " " + 地区[1] + " " + 地区[2] + " " + 详细)
    调试输出("提交数据：" + JSON编码(地址数据))
})

属性详解

级别

  • 类型： 数值型
  • 说明： 设置或获取联动级别。1 表示仅省一级，2 表示省市两级，3 表示省市区三级（默认）。级别会影响显示的下拉框数量和数据的层级深度。

禁用

  • 类型： 逻辑型
  • 说明： 设置或获取是否禁用整个组件。禁用后，所有下拉框不可交互，样式变灰。

函数详解

置数据(级联数据)

  • 功能： 设置城市级联数据源。调用后会根据当前 级别 自动渲染对应层级的下拉框。
  • 参数： 级联数据，对象数组，结构为 [{name, children: [...]}]。
  • 返回值： 无。
  • 示例： 
    城市级联框1.置数据([
    {name: "省A", children: [{name: "市A1", children: [{name: "区A1-1"}]}]}
])

置值(地区数组)

  • 功能： 设置默认选中的地区。
  • 参数： 地区数组，字符串数组，如 ["广东省", "深圳市", "南山区"]，长度应与 级别 一致（1~3）。
  • 返回值： 无。若传递的数组层级与数据不匹配，可能无法正确选中。
  • 示例： 城市级联框1.置值(["北京市", "北京市", "东城区"])

取值()

  • 功能： 获取当前选中的地区数组。
  • 返回值： 字符串数组，如 ["广东省", "深圳市", "南山区"]；若未选中任何项，返回空数组 []。
  • 示例： 变量 地区 = 城市级联框1.取值()

清空()

  • 功能： 清空所有下拉框的选中状态，重置为未选择。
  • 返回值： 无。
  • 示例： 城市级联框1.清空()

置输入被改变回调(回调函数)

  • 功能： 设置当任何一级下拉框的值发生变化时的回调函数。
  • 参数： 回调函数，格式为 (源对象, 当前值) => { ... }。
    • 源对象：城市级联框组件本身。
    • 当前值：当前选中的地区数组（字符串数组）。
  • 返回值： 无。
  • 示例： 
    城市级联框1.置输入被改变回调((源对象, 值) => {
    调试输出("当前选择：" + 数组到文本(值, " - "))
})

事件说明

输入被改变(源对象, 当前值)

  • 功能： 与 置输入被改变回调 等效，适用于设计文件（.spldg）中定义的组件。
  • 示例： 
    事件 城市级联框1.输入被改变(源对象, 当前值)
    调试输出("已选：" + 当前值)
结束 事件

⚠️ 注意事项

  1. 数据层级与级别匹配：级别 属性决定了显示几级下拉框，数据源必须包含相应深度的 children。若数据层级不足，可能导致下拉框为空。
  2. 置值 参数格式：地区数组 的长度应与 级别 一致（例如级别=3时需传入3个元素）。元素必须与数据中的 name 完全匹配（包括大小写和符号）。
  3. 数据更新：调用 置数据 会重新渲染下拉框，并清空之前的选中状态。若需保留选中值，应在设置数据后调用 置值。
  4. 禁用状态：禁用 = 真 时，所有下拉框禁用，无法交互。禁用状态下 置值 仍可设置值，但用户无法修改。
  5. 回调触发时机：置输入被改变回调 在用户选择任意一级下拉框时触发，返回当前所有已选级别的数组。若某级未选，该级对应位置为空字符串。
  6. 清空行为：清空() 会重置所有下拉框到未选择状态，并触发 输入被改变 回调（值为空数组）。
  7. 样式继承：组件本身是一个容器，内部包含多个下拉框，样式通过继承的属性作用于整体容器，内部下拉框样式由组件统一管理。
  8. 数据格式严格：数据源必须包含 name 字段，children 可选，但必须为数组。若 children 为空数组或不提供，则表示该节点为叶子节点。

相关文档

  • 文档框架基础类_视图 —— 视图类提供的所有通用属性和方法
  • 文档列表类组件_组合框 —— 基础下拉选择组件
  • 文档文本类组件_单行输入框 —— 配合表单输入
  • 文档轻语言网站：轻语言语法速查 —— 拉姆达表达式、数组操作等
  • 文档综合演示：收货地址表单 —— 实际应用示例