V1.0.0
WinDesign A2UI Vue

WCascader 组件 ​

级联选择器组件，基于 WinDesignNext Cascader 封装，用于在多级数据中进行选择（如省市区、科室层级等），支持数据绑定和事件响应。

默认返回完整路径：props.emitPath 默认为 true，modelValue 绑定值为选中路径数组（如 ["zhejiang", "hangzhou", "xihu"]）。若只需末级 value，设置 props: { "emitPath": false }。

基础用法 ​

Props API ​

属性名类型默认值说明
idstring-组件唯一标识（必填）
componentstringWCascader组件类型（必填）
modelValueobject-绑定值（A2UI 数据绑定，支持 path）
optionsarray[]静态选项列表，与 dataSource 二选一
dataSourcestring-数据源路径，从 dataModel 动态加载选项
propsobject-级联面板配置（支持 path），见下方说明
separatorstring/object/各级选中项之间的分隔符（支持 path）
sizestringdefault输入框尺寸
disabledbooleanfalse是否禁用
clearablebooleanfalse是否可清空
filterablebooleanfalse是否可搜索
placeholderstring-占位文本
showAllLevelsbooleantrue输入框是否显示完整路径
collapseTagsbooleanfalse多选时是否折叠标签
maxCollapseTagsnumber1折叠标签最大显示数量
collapseTagsTooltipbooleanfalse折叠标签是否显示 tooltip
debouncenumber300搜索防抖延迟（毫秒）
placementstringbottom-start下拉弹出位置
teleportedbooleantrue下拉层是否挂载到 body
popperClassstring-下拉层自定义 CSS 类名
effectstringlightTooltip 主题
tagTypestringinfo多选标签类型
tagEffectstringlight多选标签主题
validateEventbooleantrue是否触发表单验证
persistentbooleantrue面板关闭后是否保留 DOM
checkAllbooleanfalse多选时是否显示全选
showCheckedStrategystringparent多选标签显示策略
checkOnClickNodebooleanfalse点击节点是否选中
showPrefixbooleantrue多选时是否显示前缀图标
actionobject-A2UI v0.9 事件定义

path 支持说明 ​

通用绑定格式见 path 数据绑定速查。

属性支持 path说明
modelValue✅双向绑定选中值（路径数组或末级 value）
props✅动态控制面板行为（multiple、emitPath 等）
separator✅动态控制显示分隔符
dataSource✅字符串路径，从 dataModel 加载选项树
action.event.context[].value✅事件上下文可引用 dataModel
action.event.api.constParams[].value✅API 固定参数可引用 dataModel
options / placeholder / filterable 等❌静态配置；选项动态加载请用 dataSource

options 选项配置 ​

options 为树形数组，每项包含：

json
{
  "value": "zhejiang",
  "label": "浙江",
  "children": [
    {
      "value": "hangzhou",
      "label": "杭州",
      "children": [
        { "value": "xihu", "label": "西湖区" }
      ]
    }
  ]
}
字段类型必填说明
valuestring/number/object是当前节点唯一标识
labelstring是显示文本
childrenarray否子级选项数组
disabledboolean否是否禁用该节点
leafboolean否是否为叶子节点（懒加载场景）

props 面板配置 ​

对应 WinDesignNext Cascader 的 props 属性，控制级联面板行为：

json
{
  "props": {
    "expandTrigger": "click",
    "multiple": false,
    "checkStrictly": false,
    "emitPath": true,
    "value": "value",
    "label": "label",
    "children": "children"
  }
}
字段类型默认值说明
expandTriggerclick/hoverclick次级菜单展开方式
multiplebooleanfalse是否多选
checkStrictlybooleanfalse是否可选择任意一级（父子不关联）
emitPathbooleantrue绑定值是否返回完整路径数组
valuestringvalueoptions 中 value 字段名
labelstringlabeloptions 中 label 字段名
childrenstringchildrenoptions 中 children 字段名
checkOnClickNodebooleanfalse点击节点是否选中（多选）
checkOnClickLeafbooleantrue点击叶子节点是否选中

props path 绑定示例：

json
{
  "props": { "path": "/cascaderPanelProps" },
  "modelValue": { "path": "/region" }
}

通过 updateDataModel 动态切换多选模式：

json
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/cascaderPanelProps",
    "value": { "multiple": true, "emitPath": true, "checkStrictly": true }
  }
}

modelValue 数据绑定 ​

modelValue 将选中值绑定到 dataModel，选中结果写回对应 path。

json
// 默认 emitPath: true，绑定值为路径数组
{ "modelValue": { "path": "/region" } }

// emitPath: false，绑定值为末级 value
{
  "props": { "emitPath": false },
  "modelValue": { "path": "/districtCode" }
}

// 多选，绑定值为路径数组的数组
{
  "props": { "multiple": true },
  "modelValue": { "path": "/selectedRegions" }
}

modelValue 绑定规则：

  • 默认 emitPath: true 时，绑定值为 字符串/数字数组（完整路径）
  • emitPath: false 时，绑定值为 末级节点的 value
  • 多选时，绑定值为 数组的数组（每个选中项一条路径）
  • 可通过 literalArray 设置初始值：{ "literalArray": ["zhejiang", "hangzhou", "xihu"] }

dataSource 动态选项 ​

与 WSelect 类似，通过 dataSource 从 dataModel 加载选项树：

json
{
  "id": "cascader_dept",
  "component": "WCascader",
  "dataSource": "/deptOptions",
  "placeholder": "请选择科室",
  "clearable": true,
  "modelValue": { "path": "/selectedDeptPath" },
  "action": {
    "event": {
      "name": "onDeptChange",
      "context": [{ "key": "deptPath", "value": { "path": "/selectedDeptPath" } }]
    }
  }
}

配合 updateDataModel 初始化数据和选项：

json
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/",
    "value": {
      "selectedDeptPath": ["hospital", "internal", "cardiology"],
      "deptOptions": [
        {
          "value": "hospital",
          "label": "总院",
          "children": [
            {
              "value": "internal",
              "label": "内科",
              "children": [
                { "value": "cardiology", "label": "心内科" }
              ]
            }
          ]
        }
      ]
    }
  }
}

action 定义 ​

选中项变化时触发 change 事件（可通过 action.event.type 覆盖）：

json
{
  "action": {
    "event": {
      "name": "onRegionChange",
      "type": "change",
      "context": [
        { "key": "region", "value": { "path": "/region" } }
      ]
    }
  }
}

数据同步机制 ​

WCascader 在用户确认选择后会自动将值同步到 dataModel，流程与 WInput、WSelect 一致：

  1. Agent 发送 updateComponents 定义组件，modelValue.path 指向 dataModel 路径
  2. Agent 发送 updateDataModel 初始化选项和选中值
  3. 用户选择后，渲染器自动调用 setData 更新 dataModel
  4. 若配置了 action，同时触发 A2UI 事件

使用场景 ​

场景推荐配置
省市区选择静态 options + modelValue.path
科室/组织层级dataSource 动态加载 + modelValue.path
多选标签props: { "multiple": true }
任意级可选props: { "checkStrictly": true }
仅存储末级 codeprops: { "emitPath": false }
可搜索filterable: true

注意事项 ​

  • A2UI JSON 不支持函数类型属性，lazyLoad、filterMethod、beforeFilter 等回调无法在 JSON 中配置
  • props 在 A2UI 协议中表示级联面板配置，与 Vue 组件 props 概念相同但独立于 modelValue
  • 选项字段名默认 value/label/children，若后端数据结构不同，通过 props 配置字段映射

Design by UED