Cascader 级联选择

用于逐级选择地区、分类等有层级关系的选项。

基础选择

children 定义子选项。点击父项展开下一列，点击末级选项确认完整路径；disabled 可以禁用一个分支。

交互预览两级分类

basic.tsx

import { Cascader } from '@sudden3/leaf-ui';

const options = [
  {
    value: 'design',
    label: '设计',
    children: [
      { value: 'interface', label: '界面设计' },
      { value: 'brand', label: '品牌设计' },
    ],
  },
  {
    value: 'engineering',
    label: '工程',
    children: [
      { value: 'frontend', label: '前端开发' },
      { value: 'backend', label: '后端开发' },
    ],
  },
  { value: 'archived', label: '归档分类', disabled: true },
];

export function CascaderBasic() {
  return (
    <div className="leaf-demo-stack">
      <Cascader aria-label="项目分类" options={options} placeholder="选择项目分类" />
      <Cascader aria-label="默认分类" options={options} defaultValue={['design', 'interface']} />
      <Cascader aria-label="禁用分类" options={options} disabled />
    </div>
  );
}

受控路径

value 是从根节点到末级节点的 value 数组，onChange 同时提供完整的选项对象路径。切换父项后会清除旧分支的后续选择。

交互预览三级地区

选中路径：zhejiang → hangzhou → xihu

controlled.tsx

import { Cascader } from '@sudden3/leaf-ui';
import { useState } from 'react';
import { regions } from './options';

export function CascaderControlled() {
  const [value, setValue] = useState<string[]>(['zhejiang', 'hangzhou', 'xihu']);
  return (
    <div className="leaf-demo-stack">
      <Cascader aria-label="收货地区" options={regions} value={value} onChange={setValue} />
      <span className="leaf-demo-note">选中路径：{value.join(' → ') || '未选择'}</span>
    </div>
  );
}

示例使用的地区选项：

options.ts

import type { CascaderOption } from '@sudden3/leaf-ui';

export const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖区' },
          { value: 'yuhang', label: '余杭区' },
        ],
      },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙区' }] },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京', children: [{ value: 'gulou', label: '鼓楼区' }] },
      { value: 'suzhou', label: '苏州', children: [{ value: 'gusu', label: '姑苏区' }] },
    ],
  },
  { value: 'archived', label: '归档地区', disabled: true },
];

Cascader API

属性	类型	默认值	说明
`options`	`readonly CascaderOption[]`	必填	层级选项列表
`value` / `defaultValue`	`readonly string[]`	`[]`	受控路径 / 非受控初始路径
`onChange`	`(value: string[], selectedOptions: CascaderOption[]) => void`	—	末级选择完成或清除时触发
`allowClear`	`boolean`	`true`	清除后返回两个空数组
`placeholder`	`string`	`'请选择'`	未选择时的提示文字
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	选择器尺寸
`status`	`'error' \| 'warning'`	—	校验状态
`disabled`	`boolean`	`false`	禁用整个控件
`name` / `form`	`string`	—	字段名 / 关联的表单 ID
`required`	`boolean`	`false`	要求选择一项
`onOpenChange`	`(open: boolean) => void`	—	面板展开或收起
`ref`	`Ref<HTMLButtonElement>`	—	触发按钮引用

同一层内的 value 应唯一，传入路径应完整且存在于 options 中。其余原生 button 属性和 aria-* 透传至触发按钮；className / style 作用于外层容器。

类型

CascaderProps 用于定义组件属性。单独组装层级选项时，可以使用 CascaderOption：

import type { CascaderProps, CascaderOption, ControlSize, ControlStatus } from '@sudden3/leaf-ui';

const options: CascaderOption[] = [
  {
    label: '浙江',
    value: 'zhejiang',
    children: [{ label: '杭州', value: 'hangzhou' }],
  },
];

CascaderOption

属性	类型	默认值	说明
`value`	`string`	必填	选项值，同一层内应唯一
`label`	`string`	必填	选项文字
`disabled`	`boolean`	`false`	禁用该选项及其子级
`children`	`readonly CascaderOption[]`	—	子选项；没有子选项时可确认选择

表单与键盘

设置 name 后，FormData 的值为 JSON 数组字符串，例如 ["zhejiang","hangzhou","xihu"]，清除后为空字符串。可用 JSON.parse 读取路径。非受控组件支持表单 reset，受控组件需同步重置自己的状态。

Enter、空格或 ↓ 打开面板，↑ / ↓ 在列内移动，Home / End 移至首尾，→ 展开子级，← 返回上一级，Enter 选择。Tab 在各列之间移动，离开面板时聚焦表单中的后续控件；Escape 收起并聚焦触发按钮。关闭时未确认的路径不会提交。

面板沿用局部主题，较深层级可以横向滚动查看。为控件提供 label 或 aria-label。

#Cascader 级联选择

#基础选择

#受控路径

#Cascader API

#类型

#CascaderOption