级联选择 Cascader

多层级数据的选择。

安装

npm install antd-mobile@5.43.0

antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 unstableSetRender 注册 createRoot，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 <html data-prefers-color-scheme="dark"> 切换。

示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 DemoBlock 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。

多层级数据的选择。

何时使用

需要从一组相关联的数据集合进行选择，例如省市区，公司层级，事物分类等。

示例

Cascader

属性

type CascaderValue = string | null

type CascaderOption = {
  label: string
  value: string
  disabled?: boolean
  children?: CascaderOption[]
}

type CascaderValueExtend = {
  items: (CascaderOption | null)[]
  isLeaf: boolean
}

属性	说明	类型	默认值
activeIcon	选中图标	`ReactNode`	-
cancelText	取消按钮的文字	`ReactNode`	`'取消'`
children	所选项的渲染函数	`(items: CascaderOption[], actions: CascaderActions) => ReactNode`	-
confirmText	确定按钮的文字	`ReactNode`	`'确定'`
defaultValue	默认选中项	`CascaderValue[]`	`[]`
destroyOnClose	不可见时是否销毁 `DOM` 结构	`boolean`	`true`
forceRender	强制渲染内容	`boolean`	`false`
onCancel	取消时触发	`() => void`	-
onClose	确认和取消时都会触发关闭事件	`() => void`	-
onConfirm	确认时触发	`(value: CascaderValue[], extend: CascaderValueExtend) => void`	-
onSelect	选项改变时触发	`(value: CascaderValue[], extend: CascaderValueExtend) => void`	-
onTabsChange	切换面板的回调	`(index: number) => void`	-
options	级联数据	`CascaderOption[]`	-
placeholder	未选中时的提示文案	`string`	`'请选择'`
title	标题	`ReactNode`	-
value	选中项	`CascaderValue[]`	-
visible	是否显示级联选择	`boolean`	`false`
loading	开启骨架屏	`boolean`	`false`
optionRender	自定义选项的渲染函数	`(option: CascaderOption, info: { depth: number, active: boolean }) => ReactNode`	-

请留意 CascaderOption 的 children 属性，如果某个 option 的 children 为 []，那当用户选择了这个 option 时，Cascader 组件会自动跳转到下一级，即便这一级当前是没有任何选项的（因为 Cascader 没有办法判断，在后续的更新中，这个空数组会不会变为一个有内容的数组）。因此，请确保最末一级的 option（也就是"叶子节点"）的 children 属性不存在或者值为 undefined，这样 Cascader 组件才能将其正确地识别。

CascaderActions

属性	说明	类型
close	关闭 Cascader	`() => void`
open	显示 Cascader	`() => void`
toggle	切换 Cascader 的显示和隐藏状态	`() => void`

Ref

同 CascaderActions。

加载中 <Experimental></Experimental>

你可以把 Cascader.optionSkeleton 作为 CascaderOption[] 传入到 Cascader 的 options 属性或者是 CascaderOption 的 children 中。Cascader 会将其识别并显示出骨架屏效果。