Cascader
cascader级联选择 · 触发器 + Popover 横向逐级面板列 + 路径数组受控 + click/hover 展开 + changeOnSelect · 复用树引擎核
用法
基础用法
点击逐级展开，选到叶子节点提交整条路径。非受控时用 defaultValue 设初值。
tsx
<Cascader
nodes={nodes}
placeholder="选择地区"
onChange={(path, nodePath) => setValue(path)}
/>hover 展开
expandTrigger="hover" 时移入即逐列展开，点击才提交。
tsx
<Cascader nodes={nodes} expandTrigger="hover" placeholder="选择地区" />任意层可选
changeOnSelect 允许选中任意一级（不必到叶子）即提交。
tsx
<Cascader nodes={nodes} changeOnSelect placeholder="选择地区" />默认值与可搜索
defaultValue 回显路径；showSearch 在浮层顶部出搜索框，输入直达叶子。
tsx
<Cascader
nodes={nodes}
defaultValue={["zhejiang", "hangzhou", "xihu"]}
showSearch
/>禁用态
tsx
<Cascader nodes={nodes} disabled placeholder="选择地区" />何时用
省/市/区、分类/子类、组织层级等「有父子层级、要逐级下钻选一条完整路径」的场景用。值是从根到所选节点的 key 路径数组。默认须选到叶子；开 changeOnSelect 允许任意层提交。若数据是扁平的单层选项，用 Combobox/Listbox 即可，不必引入级联。
导入
ts
import { Cascader, flattenLeafPaths, filterLeafPaths, type CascaderLeafPath } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| nodes* | TreeNode[] | — | 层级数据（复用 tree-core 的 TreeNode，含 key/label/children/disabled） |
| value | string[] | — | 受控路径（从根到所选节点的 key 数组） |
| defaultValue | string[] | — | 非受控初始路径 |
| expandTrigger | "click" | "hover" | "click" | 逐级展开触发方式 |
| changeOnSelect | boolean | false | 任意层节点都可提交（非仅叶子） |
| showSearch | boolean | — | 浮层顶部出搜索框：扁平成叶子路径模糊匹配，命中行选中即提交全路径 |
| searchPlaceholder | string | — | 搜索框占位符 |
| placeholder | string | — | 触发器占位符 |
| disabled | boolean | — | 禁用 |
| invalid | boolean | — | 校验失败态 |
| size | "sm" | "md" | "lg" | — | 触发器尺寸 |
| className | string | — | 容器类名 |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onChange | (path: string[], nodes: TreeNode[]) => void | 选中变化，回传 key 路径与对应节点链 |
禁忌 / 坑
value是完整 key 路径数组（如["zhejiang","hangzhou","xihu"]），不是单个叶子 key；回填时要给全路径，否则展开列对不上。disabled的节点不可选、其子树也不会因它而展开。onChange第二参是节点链（TreeNode[]），需要 label 做回显时取它而非自己再查表。- 暂无其它已知坑。
相关
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
<Cascader
nodes={nodes}
expandTrigger="click"
value={value}
onChange={(path) => setValue(path)}
/>