# 树 Tree

- 页面: https://jiguang132.com/zh/resources/arco-design/docs/tree
- 资源: Arco Design (https://jiguang132.com/zh/resources/arco-design.md)
- 全部指南: https://jiguang132.com/zh/resources/arco-design/docs.md

对于文件夹、分类目录、组织架构等层级较多的内容，树可以清楚显示他们的层级关系，并具有展开、收起、选择等交互功能。

## 安装

```bash
npm install @arco-design/web-react@2.66.18
```

在入口引入 `@arco-design/web-react/dist/css/arco.css`，用 `ConfigProvider` 设置语言。React 19 项目还需在入口最先引入 `@arco-design/web-react/es/_util/react-19-adapter`，否则 Message、Modal 等命令式 API 无法渲染。

## 示例

- **基础用法**：为每个 `TreeNode` 节点赋予全局唯一的 `key`（必填项），`title` 为该节点显示的内容。
- **由treeData直接生成**
- **节点占一行**：节点占据一整行。
- **多选**：`Tree` 设置 `multiple` 属性为`true`，可以启用多选。
- **带复选框的树**：为 `Tree` 添加 `checkable` 属性即可使树具有复选框功能，可以用 `defaultCheckedKeys` 指定复选框默认选中的节点。
- **受控模式**：可以指定树的 `selectedKeys` 或 `checkedKeys` 或 `expandedKeys` 属性使树变为受控模式，在对应的 `onSelect` / `onCheck` / `onExpand` 回调中对返回值进行操作。
- **动态加载**：动态加载节点。
- **拖拽**：可拖拽的树节点。
- **设置回填方式**：为 `Tree` 添加 `checkedStrategy` 可以设置选中时的回填方式
- **显示连接线**：为 `Tree` 添加 `showLine` 属性即可使树具有连接线
- **不同尺寸**
- **定制节点图标**：只需为 `TreeNode` 指定 `icon` 属性的值即可为任意节点指定任意图标。
- **定制额外节点**：为 `Tree` 设置 `renderExtra` 可以自定义树节点的展示。
- **定制组件图标**：通过`icons` 属性即可设置组件 `loadingIcon`,`dragIcon`,`switcherIcon`。
- **虚拟列表**：通过指定 `virtualListProps` 来开启虚拟列表，在大量数据时获得高性能表现。
- **搜索树**
- **自定义 TreeData 的字段名称**：通过 `fieldNames` 字段可以自定义 TreeData 的字段名。

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

## API

### Tree

|参数名|描述|类型|默认值|版本|
|---|---|---|---|---|
|autoExpandParent|是否自动展开父节点|boolean |`true`|-|
|blockNode|是否节点占据一行|boolean |`-`|-|
|checkable|是否在节点前添加选框|boolean |`-`|-|
|checkStrictly|是否取消父子节点关联|boolean |`-`|-|
|draggable|是否可拖拽|boolean |`-`|-|
|multiple|是否支持多选|boolean |`-`|-|
|selectable|是否可以选择|boolean |`true`|-|
|showLine|是否展示连接线|boolean |`-`|-|
|size|不同尺寸|'mini' \| 'small' \| 'default' \| 'large' |`-`|-|
|actionOnClick|点击节点时对应的操作，可以是选中，复选选中，展开/收起|[ActionOnClick](#actiononclick) \| [ActionOnClick](#actiononclick)[] |`-`|select|
|allowDrop|是否允许拖拽时放置在该节点。 (`dragNode` in `2.23.0`)|[AllowDrop](#allowdrop) |`() => true`|2.7.0|
|checkedKeys|选中复选框的树节点。（受控）|string[] |`-`|-|
|checkedStrategy|定制回填方式 <br/> all: 返回所有选中的节点<br/> parent: 父子节点都选中时只返回父节点 <br/> child: 只返回子节点|SHOW_ALL \| SHOW_PARENT \| SHOW_CHILD |`all`|-|
|className|节点类名|string \| string[] |`-`|-|
|defaultCheckedKeys|默认选中复选框的树节点|string[] |`-`|-|
|defaultExpandedKeys|默认展开的节点。|string[] |`-`|-|
|defaultSelectedKeys|默认选中的树节点|string[] |`-`|-|
|expandedKeys|展开的节点，(受控)。|string[] |`-`|-|
|fieldNames|指定 key，title，isLeaf，disabled，children 对应的字段|[FieldNamesType](#fieldnamestype) |`-`|2.11.0|
|halfCheckedKeys|半选状态的节点.仅在 checkable 且 checkStrictly 时生效|string[] |`-`|2.27.0|
|loadMore|异步加载数据的回调，返回一个 `Promise`。|(node: [NodeInstance](#nodeinstance)) =&gt; Promise&lt;void&gt; |`-`|-|
|onDragEnd|节点结束拖拽的回调|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDragLeave|节点离开可释放目标上时的回调|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDragOver|节点被拖拽至可释放目标上时的回调|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDragStart|节点开始拖拽的回调|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDrop|节点在可释放目标上释放时的回调|(info: {e: DragEvent&lt;HTMLSpanElement&gt;;dragNode: [NodeInstance](#nodeinstance) \| null;dropNode: [NodeInstance](#nodeinstance) \| null;dropPosition: number;}) =&gt; void |`-`|-|
|selectedKeys|选中的树节点。（受控）|string[] |`-`|-|
|style|节点样式|CSSProperties |`-`|-|
|treeData|可以通过传入`treeData`,生成对应的树结构|[TreeDataType](#treedatatype)[] |`-`|-|
|virtualListProps|传递虚拟列表属性，传入此参数以开启虚拟滚动|[AvailableVirtualListProps](#availablevirtuallistprops) |`-`|2.11.0|
|icons|定制节点图标|\| ((nodeProps: [NodeProps](tree#treenode)) => {dragIcon?: ReactNode;switcherIcon?: ReactNode;loadingIcon?: ReactNode;})\| {dragIcon?: ReactNode;switcherIcon?: ReactNode;loadingIcon?: ReactNode;} |`FieldNamesType`|2.9.0|
|onCheck|点击树节点复选框的回调|(checkedKeys: string[],extra: {node: [NodeInstance](#nodeinstance);checkedNodes: [NodeInstance](#nodeinstance)[];checked: boolean;halfCheckedKeys: string[];halfCheckedNodes: [NodeInstance](#nodeinstance)[];e: Event;}) => void |`-`|-|
|onExpand|点击展开/关闭的回调|(expandedKeys: string[],exra?: { expanded: boolean; node: [NodeInstance](#nodeinstance); expandedNodes: [NodeInstance](#nodeinstance)[] }) => void |`-`|-|
|onSelect|点击树节点的回调|(selectedKeys: string[],extra: {selected: boolean;selectedNodes: [NodeInstance](#nodeinstance)[];node: [NodeInstance](#nodeinstance);e: Event;}) => void |`-`|-|
|renderExtra|渲染额外节点|(props: [NodeProps](tree#treenode)) => ReactNode |`-`|-|
|renderTitle|自定义 title 的渲染|(props: [NodeProps](tree#treenode)) => ReactNode |`-`|-|

### Tree.Node

|参数名|描述|类型|默认值|
|---|---|---|---|
|checkable|是否显示多选框|boolean |`-`|
|disableCheckbox|是否禁用复选框|boolean |`-`|
|disabled|是否禁用节点|boolean |`-`|
|draggable|当前节点是否可拖拽|boolean |`-`|
|isLeaf|是否是叶子节点。动态加载时有效|boolean |`-`|
|selectable|是否允许选中|boolean |`true`|
|icons|定制节点图标，优先级高于 Tree。同时设置 Tree 上的 icons 属性时候，将会进行合并。|[TreeProps](tree#tree)['icons'] |`-`|
|icon|该节点个性化显示的图标|ReactNode |`-`|
|title|该节点显示的标题|string \| ReactNode |`-`|
|className|节点类名|string \| string[] |`-`|
|style|节点样式|CSSProperties |`-`|

### AllowDrop

```js
export type AllowDrop = (options: {
  dropNode: NodeInstance;
  dragNode: NodeInstance | null;
  dropPosition: number;
}) => boolean;
```

### TreeDataType

```js
export type TreeDataType = NodeProps & {
  key?: string;
  _index?: number;
  children?: TreeDataType[];
  [key: string]: any;
};
```

### FieldNamesType

```js
export type FieldNamesType = {
  key?: string;
  title?: string;
  disabled?: string;
  children?: string;
  isLeaf?: string;
  disableCheckbox?: string;
  checkable?: string;
};
```

### AvailableVirtualListProps

```js
export type AvailableVirtualListProps = Pick<
  VirtualListProps<any>,
  | "height"
  | "itemHeight"
  | "threshold"
  | "isStaticItemHeight"
  | "scrollOptions"
  | "onScroll"
  | "wrapperChild"
>;
```

### ActionOnClick

```js
export type ActionOnClick = "select" | "check" | "expand";
```

### NodeInstance

```js
export type NodeInstance = ReactElement<
  PropsWithChildren<NodeProps>,
  typeof TreeNode
>;
```

### VirtualListProps

|参数名|描述|类型|默认值|
|------|:----------:|:--------:|-----:|
|height|可视区高度 (`2.11.0` 开始支持如 `80%` 的 `string` 类型)|`number`|`200`|
|threshold|自动开启虚拟滚动的元素数量阈值，传入`null`以禁用虚拟滚动。|`number`\|`null`|`100`|
|isStaticItemHeight|是否为相同高度的静态元素|`boolean`|`true`|

## 常见问题

1. `Tree` 设置了`autoExpandParent=true`，但没有默认展开全部节点？

  `autoExpandParent` 仅在 `Tree` 第一次挂载的时候生效。如果数据是从远程获取，可以在数据获取完成后，再去渲染 `Tree` 组件。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt