For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/cascader.md.

Cascader 级联选择

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

基础用法

children 定义子选项。展开父项后选择末级选项,确认完整路径;disabled 禁用整个分支。

basic.tsx
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 同时返回完整的选项对象路径。清除时,两者都为空数组。展开父项只改变待选路径;返回已提交路径所属的一级分支时,会恢复下级选择。

选中路径:["zhejiang","hangzhou","xihu"]
controlled.tsx
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 按完整路径展示匹配结果。搜索只覆盖已提供或已加载的选项,不会自动请求远程数据。

search.tsx
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[][],每项是一条完整路径。再次选择同一路径会取消选择,选择后浮层保持打开。

选中路径数:2
multiple.tsx
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 限制可见标签数。打开浮层可查看和修改全部选择。

single-line.tsx
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 保留触发控件的聚焦能力,但不允许打开浮层、清除或修改值。

states.tsx
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 允许提交中间层级的路径。选择仍有子项的节点时,浮层保持打开,可以继续向下选择。

选中路径:[]
intermediate.tsx
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 提供失败反馈,再次展开节点可重试。

lazy.tsx
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,清空已加载的子选项并取消旧请求。此例保持选项和加载函数不变;刷新后重新展开分类,加载新版本。

缓存版本:v1; 加载版本:未加载
cache.tsx
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 限制最大宽度;省略时默认与触发控件等宽。其他浮层配置见共享浮层参数。

popup.tsx
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 作用于外层容器。

属性类型默认值说明
optionsreadonly CascaderOption[]必填层级选项列表
valuereadonly string[] | readonly (readonly string[])[]—受控路径;省略时使用内部非受控值。
defaultValuereadonly string[] | readonly (readonly string[])[][]非受控模式的初始路径;支持表单重置。
onChange((value: string[], selectedOptions: CascaderOption[]) => void) | ((value: string[][], selectedOptions: CascaderOption[][]) => void)—单选返回路径和对应选项,多选返回路径数组和对应选项数组;选择、取消或清除时触发,清除的两参数均为空数组。
multiplefalse | truefalse启用多选;value 和回调的类型随之变化。
placeholderstring'请选择'未选择时的提示文字
size'sm' | 'md' | 'lg''md'选择器尺寸
status'error' | 'warning'—校验状态
disabledbooleanfalse禁用交互。
readOnlyboolean—锁定业务值,禁止输入、选择、清除和删除。
allowClearbooleantrue清除后返回两个空数组
showSearchboolean—启用搜索输入。
changeOnSelectboolean—允许选择中间层级。
tagWrapbooleantrue允许多选标签换行;false 单行显示并自动折叠溢出项。
maxTagCountnumber | '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—加载失败时调用,可展示重试提示。
cacheKeystring | number—数据版本改变时清空懒加载缓存,并取消旧请求。
openboolean—受控的展开状态。
defaultOpenbooleanfalse非受控模式的初始展开状态。
onOpenChange(open: boolean) => void—面板展开或收起
popupWidthnumber | string'trigger'浮层宽度;trigger 与触发控件等宽,auto 按内容定宽(可比控件窄),数字为固定像素值,也支持 CSS 长度。
popupMaxWidthnumber | string—可选的浮层最大宽度;未设置时不额外限制,仍受可视区域限制。
namestring—原生 FormData 的字段名;非空值提交 JSON 路径,空值提交空字符串。
formstring—关联的原生表单 ID。
requiredbooleanfalse要求整体值非空,复合控件只校验一次。
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。
refRef<HTMLButtonElement>—触发按钮引用

CascaderOption

级联选项的数据结构,子选项通过 children 组织。

属性类型默认值说明
valuestring必填选项值;静态数据同层唯一,异步加载的节点须全树唯一以区分缓存。
labelReactNode必填选项的显示内容。
searchLabelstring—复杂 label 的搜索纯文本。
isLeafboolean—明确指定是否为叶子节点;配合懒加载使用。
disabledbooleanfalse禁用该选项及其所有子级。
childrenreadonly 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',
});
属性类型默认值说明
valuestring—选项值在业务对象中的字段名。
labelstring—显示文字在业务对象中的字段名。
childrenstring—子节点数组在业务对象中的字段名。
disabledstring—禁用状态在业务对象中的字段名。
isLeafstring—叶子标记在业务对象中的字段名。