Cascader#
数据录入
@rockshin/tao-ui通过搜索、多选或独立面板,从层级选项中选择完整路径。
每个示例都可以独立复制运行。带设备预览的示例可通过工具栏切换桌面与手机宽度。
尺寸支持 small、medium、large;兼容别名 middle 与 medium 使用相同尺寸。
窄于 576px 时自动使用底部抽屉;可用 mobile 强制选择展示方式,mobileTitle 指定抽屉标题。手机端单选即时提交,多选点击 Done 后提交,关闭则取消本次修改。桌面端 hover 时清除按钮替换箭头,触屏始终显示清除按钮。
#示例
#选择完整路径
选中值按顺序包含路径中的各级 value。
Asia / China / Shanghai
TSX
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function BasicCascader() {
return (
<Cascader
aria-label="Location"
options={options}
defaultValue={['asia', 'china', 'shanghai']}
allowClear
style={{ width: '100%' }}
/>
);
}#受控路径与展示
displayRender 可以缩短展示文字,同时在状态中保留完整路径。
Tokyo
asia / japan / tokyo
TSX
import { useState } from 'react';
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function ControlledLocation() {
const [value, setValue] = useState<string[]>(['asia', 'japan', 'tokyo']);
return (
<div>
<Cascader
multiple={false}
options={options}
value={value}
onChange={setValue}
displayRender={(labels) => labels.at(-1)}
style={{ width: '100%' }}
/>
<p>{value.join(' / ')}</p>
</div>
);
}#选择多条路径
多选模式提供联动复选框;SHOW_CHILD 展示已选叶子路径。
+ 0 ...
TSX
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function MultipleLocations() {
return (
<Cascader
options={options}
multiple
showCheckedStrategy={Cascader.SHOW_CHILD}
defaultValue={[['asia', 'china', 'shanghai']]}
maxTagCount="responsive"
placeholder="Choose locations"
style={{ width: '100%' }}
/>
);
}#搜索路径中的各级文字
过滤函数检查整条路径的标签,选择搜索结果后返回完整路径。
Search country or city
TSX
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function SearchLocations() {
return (
<Cascader
options={options}
showSearch={{
filter: (input, path) =>
path.some((option) =>
String(option.label).toLowerCase().includes(input.toLowerCase()),
),
}}
placeholder="Search country or city"
style={{ width: '100%' }}
/>
);
}#选择中间层级
changeOnSelect 允许选择中间路径;本例通过鼠标悬停展开下一列。
Choose a continent, country or city
TSX
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function IntermediateLocation() {
return (
<Cascader
options={options}
changeOnSelect
expandTrigger="hover"
placeholder="Choose a continent, country or city"
style={{ width: '100%' }}
/>
);
}#映射自定义字段
通过字段映射直接使用已有业务数据。
Choose a region
TSX
import { Cascader } from '@rockshin/tao-ui';
export default function RegionFields() {
return (
<Cascader
fieldNames={{ label: 'name', value: 'code', children: 'regions' }}
options={[
{
code: 'cn',
name: 'China',
regions: [
{ code: 'sh', name: 'Shanghai' },
{ code: 'hz', name: 'Hangzhou' },
],
},
]}
placeholder="Choose a region"
style={{ width: '100%' }}
/>
);
}#按需加载下一列
此处用本地延迟模拟请求。未加载的父节点设置 isLeaf:false,加载后更新 options。
Load cities
TSX
import { useState } from 'react';
import { Cascader, type DefaultOptionType } from '@rockshin/tao-ui';
export default function AsyncLocations() {
const [options, setOptions] = useState<DefaultOptionType[]>([
{ value: 'china', label: 'China', isLeaf: false },
]);
return (
<Cascader
options={options}
changeOnSelect
loadData={async (selected) => {
const target = selected.at(-1)!;
target.loading = true;
setOptions([...options]);
await new Promise((resolve) => setTimeout(resolve, 500));
target.loading = false;
target.children = [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
];
setOptions([...options]);
}}
placeholder="Load cities"
style={{ width: '100%' }}
/>
);
}#独立面板
Cascader.Panel 直接展示级联列,不使用输入触发器。
- Asia
- Europe
TSX
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function LocationPanel() {
return (
<Cascader.Panel
options={options}
defaultValue={['asia', 'china', 'shanghai']}
/>
);
}#手机底部抽屉
在手机模式下通过底部抽屉选择三级路径,级联列超出可用宽度时可以横向滚动。
单选在选中路径时立即生效。使用 multiple 时,抽屉里的更改在点击「完成」后才应用。从 0.0.49 起,组件会跳过确认前被移除或禁用的新选路径,保留此前已经提交且用户仍保留选中的路径。
TSX
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function MobileLocation() {
return (
<div style={{ padding: 16 }}>
<h3>Delivery location</h3>
<Cascader
aria-label="Delivery location"
mobileTitle="Delivery location"
size="middle"
options={options}
showSearch
allowClear
variant="filled"
style={{ width: '100%' }}
/>
</div>
);
}