Cascader 级联选择器
新粗野主义风格的级联选择器，支持嵌套选项级联选择、路径绑定（单选/多选）、父子节点关联状态自定义以及完整的键盘操作和无障碍支持。
预览
安装
pnpm dlx brutx-vue@latest add cascader用法
基础用法
<script setup>
import { ref } from 'vue'
import { Cascader } from 'brutx-ui-vue'
const options = [
{
value: 'zh',
label: '中国',
children: [
{
value: 'bj',
label: '北京',
children: [
{ value: 'hd', label: '海淀' },
{ value: 'cy', label: '朝阳' },
]
},
{
value: 'sh',
label: '上海',
}
]
},
{
value: 'us',
label: '美国',
children: [
{ value: 'ny', label: '纽约' },
{ value: 'ca', label: '加州' },
]
}
]
const selected = ref([])
</script>
<template>
<Cascader
v-model="selected"
:options="options"
placeholder="选择地区"
clearable
/>
</template>多选模式
设置 multiple 可以启用多选，此时 v-model 绑定值为二维数组，包含所选的所有完整路径。在非 checkStrictly 状态下，勾选父节点会自动选中其所有子叶子节点。
<script setup>
import { ref } from 'vue'
import { Cascader } from 'brutx-ui-vue'
const selected = ref([]) // 二维数组，如 [['zh', 'bj', 'hd'], ['us', 'ny']]
</script>
<template>
<Cascader
v-model="selected"
:options="options"
multiple
placeholder="选择多个地区"
/>
</template>选择任意一级
默认情况下，只有叶子节点才能被最终选中。设置 checkStrictly 为 true 允许选中任意一级的节点（即父节点也可用作可绑定的值路径）。
<template>
<Cascader
v-model="selected"
:options="options"
check-strictly
placeholder="选择任意级别"
/>
</template>API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
options必填 | CascaderOption<unknown>[] | — | 级联选择的嵌套选项树；每个选项通过 value、label 和可选 children 描述。 |
详情声明类型CascaderOption<unknown>[] 关联类型 CascaderOption 类型定义 — CascaderOptionexport interface CascaderOption<T = unknown> {
value: CascaderValue
label: string
children?: CascaderOption<T>[]
disabled?: boolean
data?: T
}默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
modelValue | CascaderValue[] | CascaderValue[][] | undefined | []按实例调用工厂函数 | 当前选择的路径；单选为单条 CascaderValue 路径，多选为路径数组，通过 v-model 绑定。 |
详情声明类型CascaderValue[] | CascaderValue[][] | undefined 关联类型 CascaderValue 类型定义 — CascaderValueexport type CascaderValue = string | number 默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
open | boolean | undefined | undefined | 下拉面板的受控展开状态；通过 v-model:open 同步。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
multiple | boolean | undefined | false | 允许同时选择多个选项路径；开启后 modelValue 为路径数组。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
clearable | boolean | undefined | false | 显示清除操作以移除已选路径。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
checkStrictly | boolean | undefined | false | 允许独立选择有子项的父节点，而不要求选择到叶子节点。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
separator | string | undefined | " / " | 设置触发器中同一路径各级标签之间显示的分隔符。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
maxDisplay | number | undefined | 2 | 多选时触发器最多直接显示的路径数量；其余路径折叠为汇总。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
size | "default" | "lg" | "sm" | undefined | "default" | 设置触发器按钮的尺寸变体。 |
详情声明类型"default" | "lg" | "sm" | undefined 字面量
默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
placeholder | string | undefined | undefined | 未选择路径时触发器显示的文字。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
disabled | boolean | undefined | false | 禁用选择器及下拉面板的用户交互。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
dropdownClass | string | undefined | undefined | 追加到级联下拉面板的 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
class | string | undefined | undefined | 追加到选择器触发按钮的 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
ariaLabel | string | undefined | undefined | 设置选择器触发器的无障碍标签。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/cascader/Cascader.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@update:modelValue | [value: CascaderValue[] | CascaderValue[][]] | 选择路径变化时发出新的路径值；配合 v-model 更新受控值。 |
详情声明类型[value: CascaderValue[] | CascaderValue[][]] 关联类型 CascaderValue 类型定义 — CascaderValueexport type CascaderValue = string | number 来源packages/ui/src/components/cascader/Cascader.vue | ||
@update:open | [value: boolean] | 下拉面板展开状态变化时发出新布尔值，可用于 v-model:open。 |
详情声明类型[value: boolean] 字面量
来源packages/ui/src/components/cascader/Cascader.vue | ||
@change | [value: CascaderValue[] | CascaderValue[][]] | 用户提交新的单选路径或多选路径集合时发出选择结果。 |
详情声明类型[value: CascaderValue[] | CascaderValue[][]] 关联类型 CascaderValue 类型定义 — CascaderValueexport type CascaderValue = string | number 来源packages/ui/src/components/cascader/Cascader.vue | ||
@open-change | [open: boolean] | 下拉面板打开或关闭时发出当前展开状态。 |
详情声明类型[open: boolean] 字面量
来源packages/ui/src/components/cascader/Cascader.vue | ||
数据类型
type CascaderValue = string | number
interface CascaderOption<T = unknown> {
value: CascaderValue
label: string
children?: CascaderOption<T>[]
disabled?: boolean
data?: T
}CascaderOption 支持泛型注入业务数据类型：CascaderOption<MyData>[] 中 data 字段将获得类型推断；默认 unknown 保持宽松语义。
导出类型
import type { CascaderOption, CascaderValue } from 'brutx-ui-vue'可访问性
- 键盘操作：
ArrowDown/ArrowUp：在当前选项列中上下移动聚焦，自动跳过disabled选项ArrowRight：展开当前选项的子菜单列并聚焦首项ArrowLeft：收起当前级子菜单，并退回到上一选项列Enter/Space：确认选择或在多选下切换 Checkbox 勾选Escape：关闭级联选择器下拉面板
- ARIA 属性：触发器使用
role="combobox"配合aria-expanded与aria-disabled声明状态。下拉列表项设置role="menuitem" - 焦点管理：展开时焦点自动流转至已选路径的最末一级选项；无选中值时不高亮任何项（
aria-activedescendant保持未定义），直到用户开始键盘导航，避免焦点仍在触发器时误报首个选项 - 动效降级：下拉弹窗面板的过渡效果支持
prefers-reduced-motion系统降级，在低动效设备上自动简化动效