#Cascader 级联选择
逐级选择地区、分类等有层级关系的选项。
#基础用法
children 定义子选项。展开父项后选择末级选项,确认完整路径;disabled 禁用整个分支。
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [
{
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 (
<Form layout="vertical">
<FormField label="项目分类">
<Cascader options={options} placeholder="选择项目分类" />
</FormField>
</Form>
);
}
#示例
#受控路径
value 是从根节点到选中节点的值数组,onChange 同时返回完整的选项对象路径。清除时,两者都为空数组。展开父项只改变待选路径;返回已提交路径所属的一级分支时,会恢复下级选择。
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
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 },
];
export function CascaderControlled() {
const [value, setValue] = useState<string[]>(['zhejiang', 'hangzhou', 'xihu']);
return (
<Form layout="vertical">
<FormField label="收货地区">
<Cascader options={regions} value={value} onChange={setValue} />
</FormField>
<Text role="status" tone="muted">
选中路径:{JSON.stringify(value)}
</Text>
</Form>
);
}
#搜索
showSearch 按完整路径展示匹配结果。搜索只覆盖已提供或已加载的选项,不会自动请求远程数据。
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: '浙江',
children: [
{ value: 'hangzhou', label: '杭州' },
{ value: 'ningbo', label: '宁波' },
],
},
{
value: 'jiangsu',
label: '江苏',
children: [
{ value: 'nanjing', label: '南京' },
{ value: 'suzhou', label: '苏州' },
],
},
];
export function CascaderSearch() {
return (
<Form layout="vertical">
<FormField label="地区">
<Cascader options={regions} placeholder="选择地区" showSearch />
</FormField>
</Form>
);
}
#多选
multiple 模式的 value 为 string[][],每项是一条完整路径。再次选择同一路径会取消选择,选择后浮层保持打开。
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: '浙江',
children: [
{ value: 'hangzhou', label: '杭州' },
{ value: 'ningbo', label: '宁波' },
],
},
{
value: 'jiangsu',
label: '江苏',
children: [
{ value: 'nanjing', label: '南京' },
{ value: 'suzhou', label: '苏州' },
],
},
];
export function CascaderMultiple() {
const [value, setValue] = useState<string[][]>([
['zhejiang', 'hangzhou'],
['jiangsu', 'nanjing'],
]);
return (
<Form layout="vertical">
<FormField label="地区">
<Cascader multiple options={regions} value={value} onChange={setValue} />
</FormField>
<Text role="status" tone="muted">
选中路径数:{value.length}
</Text>
</Form>
);
}
#单行多选
tagWrap={false} 将标签保留在一行,超出空间的选项折叠为 +N;也可通过 maxTagCount 限制可见标签数。打开浮层可查看和修改全部选择。
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [
{
value: 'product',
label: '产品团队',
children: [
{ value: 'design', label: '产品体验设计' },
{ value: 'web', label: '前端开发' },
{ value: 'mobile', label: '移动端开发' },
],
},
];
export function CascaderSingleLine() {
return (
<Form layout="vertical">
<FormField label="产品团队">
<Cascader
multiple
tagWrap={false}
options={options}
defaultValue={[
['product', 'design'],
['product', 'web'],
['product', 'mobile'],
]}
/>
</FormField>
</Form>
);
}
#禁用与只读
disabled 禁止交互;readOnly 保留触发控件的聚焦能力,但不允许打开浮层、清除或修改值。
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [
{
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 },
];
const value = ['design', 'interface'];
export function CascaderStates() {
return (
<Form layout="vertical">
<FormField label="禁用">
<Cascader options={options} value={value} disabled />
</FormField>
<FormField label="只读">
<Cascader options={options} value={value} readOnly />
</FormField>
</Form>
);
}
#选择中间层
changeOnSelect 允许提交中间层级的路径。选择仍有子项的节点时,浮层保持打开,可以继续向下选择。
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: '浙江',
children: [
{ value: 'hangzhou', label: '杭州' },
{ value: 'ningbo', label: '宁波' },
],
},
{
value: 'jiangsu',
label: '江苏',
children: [
{ value: 'nanjing', label: '南京' },
{ value: 'suzhou', label: '苏州' },
],
},
];
export function CascaderIntermediate() {
const [value, setValue] = useState<string[]>([]);
return (
<Form layout="vertical">
<FormField label="地区">
<Cascader changeOnSelect options={regions} value={value} onChange={setValue} />
</FormField>
<Text role="status" tone="muted">
选中路径:{JSON.stringify(value)}
</Text>
</Form>
);
}
#异步加载
为尚无 children 的节点设置 isLeaf={false},展开时由 loadData 返回子选项。保持 options 和 loadData 的引用稳定,节点值在整棵树中唯一。
请求应响应 AbortSignal:更换选项、加载函数、cacheKey 或卸载时会取消旧请求,关闭浮层不会取消。通过 onLoadError 提供失败反馈,再次展开节点可重试。
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [{ value: 'remote', label: '远程分类', isLeaf: false }];
function waitForChildren(signal: AbortSignal) {
return new Promise<void>((resolve, reject) => {
if (signal.aborted) {
reject(new DOMException('Aborted', 'AbortError'));
return;
}
const onAbort = () => {
clearTimeout(timer);
reject(new DOMException('Aborted', 'AbortError'));
};
const timer = setTimeout(() => {
signal.removeEventListener('abort', onAbort);
resolve();
}, 400);
signal.addEventListener('abort', onAbort, { once: true });
});
}
async function loadData(option: CascaderOption, signal: AbortSignal): Promise<CascaderOption[]> {
await waitForChildren(signal);
return [{ value: `${option.value}-child`, label: '已加载项', isLeaf: true }];
}
export function CascaderLazy() {
return (
<Form layout="vertical">
<FormField label="远程分类">
<Cascader options={options} loadData={loadData} placeholder="展开分类" />
</FormField>
</Form>
);
}
#刷新缓存
数据版本变化时更新 cacheKey,清空已加载的子选项并取消旧请求。此例保持选项和加载函数不变;刷新后重新展开分类,加载新版本。
import { Button, Cascader, type CascaderOption, Flex, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useCallback, useRef, useState } from 'react';
const options: CascaderOption[] = [{ value: 'remote', label: '远程分类', isLeaf: false }];
function waitForChildren(signal: AbortSignal) {
return new Promise<void>((resolve, reject) => {
if (signal.aborted) {
reject(new DOMException('Aborted', 'AbortError'));
return;
}
const onAbort = () => {
clearTimeout(timer);
reject(new DOMException('Aborted', 'AbortError'));
};
const timer = setTimeout(() => {
signal.removeEventListener('abort', onAbort);
resolve();
}, 400);
signal.addEventListener('abort', onAbort, { once: true });
});
}
export function CascaderCache() {
const [version, setVersion] = useState(1);
const [loadedVersion, setLoadedVersion] = useState<number | null>(null);
const versionRef = useRef(1);
const loadData = useCallback(async (option: CascaderOption, signal: AbortSignal) => {
const requestVersion = versionRef.current;
await waitForChildren(signal);
setLoadedVersion(requestVersion);
return [{ value: `${option.value}-child`, label: `已加载项 v${requestVersion}`, isLeaf: true }];
}, []);
return (
<Form layout="vertical">
<FormField label="远程分类">
<Cascader options={options} loadData={loadData} cacheKey={version} placeholder="展开分类" />
</FormField>
<Flex align="start">
<Button
onClick={() => {
versionRef.current += 1;
setVersion(versionRef.current);
setLoadedVersion(null);
}}
>
刷新数据
</Button>
</Flex>
<Text role="status" tone="muted">
缓存版本:v{version}; 加载版本:{loadedVersion === null ? '未加载' : `v${loadedVersion}`}
</Text>
</Form>
);
}
#浮层宽度
popupWidth="auto" 按内容定宽,popupMaxWidth 限制最大宽度;省略时默认与触发控件等宽。其他浮层配置见共享浮层参数。
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: '浙江',
children: [
{ value: 'hangzhou', label: '杭州' },
{ value: 'ningbo', label: '宁波' },
],
},
{
value: 'jiangsu',
label: '江苏',
children: [
{ value: 'nanjing', label: '南京' },
{ value: 'suzhou', label: '苏州' },
],
},
];
export function CascaderPopup() {
return (
<Form layout="vertical">
<FormField label="地区">
<Cascader options={regions} placeholder="选择地区" popupWidth="auto" popupMaxWidth={320} />
</FormField>
</Form>
);
}
设置 name 后,以 JSON 数组字符串提交路径,空值提交为空字符串。非受控值支持表单重置,受控值需同步重置应用状态;标签和错误信息见 Form。内置文案配置见 ConfigProvider。
#API
#Cascader API
其余原生 button 属性和 aria-* 透传至触发按钮;className / style 作用于外层容器。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
options | readonly CascaderOption[] | 必填 | 层级选项列表 |
value | readonly string[] | readonly (readonly string[])[] | — | 受控路径;省略时使用内部非受控值。 |
defaultValue | readonly string[] | readonly (readonly string[])[] | [] | 非受控模式的初始路径;支持表单重置。 |
onChange | ((value: string[], selectedOptions: CascaderOption[]) => void) | ((value: string[][], selectedOptions: CascaderOption[][]) => void) | — | 单选返回路径和对应选项,多选返回路径数组和对应选项数组;选择、取消或清除时触发,清除的两参数均为空数组。 |
multiple | false | true | false | 启用多选;value 和回调的类型随之变化。 |
placeholder | string | '请选择' | 未选择时的提示文字 |
size | 'sm' | 'md' | 'lg' | 'md' | 选择器尺寸 |
status | 'error' | 'warning' | — | 校验状态 |
disabled | boolean | false | 禁用交互。 |
readOnly | boolean | — | 锁定业务值,禁止输入、选择、清除和删除。 |
allowClear | boolean | true | 清除后返回两个空数组 |
showSearch | boolean | — | 启用搜索输入。 |
changeOnSelect | boolean | — | 允许选择中间层级。 |
tagWrap | boolean | true | 允许多选标签换行;false 单行显示并自动折叠溢出项。 |
maxTagCount | number | 'responsive' | — | 最多展示的标签数;responsive 根据可用宽度自动折叠。 |
displayRender | (labels: ReactNode[], selectedOptions: CascaderOption[]) => ReactNode | — | 自定义每条已选路径的显示内容,参数为该路径的标签和选项。 |
optionRender | (option: CascaderOption) => ReactNode | — | 自定义选项内容。 |
loadData | (option: CascaderOption, signal: AbortSignal) => Promise<readonly CascaderOption[]> | — | 展开 isLeaf 为 false 且未提供 children 的节点时请求子项;使用 signal 处理取消。 |
onLoadError | (error: unknown, option: CascaderOption) => void | — | 加载失败时调用,可展示重试提示。 |
cacheKey | string | number | — | 数据版本改变时清空懒加载缓存,并取消旧请求。 |
open | boolean | — | 受控的展开状态。 |
defaultOpen | boolean | false | 非受控模式的初始展开状态。 |
onOpenChange | (open: boolean) => void | — | 面板展开或收起 |
popupWidth | number | string | 'trigger' | 浮层宽度;trigger 与触发控件等宽,auto 按内容定宽(可比控件窄),数字为固定像素值,也支持 CSS 长度。 |
popupMaxWidth | number | string | — | 可选的浮层最大宽度;未设置时不额外限制,仍受可视区域限制。 |
name | string | — | 原生 FormData 的字段名;非空值提交 JSON 路径,空值提交空字符串。 |
form | string | — | 关联的原生表单 ID。 |
required | boolean | false | 要求整体值非空,复合控件只校验一次。 |
popupPlacement | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | — | 浮层相对触发控件的位置。 |
popupClassName | string | — | 浮层的自定义类名。 |
popupStyle | CSSProperties | — | 浮层的自定义样式。 |
popupRender | (content: React.ReactNode) => React.ReactNode | — | 包装或补充面板内容,保留传入的内容以维持交互。 |
getPopupContainer | () => Element | DocumentFragment | — | 返回浮层的挂载容器,也可返回 ShadowRoot。 |
ref | Ref<HTMLButtonElement> | — | 触发按钮引用 |
#CascaderOption
级联选项的数据结构,子选项通过 children 组织。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | 必填 | 选项值;静态数据同层唯一,异步加载的节点须全树唯一以区分缓存。 |
label | ReactNode | 必填 | 选项的显示内容。 |
searchLabel | string | — | 复杂 label 的搜索纯文本。 |
isLeaf | boolean | — | 明确指定是否为叶子节点;配合懒加载使用。 |
disabled | boolean | false | 禁用该选项及其所有子级。 |
children | readonly CascaderOption[] | — | 子选项列表。 |
#CascaderFieldNames
通过 mapCascaderOptions(records, fields) 将业务数据转换为 CascaderOption[],再传给 options。CascaderFieldNames 描述映射字段,不是 Cascader 的属性。
import { mapCascaderOptions } from '@ifhover/leaf-ui';
const records = [{ id: 'design', name: '设计', nodes: [{ id: 'interface', name: '界面设计' }] }];
const options = mapCascaderOptions(records, {
value: 'id',
label: 'name',
children: 'nodes',
});| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | — | 选项值在业务对象中的字段名。 |
label | string | — | 显示文字在业务对象中的字段名。 |
children | string | — | 子节点数组在业务对象中的字段名。 |
disabled | string | — | 禁用状态在业务对象中的字段名。 |
isLeaf | string | — | 叶子标记在业务对象中的字段名。 |