0.0.4

Cascader 级联选择器 ​

当选项具有清晰的层级结构时，可使用级联选择器进行查看与选择。

基础用法 ​

展开子级选项有两种触发方式。

将 options 绑定为选项数组即可渲染级联选择器。props.expandTrigger 用于定义子级如何展开。

Child options expand when clicked (default)

Child options expand when hovered

禁用选项 ​

在选项对象中设置 disabled 字段即可禁用该项。

本例 options 首项包含 disabled: true，因此禁用。默认读取每项的 disabled 字段；若使用其他字段表示禁用，可在 props.disabled 中映射（详见下方 API）。value、label、children 字段名同样支持自定义。

可清空 ​

为 el-cascader 设置 clearable 后，选中并悬停时会显示清空图标。

自定义清空图标 ​

通过 clear-icon 自定义清空图标。

仅显示最后一级 ​

输入框可只展示最后一级，而非完整路径。

show-all-levels 控制是否展示所有层级；为 false 时仅展示最后一级。

多选 ​

在标签上使用 :props="props"，并在脚本中 const props = { multiple: true }。

推荐写法：

vue
<template>
  <u-cascader :props="props" />
</template>

<script lang="ts" setup>
const props = { multiple: true }
</script>

不推荐：

vue
<template>
  <!-- 级联选择器此处使用对象字面量绑定无效 -->
  <u-cascader :props="{ multiple: true }" />
</template>

多选时默认展示全部标签；collapse-tags 为 true 可折叠；max-collapse-tags 控制最多展示数量，默认 1。collapse-tags-tooltip 可在悬停折叠文案时查看全部选中项。

Display all tags (default)

Collapse tags

Collapse tags tooltip

Max Collapse Tags

选择任意一级 ​

单选时默认只能选叶子节点；多选时勾选父级会联动子级。开启本能力后父子选中状态可解耦，从而选择任意一级。

设置 props.checkStrictly = true，节点选中状态不再影响父子，即可选择任意层级。

Select any level of options (Single selection)

Select any level of options (Multiple selection)

动态加载 ​

点击节点时动态加载子级。

设置 lazy = true 启用动态加载，并通过 lazyLoad 定义如何加载数据。lazyLoad 第一个参数为当前节点 node，第二个 resolve 为加载完成回调（必须调用）。为准确展示节点状态，可增加 leaf 字段（或通过 props.leaf 映射）表示是否为叶子节点；否则将根据是否存在子节点推断。

可搜索 ​

通过关键字搜索并选择选项。

为 el-cascader 增加 filterable 开启过滤。默认会匹配标签或其父级标签（取决于 show-all-levels）是否包含关键字。也可通过 filter-method 自定义：第一个参数为 node，第二个为 keyword，返回布尔值表示是否命中。

Filterable (Single selection)

Filterable (Multiple selection)

自定义节点内容 ​

可自定义级联节点展示内容。

使用作用域插槽自定义节点；作用域提供 node（节点对象）与 data（节点数据）。

自定义搜索项 ​

通过 suggestion-item 插槽自定义过滤建议项；作用域提供 item。

级联面板 ​

CascaderPanel 是 Cascader 的核心子组件，支持单选、多选、动态加载等能力。

与 el-cascader 类似，通过 options 设置数据，通过 props 启用特性，详见下方 API。

自定义标签 ​

可自定义已选项标签。

在 el-cascader 的插槽中插入自定义标签时，collapse-tags、collapse-tags-tooltip、max-collapse-tags 将不生效。

Using slots allows for more flexible control over the display.

Display top-level tags only

展示策略 ​

控制多选模式下已选项的展示方式。

多选下使用 show-checked-strategy 控制展示：默认 child 展示所有选中子节点；parent 在子节点全部选中时仅展示父节点。

Strategy: child (default, show all selected child nodes)

Strategy: parent (show only parent nodes when all children are selected)

点击节点选中 ​

需配合 multiple 或 checkStrictly。

可设置 checkOnClickNode，在点击节点（除前缀图标外）时切换选中。使用 showPrefix 控制前缀显隐。

添加 checkOnClickLeaf 可仅在点击叶子（最后一级）时切换选中，默认开启。

show prefix

checkStrictly | Single mode

Multiple mode

自定义头部与底部 ​

可通过插槽自定义下拉面板的头部与底部。

使用插槽自定义内容。

Custom header content

Custom footer content

级联选择器 API ​

级联选择器 属性 ​

名称说明类型默认值
model-value / v-model绑定值string / number /array—
options选项数据；value、label 等键名可通过 CascaderProps 映射array—
props配置项，见下方 CascaderProps 表object—
size输入框尺寸enum—
placeholder占位符string—
disabled是否禁用boolean—
clearable是否可清空boolean—
clear-icon自定义清空图标string / objectCircleClose
show-all-levels输入框是否展示选中值的完整层级booleantrue
collapse-tags多选时是否折叠标签boolean—
collapse-tags-tooltip悬停折叠文案时是否展示全部标签；需开启 collapse-tagsbooleanfalse
max-collapse-tags-tooltip-height折叠标签提示的最大高度string / number—
separator选项分隔符string' / '
filterable是否可搜索boolean—
filter-method自定义搜索逻辑；参数为 node、keyword，返回是否命中Function—
debounce搜索输入防抖（毫秒）number300
before-filter过滤前钩子，参数为待过滤字符串；返回 false 或 Promise 被拒绝则中止过滤Function—
popper-class下拉与标签提示的自定义类名string''
popper-style下拉与标签提示的自定义样式string / object—
teleported是否将弹出层传送至 bodybooleantrue
effect标签提示主题，内置 dark / lightenum / stringlight
tag-type标签类型enuminfo
tag-effect标签效果enumlight
validate-event是否触发表单校验booleantrue
max-collapse-tags最多展示标签数；需开启 collapse-tagsnumber1
empty-values空值配置，见 config-providerarray—
value-on-clear清空时的返回值，见 config-providerstring / number / boolean / Function—
persistent下拉失活且 persistent 为 false 时是否销毁下拉booleantrue
fallback-placementsTooltip 可能位置列表 popper.jsarray—
placement下拉位置enumbottom-start
show-checked-strategy多选下已选节点展示策略；需要层级更整洁用 parent，需要逐项展示用 childenumchild

