TreeSelect
tree-select树选择器 · 触发器 + Popover 浮层内嵌 Tree + 单选/多选(checkable)对称 + 树内搜索 + clearable 清除回未选态(与 Select 对称) · 复用树引擎核
用法
单选 + 搜索
默认单选：点叶子即提交并收起。searchable 在浮层顶部出搜索框，可在多层里命中跳转。非受控用 defaultValue 设初值。
tsx
<TreeSelect
nodes={nodes}
searchable
placeholder="选择归属部门"
onChange={(v) => setValue(v)}
/>多选（父子级联）
multiple 时节点出复选框，勾父级联到叶，取消单个叶让父级落半选态；value 收敛为叶子键集合。
tsx
<TreeSelect
nodes={nodes}
multiple
defaultValue={["fe-web", "fe-mini"]}
placeholder="勾选可见部门"
onChange={(v) => setValue(v)}
/>可清除（clearable）
有值且未禁用时，hover 或键盘聚焦触发器右侧会浮出清除按钮（箭头让位），点击回到未选态：单选回传空串、多选回传空数组。层级筛选维度留空 = 不限，必开。
当前值："fe-web"
tsx
<TreeSelect
nodes={nodes}
clearable
value={value}
onChange={setValue}
placeholder="全部部门"
/>多选可清除
多选下清除按钮一次清空所有勾选（回传 []），不必逐个取消。
tsx
<TreeSelect nodes={nodes} multiple clearable defaultValue={["fe-web", "fe-mini"]} />禁用态
tsx
<TreeSelect nodes={nodes} disabled defaultValue="fe-web" />何时用
数据源本身是层级结构（组织架构、分类目录、地区），需要在收拢的触发器里选一个或多个节点时用。若选项是扁平列表用 Combobox/Listbox；若是固定的省市区级联用 RegionCascader。
导入
ts
import { TreeSelect } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| nodes* | TreeNode[] | — | 树数据源（含 key/label/children），从 ../tree/tree-core 复用 |
| value | string | string[] | — | 受控值；单选为 string，多选为 string[] |
| defaultValue | string | string[] | — | 非受控初值 |
| multiple | boolean | false | 多选（checkable，父子级联勾选） |
| placeholder | string | — | 触发器占位文案 |
| disabled | boolean | false | 禁用 |
| invalid | boolean | false | 无效态（外壳变 danger） |
| size | "sm" | "md" | "lg" | "md" | 触发器尺寸 |
| clearable | boolean | false | 可清除：有值且未禁用时触发器右侧 hover/聚焦浮出清除按钮，点击回到未选态（单选回传 ""，多选回传 []）。与 Select 的 clearable 语义一致 |
| searchable | boolean | false | 浮层内树搜索框，多层命中跳转 |
| expandTrigger | "row" | "icon" | "row" | 什么东西触发展开/收起，透传给内部 Tree。默认 `"row"` 下单选只有叶子选得中；要「选到中间层」（某个部门 / 某个大类 / 某一册）传 "icon"：箭头管展开、行管选中 |
| showLine | boolean | — | 显示树连接线 |
| className | string | — | 透传到触发器 |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onChange | (value: string | string[]) => void | 选择变更回调；单选回传 string，多选回传 string[] |
禁忌 / 坑
- 单选默认没有清除入口，选中后无法在组件内回到未选态；凡是「可留空的筛选维度」都要开
clearable，否则筛选条件只能收窄不能放宽。 value受控时multiple切换会改变值的类型（string ↔ string[]），onChange 回调的入参类型随multiple而变，消费侧需按当前模式分支处理，不要混存。- 多选下
value只需传叶子/已选 key，父级半选态由组件依树结构派生，不要手动塞入半选父 key。 - 单选默认只有叶子节点可选：
expandTrigger缺省是"row"，有子节点的行点了只展开、不回传onChange，点几次都选不中。需要提交任意层级就传expandTrigger="icon"（箭头管展开、行管选中），或改用 Cascader 的changeOnSelect。多选不受影响——勾选框是独立命中区。
相关
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
<TreeSelect
nodes={nodes}
searchable
value={value}
onChange={setValue}
/>