arco-design TreeSelect 基础用法:从 TreeNode 声明到源码级的选择器原理剖析

原创2026-10-13 16:41:102,189 阅读
文章标签:UI组件前端设计系统

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/)给出了对应方案:

组件的核心文件结构可供延伸阅读:入口 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 则为本文描述的每一项行为提供了可执行的验证依据。

登录后查看全文
arco-design