级联选择器 事件 ​

事件名说明类型
change绑定值变化时Function
expand-change展开节点变化时Function
blur失焦时Function
focus聚焦时Function
clear可清空时点击清空图标Function
visible-change下拉出现/隐藏时Function
remove-tag多选移除标签时Function

级联选择器 插槽 ​

名称说明
default自定义节点内容；作用域为 node、data；作用域类型 ^[object]`
empty无匹配选项时的内容
prefix输入框前缀内容
suggestion-item搜索时自定义建议项；作用域类型 ^[object]`
tag自定义标签；作用域类型 ^[object]`
header下拉面板顶部内容
footer下拉面板底部内容

级联选择器 暴露 ​

名称说明类型
getCheckedNodes获取当前选中节点数组；leafOnly 为 true 时仅返回叶子选中节点，默认 falseFunction
cascaderPanelRef面板组件引用object
togglePopperVisible切换下拉显隐Function
contentRef内容区域引用object
presentText当前展示文本object
focus聚焦输入框Function
blur失焦输入框Function

级联面板 API ​

级联面板 属性 ​

名称说明类型默认值
model-value / v-model绑定值string/number/array—
options选项数据；键名可通过 CascaderProps 映射array—
props配置项，见 CascaderPropsobject—

级联面板 事件 ​

事件名说明类型
change绑定值变化时Function
update:modelValue绑定值变化时Function
expand-change展开节点变化时Function
close关闭面板事件，供级联选择器判断是否收起面板Function

级联面板 插槽 ​

名称说明
default自定义节点内容；作用域为 node、data；作用域类型 ^[object]`
empty无数据时面板内容

级联面板 暴露 ​

名称说明类型
getCheckedNodes获取当前选中节点数组；leafOnly 为 true 时仅返回叶子选中节点，默认 falseFunction
clearCheckedNodes清空已选节点Function

级联选择器配置项（CascaderProps） ​

名称说明类型默认值
expandTrigger子级展开触发方式enumclick
multiple是否多选booleanfalse
checkStrictly选中状态是否不关联父子booleanfalse
emitPath选中变化时是否返回节点路径数组；为 false 时仅返回节点值booleantrue
lazy是否动态加载子节点，需配合 lazyLoadbooleanfalse
lazyLoad动态加载子节点数据；仅 lazy 为 true 时生效；支持 reject 参数Function—
value节点对象中作为取值的键名stringvalue
label节点对象中作为标签的键名stringlabel
children节点对象中作为子级的键名stringchildren
disabled节点对象中表示禁用的键名stringdisabled
leaf节点对象中表示叶子节点的键名stringleaf
hoverThreshold悬停展开的阈值（毫秒）number500
checkOnClickNode点击节点时是否切换选中booleanfalse
checkOnClickLeaf是否仅在点击叶子节点时切换选中booleantrue
showPrefix是否显示单选/多选前缀图标booleantrue

类型声明 ​

展开类型声明
ts
type CascaderNodeValue = string | number
type CascaderNodePathValue = CascaderNodeValue[]
type CascaderValue =
  | CascaderNodeValue
  | CascaderNodePathValue
  | (CascaderNodeValue | CascaderNodePathValue)[]

type Resolve = (data: any) => void

type ExpandTrigger = 'click' | 'hover'

type LazyLoad = (node: Node, resolve: Resolve, reject: () => void) => void

type isDisabled = (data: CascaderOption, node: Node) => boolean

type isLeaf = (data: CascaderOption, node: Node) => boolean

interface CascaderOption extends Record<string, unknown> {
  label?: string
  value?: CascaderNodeValue
  children?: CascaderOption[]
  disabled?: boolean
  leaf?: boolean
}

interface CascaderProps {
  expandTrigger?: ExpandTrigger
  multiple?: boolean
  checkStrictly?: boolean
  emitPath?: boolean
  lazy?: boolean
  lazyLoad?: LazyLoad
  value?: string
  label?: string
  children?: string
  disabled?: string | isDisabled
  leaf?: string | isLeaf
  hoverThreshold?: number
}

class Node {
  readonly uid: number
  readonly level: number
  readonly value: CascaderNodeValue
  readonly label: string
  readonly pathNodes: Node[]
  readonly pathValues: CascaderNodePathValue
  readonly pathLabels: string[]

  childrenData: ChildrenData
  children: Node[]
  text: string
  loaded: boolean
  /**
   * 是否选中
   *
   * @default false
   */
  checked: boolean
  /**
   * 表示未全选子节点与全选子节点之间的中间态
   *
   * @default false
   */
  indeterminate: boolean
  /**
   * 加载状态
   *
   * @default false
   */
  loading: boolean

  // 访问器
  isDisabled: boolean
  isLeaf: boolean
  valueByOption: CascaderNodeValue | CascaderNodePathValue

  // 方法
  appendChild(childData: CascaderOption): Node
  calcText(allLevels: boolean, separator: string): string
  broadcast(): void
  emit(): void
  onParentCheck(checked: boolean): void
  onChildCheck(): void
  setCheckState(checked: boolean): void
  doCheck(checked: boolean): void
}

Node as CascaderNode