Cascader
按层级逐步完成选择。中文惯用名：级联选择。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.cascader |
| 名称 | Cascader |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 按层级逐步完成选择 |
| 描述 | 中文惯用名：级联选择。 |
预览
静态结构：Cascader 为 input 风格触发器（data-slot="cascader-trigger"，文本以 ` / ` 连接路径各级 label，缺省「请选择」）+ 受控 Popover 弹层（data-slot="cascader-panel"）：多列并排（每列 data-slot="cascader-column"，宽 40、独立滚动），点击含 children 的节点开下一列（行尾 ChevronRight 指示），点击叶子提交并关闭弹层；列内当前路径节点高亮。打开弹层时以已提交路径初始化下钻位置。Form 内声明 name 时外层包 FieldShell（label + 校验错误）。
DSL 结构
{
"type": "Cascader",
"props": {
"name": "region",
"placeholder": "请选择省市区",
"options": [
{
"label": "浙江省",
"value": "zj",
"children": [
{
"label": "杭州市",
"value": "hangzhou",
"children": [
{
"label": "西湖区",
"value": "xihu"
},
{
"label": "滨江区",
"value": "binjiang"
}
]
}
]
}
]
}
}何时用
何时使用
- 按层级逐步完成选择且路径本身有语义：省 / 市 / 区、类目 / 子类目。
- 各级选项数量中等、需要逐列下钻浏览；只有叶子节点完成选择。
何时不用
- 需要选中中间层级（父节点即合法值）：使用 TreeSelect（单值）。
- 扁平候选：使用 Select；层级数据但候选巨大需搜索：TreeSelect + searchable 更合适（Cascader 无搜索）。
- 多选路径：当前实现为单选路径。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 基础级联 | 多列逐级下钻，叶子完成选择 | 省市区、类目等固定层级数据 |
| 路径回显 | 触发器文本以「 / 」连接各级 label | 编辑场景回显已存路径 value 数组 |
| placeholder 空态 | 未选时触发器显示弱提示（缺省「请选择」） | 非必填层级字段 |
| disabled 禁用 | 触发器半透明不可点开 | 联动未就绪或只读场景 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（FieldShell 呈现） |
rules | FieldRule[] | — | 校验规则 |
options | CascaderOption[] | [] | 嵌套选项（{ label, value, children? }；含 children 的节点点开下一列，叶子完成选择） |
value | `Array<string | number>` | — |
placeholder | string | '请选择' | 空态提示文案 |
disabled | boolean | false | 禁用触发器 |
onChange | `(value: Array<string | number>) => void` | — |
className | string | — | 根节点 class（Form 内为 form-item 容器，独立渲染时为触发器） |
style | CSSProperties | — | 根节点内联样式（同 className 的挂载规则） |
使用规范
- 值是完整路径 value 数组（如 ["zhejiang", "hangzhou", "xihu"]），不是叶子单值；落库与回显保持数组形态。
- 与 TreeSelect 的边界：Cascader 只有叶子完成选择、保留路径；TreeSelect 任意节点可选、只存单值。
- 路径中任一 value 在 options 中未命中则回显为空；options 变更后注意存量值的有效性。
- 层级不宜过深（2-4 级最佳）：每级一列，过深横向展开体验差。
- Cascader 无搜索能力；候选巨大需搜索定位时改用 TreeSelect + searchable。
正例
- ✓ 省市区选择：三级 options，选中叶子传出完整路径数组，触发器回显「浙江 / 杭州 / 西湖」。
- ✓ 商品类目：两级类目下钻，Form 内 name + 必填 rules，未选到叶子不提交。
- ✓ 编辑回显：value 传入已存路径数组，打开弹层自动定位到对应列。
反例
- ✕ 需要选中间层级（如只选到省）却用 Cascader（叶子才完成选择，应使用 TreeSelect）。
- ✕ 把路径数组 join 成字符串存储后拆不回原值类型（string / number 混淆导致回显失效）。
- ✕ 六级以上深层级仍用 Cascader 逐列下钻，用户迷失在多列中。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。