级联选择 Cascader
最常见的级联选择场景。默认按叶子节点提交值，也支持通过 expand-trigger="hover" 调整子级展开方式。
严格选择模式
Section titled “严格选择模式”开启 check-strictly 后，父节点也可以直接选中；多选时会同时解除父子联动。
通过 allow-clear 显示清除按钮，兼容 clearable 别名。
在节点上设置 disabled 后，该项不会参与选择和回填。
设置 expand-child 后，进入一个分支时会自动展开它的第一个子菜单。
当回填值在当前选项树中不存在时，可以通过 fallback 控制展示文本，或关闭回退展示。
自定义字段名
Section titled “自定义字段名”通过 field-names 映射不同的数据结构。
自定义展示值
Section titled “自定义展示值”使用 format-label 统一格式化已选路径的展示内容。
路径展示与响应式标签
Section titled “路径展示与响应式标签”通过 show-path 和 separator 控制回填文案；多选时可用 max-tag-count="responsive" 让标签在窄宽度下自动折叠，和 Select / TreeSelect 复用同一套标签压缩逻辑。
子选项懒加载
Section titled “子选项懒加载”传入 load-more 后，未标记 isLeaf: true 且没有 children 的节点会走懒加载分支。
选择框和下拉面板都可以显示加载态。
设置 multiple 后使用复选框交互，并复用当前组件库的标签回填逻辑。
CascaderPanel 可以单独作为路径面板使用，适合详情页或组合式表单布局。
开启 path-mode 后，值会以完整路径数组的形式回传。
设置 allow-search 启用搜索，兼容 filterable 别名；搜索面板默认展示整条路径，也可通过 search-option-only-label 只展示末级标签。
当前示例会在大体量子选项列里对比默认固定模式和显式 itemSize 写法，更适合验证级联面板在真实大数据量下的滚动表现。对于典型的多列菜单，默认固定高度通常就是最稳的配置。
通过 virtual-list-props 在大数据量场景下减少渲染开销。Cascader 当前菜单项默认按固定高度处理：如果你没有显式传 itemSize 或 minItemSize，组件会按 36px 菜单项高度补齐固定模式；如果要手动指定固定高度，请传 itemSize；只有显式传 minItemSize 时，才会切到动态高度模式。完整参数与迁移映射见 虚拟列表迁移指南。
从 Naive UI 迁移
Section titled “从 Naive UI 迁移”这次迁移以当前组件库内部的 Trigger、SelectView、表单联动、主题和弹层容器链路为基础实现，同时保留一层有限的 Naive 兼容别名，方便旧业务先完成替换，再逐步收敛到本地 API。
| Naive UI | SD Design Vue | 说明 |
|---|---|---|
n-cascader | sd-cascader | 级联选择器主体 |
n-cascader-panel | sd-cascader-panel | 面板组件 |
:options | :options | 选项主属性保持一致 |
v-model:value | v-model / v-model:value | 当前同时支持 model-value 和 value 兼容别名 |
show / default-show | popup-visible / default-popup-visible，同时兼容 show / default-show | 新代码建议回到本地命名 |
filterable | allow-search / filterable | 新代码建议使用 allow-search |
clearable | allow-clear / clearable | 新代码建议使用 allow-clear |
show-path | show-path | 控制已选标签是否展示完整路径 |
separator | separator | 路径展示分隔符 |
max-tag-count="responsive" | max-tag-count="responsive" | 多选标签会按当前容器宽度自动折叠 |
render-label | format-label / #label / #option | 路径展示与选项展示改为本地格式化函数和插槽 |
render-prefix / render-suffix | #prefix、#arrow-icon、#loading-icon、#search-icon | 对外渲染入口统一收敛到插槽 |
fallback-option 风格回填 | fallback | 不存在的值仍可回显，但回调签名以当前组件库为准 |
- 运行时行为以当前组件库为准，尤其是弹层定位、表单
onChange/onBlur联动、局部主题和容器挂载，已经统一接入本地Trigger/ConfigProvider/ThemeProvider。 - 公开定制能力只保留插槽和少量格式化函数，不再对外保留 render function API。历史上依赖
render-label、render-prefix、render-suffix的场景，建议分别迁到format-label、label、option、prefix、arrow-icon、loading-icon、search-icon等公开插槽或属性。 - 当前版本保留
value、show、default-show、filterable、clearable等兼容别名，但新增代码更建议直接使用model-value、popup-visible、default-popup-visible、allow-search、allow-clear。 - 搜索面板、标签回填、路径格式化和多选勾选链路都复用了当前组件库内部实现。
max-tag-count="responsive"、show-path、separator现在已和 Select / TreeSelect 保持一致。 check-strategy这一类会改变多选值语义的 Naive 行为当前仍未对齐；如果旧代码依赖它，需要保留为迁移差异单独评估。
建议的迁移顺序
Section titled “建议的迁移顺序”- 先替换组件标签：把
n-cascader/n-cascader-panel替换成sd-cascader/sd-cascader-panel，原来的options、value、show、filterable、clearable可以先靠兼容层跑通。 - 再统一命名：逐步把
value、show、default-show、filterable、clearable迁到model-value、popup-visible、default-popup-visible、allow-search、allow-clear。 - 然后处理自定义内容：删除 render function 写法，改用
label、option、prefix等模板插槽，保持公开扩展方式一致。 - 最后回归复杂交互：重点检查搜索、懒加载、多选、严格选择、路径回填、虚拟列表和
fallback场景。
下面的示例把兼容别名写法和推荐写法放在一起，方便逐步替换而不是一次性重写。
<cascader> Props
Section titled “<cascader> Props”| 参数名 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| path-mode | 绑定值是否为路径 | boolean | false | |
| multiple | 是否为多选状态 | boolean | false | |
| model-value (v-model) | 绑定值 | CascaderModelValue | - | |
| value (v-model:value) | model-value 的兼容别名 | CascaderModelValue | - | |
| default-value | 默认值（非受控状态） | CascaderModelValue | '' | undefined | [] | |
| options | 级联选择器的选项 | CascaderOption[] | [] | |
| disabled | 是否禁用 | boolean | false | |
| error | 是否为错误状态 | boolean | false | |
| size | 选择框的大小 | 'mini' | 'small' | 'medium' | 'large' | 'medium' | |
| allow-search | 是否允许搜索，兼容 filterable 别名 | boolean | false (single) | true (multiple) | |
| filterable | allow-search 的兼容别名 | boolean | - | |
| allow-clear | 是否允许清除，兼容 clearable 别名 | boolean | false | |
| clearable | allow-clear 的兼容别名 | boolean | - | |
| input-value (v-model) | 输入框的值 | string | - | |
| default-input-value | 输入框默认值 | string | '' | |
| popup-visible (v-model) | 是否显示下拉框 | boolean | - | |
| show (v-model:show) | popup-visible 的兼容别名 | boolean | - | |
| default-popup-visible | 默认是否显示下拉框 | boolean | false | |
| default-show | default-popup-visible 的兼容别名 | boolean | - | |
| expand-trigger | 展开下一级的触发方式 | 'click' | 'hover' | 'click' | |
| placeholder | 占位符 | string | - | |
| filter-option | 自定义选项过滤方法 | (inputValue: string, option: CascaderOption) => boolean | - | |
| popup-container | 弹出框挂载容器 | string | HTMLElement | - | |
| max-tag-count | 多选模式最多显示的标签数量，0 表示不限制，responsive 表示按容器宽度自动折叠 | number | 'responsive' | 0 | |
| show-path | 回填时是否展示完整路径 | boolean | true | |
| separator | 回填路径使用的分隔符 | string | ' / ' | |
| format-label | 自定义已选路径的展示内容 | (options: CascaderOption[]) => string | - | |
| trigger-props | 下拉菜单触发器属性 | TriggerProps | - | |
| check-strictly | 是否开启严格选择模式 | boolean | false | |
| load-more | 数据懒加载函数 | (option: CascaderOption, done: (children?: CascaderOption[]) => void) => void | - | 2.13.0 |
| loading | 是否为加载中状态 | boolean | false | 2.15.0 |
| search-option-only-label | 搜索面板是否只展示末级标签 | boolean | false | 2.18.0 |
| search-delay | 触发搜索事件的延迟时间 | number | 500 | 2.18.0 |
| field-names | 自定义字段映射 | CascaderFieldNames | - | 2.22.0 |
| value-key | 对象值用于确定 key 的字段 | string | 'value' | 2.29.0 |
| fallback | 自定义不存在选项值的展示 | boolean | ((value: CascaderOptionValue | CascaderOptionValue[]) => string) | true | 2.29.0 |
| expand-child | 是否展开子菜单 | boolean | false | 2.29.0 |
| virtual-list-props | 虚拟列表配置。完整参数与迁移说明见 虚拟列表迁移指南 | VirtualListProps | - | 2.49.0 |
| tag-nowrap | 标签内容不换行 | boolean | false | 2.56.1 |
<cascader> Events
Section titled “<cascader> Events”| 事件名 | 描述 | 参数 |
|---|---|---|
| update:modelValue | v-model 更新事件 | value: CascaderModelValue |
| update:value | value 兼容别名的更新事件 | value: CascaderModelValue |
| change | 选中值改变时触发 | value: CascaderModelValue |
| input-value-change | 输入值改变时触发 | value: string |
| clear | 点击清除按钮时触发 | - |
| search | 用户搜索时触发 | value: string |
| update:popup-visible | 弹层显隐更新事件 | visible: boolean |
| popup-visible-change | 弹层显隐变化时触发 | visible: boolean |
| update:show | show 兼容别名的更新事件 | visible: boolean |
| showChange | show 兼容别名的变化事件 | visible: boolean |
| focus | 获得焦点时触发 | ev: FocusEvent |
| blur | 失去焦点时触发 | ev: FocusEvent |
<cascader> Slots
Section titled “<cascader> Slots”| 插槽名 | 描述 | 参数 | 版本 |
|---|---|---|---|
| label | 选择框的显示内容 | data: CascaderOption | 2.18.0 |
| option | 自定义选项内容 | data: CascaderOption | 2.18.0 |
| prefix | 前缀元素 | - | 2.23.0 |
| arrow-icon | 选择框箭头图标 | - | 2.16.0 |
| loading-icon | 选择框加载图标 | - | 2.16.0 |
| search-icon | 选择框搜索图标 | - | 2.16.0 |
| empty | 选项为空时的显示内容 | - | 2.23.0 |
<cascader-panel> Props
Section titled “<cascader-panel> Props”| 参数名 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| path-mode | 绑定值是否为路径 | boolean | false | |
| multiple | 是否为多选状态 | boolean | false | |
| model-value (v-model) | 绑定值 | CascaderModelValue | - | |
| value (v-model:value) | model-value 的兼容别名 | CascaderModelValue | - | |
| default-value | 默认值（非受控状态） | CascaderModelValue | '' | undefined | [] | |
| options | 级联选择器的选项 | CascaderOption[] | [] | |
| expand-trigger | 展开下一级的触发方式 | 'click' | 'hover' | 'click' | |
| check-strictly | 是否开启严格选择模式 | boolean | false | |
| load-more | 数据懒加载函数 | (option: CascaderOption, done: (children?: CascaderOption[]) => void) => void | - | 2.13.0 |
| field-names | 自定义字段映射 | CascaderFieldNames | - | 2.22.0 |
| value-key | 对象值用于确定 key 的字段 | string | 'value' | 2.29.0 |
| expand-child | 是否展开子菜单 | boolean | false | 2.29.0 |
<cascader-panel> Events
Section titled “<cascader-panel> Events”| 事件名 | 描述 | 参数 |
|---|---|---|
| update:modelValue | v-model 更新事件 | value: CascaderModelValue |
| update:value | value 兼容别名的更新事件 | value: CascaderModelValue |
| change | 选中值改变时触发 | value: CascaderModelValue |
<cascader-panel> Slots
Section titled “<cascader-panel> Slots”| 插槽名 | 描述 | 参数 | 版本 |
|---|---|---|---|
| empty | 选项为空时的显示内容 | - | 2.23.0 |
CascaderOption
Section titled “CascaderOption”| 参数名 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| value | 选项值，支持对象值 | string | number | Record<string, unknown> | - | |
| label | 选项文本 | string | - | |
| disabled | 是否禁用 | boolean | false | |
| tagProps | 多选标签透传属性 | TagProps | - | 2.8.0 |
| children | 下一级选项 | CascaderOption[] | - | |
| isLeaf | 是否为叶子节点 | boolean | false |