arco-design TreeSelect 基础用法:从 TreeNode 声明到源码级的选择器原理剖析
arco-design TreeSelect 基础用法:从 TreeNode 声明到源码级的选择器原理剖析
本文以 arco-design(@arco-design/web-react,当前仓库版本 2.66.18)中 TreeSelect 组件的"基础用法"示例为主线,完整讲解最简树选择器的写法:如何用 TreeSelect.Node 声明式地搭建树形选项、defaultValue 与 allowClear 如何工作、节点 key 为何是选中值的唯一身份。在此基础上,结合 components/TreeSelect/tree-select.tsx 等源码,剖析组件从子节点数据到选中回显的完整数据流,帮助读者从"会照抄 demo"进阶到"看得懂底层"。
一、基础用法:声明式节点 + defaultValue + allowClear
components/TreeSelect/demo/basic.md 给出的示例就是 TreeSelect 最简形态——"最简单的用法":不传 treeData,而是把树结构以 JSX 子节点的方式直接声明在组件内部。完整代码如下:
import { TreeSelect } from '@arco-design/web-react';
const TreeNode = TreeSelect.Node;
const App = () => {
return (
<TreeSelect defaultValue="node1" style={{ width: 300 }} allowClear>
<TreeNode key="node1" title="Trunk">
<TreeNode key="node2" title="Leaf" />
</TreeNode>
<TreeNode key="node3" title="Trunk2">
<TreeNode key="node4" title="Leaf" />
<TreeNode key="node5" title="Leaf" />
</TreeNode>
</TreeSelect>
);
};
export default App;
这个示例中每一行都有明确的职责,逐项拆解:
const TreeNode = TreeSelect.Node:TreeNode并非独立组件,而是挂在TreeSelect上的静态属性Node,其实际来源是Tree组件的Node。可以在 components/TreeSelect/tree-select.tsx 中看到静态挂载逻辑:TreeSelectComponent.Node = Tree.Node,同时还挂载了SHOW_ALL、SHOW_PARENT、SHOW_CHILD三个回显策略常量(同样来自Tree)。<TreeNode key="node1" title="Trunk">:key是节点的唯一标识,也是选择器选中值(value)的载体;title是下拉面板中展示的文本以及选中后的回显文本。嵌套<TreeNode>的层级关系即树的父子关系。defaultValue="node1":非受控模式的默认选中值,此处选中根节点node1。选中后选择框内回显该节点的title(即 "Trunk")。style={{ width: 300 }}:选择框宽度。TreeSelect 基于输入框视图(SelectView)渲染,宽度需要显式给定,否则在块级布局中会充满父容器。allowClear:允许点击右侧出现的清除图标一键清空当前值。
关于 allowClear 的实际行为,测试用例 components/TreeSelect/test/index.test.tsx 中 "allowClear props" 给出了可验证的证据:先选中 node1(onChange 收到 'node1'),再点击清除图标 .arco-icon-close 后,value 变为 undefined。对应到源码,清除动作在 components/TreeSelect/tree-select.tsx 中通过 onClear 回调处理:调用 triggerChange([], {}) 把内部值置空,随后再触发 props.onClear?.(!!popupVisible) 把当前下拉框展开状态交给业务侧。
二、两种数据源:children 声明式 vs treeData 数据驱动
basic.md 示例使用的是 children 声明式写法,而 components/TreeSelect/demo/treeData.md 演示了另一种等价方式——传入 treeData 数组生成树结构:
const treeData = [
{
key: 'node1',
title: 'Trunk',
disabled: true,
children: [
{ key: 'node2', title: 'Leaf' },
],
},
{
key: 'node3',
title: 'Trunk2',
children: [
{ key: 'node4', title: 'Leaf' },
{ key: 'node5', title: 'Leaf' },
],
},
];
const App = () => {
return <TreeSelect treeData={treeData} placeholder="请选择..." style={{ width: 300 }} />;
};
两种写法为什么可以互换?答案在内部 Hook components/TreeSelect/hook/useTreeData.ts:
const getData = () => {
return props.treeData || getTreeDataFromTreeChildren(props.children);
};
即组件优先使用 treeData;未传 treeData 时,才把 JSX 子节点通过 components/Tree/util.tsx 的 getTreeDataFromTreeChildren 拍平为普通对象数组——递归遍历 React.Children,把每个 child.props 与其 child.key 合并成 { key, title, children, ... } 结构。这解释了 basic.md 示例中 key 必须写在 <TreeNode> 上的原因:拍平过程依赖 child.key 提取节点身份。
此外该 Hook 还通过 useUpdate 监听 props.treeData 与 props.children 的引用变化来更新内部数据,因此两种数据源都可以安全地做动态更新。
三、选中值的内部流转:key 是唯一的选中身份
basic.md 中 defaultValue="node1" 传入的只是字符串,为什么选择框能回显出 "Trunk"?关键在 key 到节点属性的缓存映射。
3.1 useKeyCache:为每个 key 建立节点索引
components/TreeSelect/hook/useKeyCache.ts 中的 getKey2NodeProps 会递归遍历整棵 treeData,为每个节点生成 key2nodeProps 映射。除了 key、title 等原始字段,还会附加一批内部字段:
parentKey、pathParentKeys:父节点链,供父子勾选联动和搜索命中祖先回溯使用;_level、_index:层级与全局序号;- 对每层最后一个子节点追加
-node-is-tail类名,供样式收尾。
如果数据项没有 key 字段,会回退为 ${father?._key || ''}-${index} 拼接生成——这也是 components/TreeSelect/interface.ts 中 DefaultFieldNames 定义了 key/title/children/selectable/disabled/disableCheckbox/checkable/isLeaf 八个默认字段名的原因,业务方可通过 fieldNames 整体映射后端字段。
3.2 useStateValue:字符串 key 如何变成回显文本
components/TreeSelect/hook/useStateValue.ts 的 parseValue 负责把 defaultValue/value 统一解析为内部的 LabelValue<a href="https://link.gitcode.com/i/61da25669ff3e0ddee1a502d8d80f565" target="_blank">](即 { label, value, disabled? }[],类型定义见 [components/TreeSelect/interface.ts):
- 传入的字符串
'node1'先被包装成{ value: 'node1', label: undefined }; - 再查
key2nodeProps['node1'],命中后label被填充为该节点的title("Trunk"),同时继承节点自身的disabled状态; - 若树中查不到该 key,则依次回退到上一次的值缓存,最后
label兜底为value本身——这保证了异步数据未加载时(treeData=<a href="https://link.gitcode.com/i/f9fada8a4bd2444bcfce3ba9b5c63026" target="_blank">])也能正常回显 key 文本,[components/TreeSelect/test/index.test.tsx 的 "renderFormat correctly async" 用例正是验证了这一"数据晚到"场景:先treeData={[]}回显 key,数据到达后自动切换为title。
反向的 onChange 输出由 components/TreeSelect/hook/useStateValue.ts 的 setStateValue 完成:单选时输出 newValue<a href="https://link.gitcode.com/i/0a647bc707c8d6a24065d6b4b455ea9d" target="_blank">0].value(即字符串 key),multiple 时输出 key 数组;开启 labelInValue 后输出对象/对象数组。测试 "select correctly"([index.test.tsx)验证了点击节点后 onChange 收到 'node1'、'node1-1',而视图回显的是节点的 title 文本——与 basic.md 示例的行为完全一致。
四、选中交互与下拉行为:源码中的关键链路
基础示例只展示了点击选中和清除,但理解以下几条链路,能解释"基础用法"背后组件的完整行为:
- 点击面板内节点:下拉面板由 components/TreeSelect/tree-list.tsx 的
handleChange接管,把节点包装为{ value: node.props._key, label: node.props.title }后经triggerChange更新;单选模式下triggerChange(tree-select.tsx)会顺带tryUpdatePopupVisible(false)收起面板——这正是测试 "popOver expand and collapse" 断言的"选中后onVisibleChange(false)"行为。 - 受控模式:
value与defaultValue二选一。传入value后组件变为受控,测试 "be controlled"(index.test.tsx)验证了 rerender 切换value后回显文本同步变化("小恶魔" → "史塔克家族")。 - 禁用状态:
disabled时测试断言下拉面板不会渲染(wrapper.find('Tree')长度为 0),见 index.test.tsx。 - 空状态与搜索:面板内无数据(或搜索无命中)时渲染
notFoundContent或renderEmpty('TreeSelect')(tree-select.tsx);showSearch开启后搜索输入经 100ms 防抖的handleSearch过滤节点(tree-select.tsx),命中的节点标题还会被 tree-list.tsx 的renderTitle高亮。
五、基础示例涉及参数的 API 速查
围绕 basic.md 用到的核心参数,结合 components/TreeSelect/README.zh-CN.md 与 components/TreeSelect/interface.ts 整理如下(完整参数表以 README 为准):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
defaultValue |
string | string[] | LabelValue | LabelValue[] |
- |
选择框默认值(非受控);对象形式即 { label, value, disabled? } |
value |
同 defaultValue |
- |
受控选中值,传入后 defaultValue 失效 |
treeData |
TreeSelectDataType[] |
- |
数据驱动模式的树数据,与 children 二选一 |
allowClear |
boolean |
- |
允许清除值,见第二节清除链路 |
placeholder |
string |
- |
无选中值时的提示文字 |
style |
CSSProperties |
- |
选择框样式,示例中用于固定 300px 宽 |
labelInValue |
boolean |
- |
onChange/value 使用 { label, value } 对象格式 |
multiple |
boolean |
- |
是否多选,多选时值为 key 数组 |
treeCheckable |
boolean |
- |
显示复选框(等价进入多选) |
treeCheckedStrategy |
'all' | 'parent' | 'child' 或 SHOW_* 常量 |
SHOW_CHILD |
定制勾选回显方式,常量可从 TreeSelect.SHOW_ALL/PARENT/CHILD 获取 |
showSearch |
boolean | { retainInputValue?: boolean; retainInputValueWhileSelect?: boolean } |
- |
允许搜索,可配置搜索文本保留策略 |
fieldNames |
FieldNamesType |
DefaultFieldNames |
映射 key/title/children/isLeaf 等字段名 |
onChange |
(value, extra) => void |
- |
选中变化回调,extra 含 trigger/checked/selected |
onVisibleChange |
(visible: boolean) => void |
- |
面板展开/收起回调 |
六、进阶方向与参考路径
基础示例解决的是"单节点树的选择",当需求升级时,TreeSelect 的其余官方示例(均位于 components/TreeSelect/demo/)给出了对应方案:
- 多选与复选框:multiple.md、checkable.md、checkedStrategy.md(
treeCheckedStrategy三种回显策略); - 受控/非受控切换:controled.md;
- 搜索与异步检索:search.md、onSearch.md(自定义
onSearch); - 异步加载子节点:loadmore.md(
loadMore回调 +dataRef,测试见 index.test.tsx 的 "options loadMore"); - 大量数据的虚拟滚动:virtual.md;
- 自定义字段名/字段映射:fieldnames.md;
- 回显定制:renderFormat.md、labelInvalue.md。
组件的核心文件结构可供延伸阅读:入口 components/TreeSelect/index.tsx → 主组件 tree-select.tsx(Trigger 挂载下拉、SelectView 渲染视图)→ tree-list.tsx(内嵌 Tree 并接管 onSelect/onCheck)→ 三个状态 Hook(useTreeData/useKeyCache/useStateValue)。单元测试 index.test.tsx 与 demo 快照测试 demo.test.ts 则为本文描述的每一项行为提供了可执行的验证依据。