Cascader 级联选择
uni-appH5微信小程序App
uni-app 跨端级联选择器。点击触发器弹出底部面板,页签(各级路径 + 请选择)+ 单层列表逐级下钻,点叶子选中整条路径;触发器以 / 连接显示路径。multiple 开启多选:选项显示复选框级联勾选,触发器以标签展示选中叶子,支持 collapseTags 折叠。
何时使用
从层级数据中选取一条路径:省市区、多级分类、组织层级;移动端/小程序/App 三端通用。
何时不使用
需要同时看到并勾选多个层级节点时,用 Tree。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | Array<string | number> | Array<Array<string | number>> | [] | 选中路径(单选)或选中路径数组(multiple 多选),配合 v-model 使用 |
options | Array<CascaderOption> | [] | 嵌套选项,项为 { label: string; value: string | number; children?: 同构; disabled?: boolean } |
placeholder | string | "请选择" | 未选中时的占位文本 |
emptyText | string | "暂无数据" | 面板当前层级无选项时的空数据文案 |
disabled | boolean | false | 禁用 |
clearable | boolean | false | 可清空;移动端无 hover,有值时触发器常显清空按钮 |
multiple | boolean | false | 多选模式:选项显示复选框,勾选父级级联勾选全部可选子孙(部分选中时父级半选);点复选框勾选且面板不关闭,点选项文本下钻子级;modelValue 为路径数组 |
collapseTags | boolean | false | 多选时折叠标签:只显示首个标签与 +N 计数 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | Array<string | number> | Array<Array<string | number>> | 选中叶子/勾选变化/清空时触发,用于 v-model |
change | Array<string | number> | Array<Array<string | number>> | 值变化时触发(选中叶子、勾选变化或清空) |
clear | void | 点击清空按钮时触发 |
示例
单选地址
vue
<Cascader v-model="s" :options="areaOptions" placeholder="选择所在地区" />可清空
vue
<Cascader v-model="s2" :options="areaOptions" placeholder="选择所在地区" clearable />禁用
vue
<Cascader v-model="s3" :options="areaOptions" disabled placeholder="不可选择" />