Semi Design Tree 树形控件完全指南:从基础用法到高级定制与源码原理
Semi Design Tree 树形控件完全指南:从基础用法到高级定制与源码原理
本篇技术指南围绕 Semi Design(@douyinfe/semi-ui)的 Tree 树形控件展开,覆盖组件引入、单选/多选、搜索过滤、异步加载、拖拽排序、虚拟化长列表、完全自定义渲染等完整能力,并结合仓库源码(组件实现 与 Foundation 逻辑)解释底层数据转换、勾选联动与过滤机制。读完本文,你将掌握用 Tree 构建从文件目录、组织架构到商品分类等各类层级列表的完整实战方案,并理解其受控/非受控、展开/勾选等核心状态模型。
Tree 组件定位与引入
Tree 是 Semi Design 导航类(Navigation)组件,用于呈现层级结构列表。在 content/navigation/tree/index-en-US.md 中它被定义为一款“呈现层级列表的树形视图组件”(brief: A tree view component presents a hierarchical list),适用于目录、组织架构、分类等场景。
引入方式极为简单,从 @douyinfe/semi-ui 具名导入即可:
import { Tree } from '@douyinfe/semi-ui';
组件的核心数据载体是 treeData(TreeNodeData[]),每个节点至少需要唯一的 key 与展示用的 label,可选 value、children、icon、disabled、isLeaf 等字段。默认情况下 Tree 为单选模式,每一级菜单项均可选择。
基本用法:单选与多选
单选(默认)
不传 multiple 时,Tree 处于单选模式。下面的示例构造了一棵包含两级子节点的树,并通过 defaultExpandAll 在初始化时展开全部节点:
import React from 'react';
import { Tree } from '@douyinfe/semi-ui';
() => {
const treeData = [
{
label: 'Asia',
value: 'Asia',
key: '0',
children: [
{
label: 'China',
value: 'China',
key: '0-0',
children: [
{ label: 'Beijing', value: 'Beijing', key: '0-0-0' },
{ label: 'Shanghai', value: 'Shanghai', key: '0-0-1' },
],
},
{
label: 'Japan',
value: 'Japan',
key: '0-1',
children: [{ label: 'Osaka', value: 'Osaka', key: '0-1-0' }],
},
],
},
{
label: 'North America',
value: 'North America',
key: '1',
children: [
{ label: 'United States', value: 'United States', key: '1-0' },
{ label: 'Canada', value: 'Canada', key: '1-1' },
],
},
];
const style = {
width: 260,
height: 420,
border: '1px solid var(--semi-color-border)',
};
return <Tree treeData={treeData} defaultExpandAll style={style} />;
};
多选与父子联动
设置 multiple 进入多选模式。多选时遵循经典的父子联动规则:当某一父项的所有子项都被选中时,父项自动被勾选;反之取消父项会级联取消子项。若子项部分选中,父项呈现半选(halfChecked)状态。从源码看,勾选关系的计算集中在 treeUtil.ts 的 calcCheckedKeys、calcCheckedKeysForChecked 与 calcCheckedKeysForUnchecked 中,它们递归维护 checkedKeys 与 halfCheckedKeys 两个集合。
<Tree treeData={treeData} multiple defaultExpandAll style={style} />
如果希望多选时节点间勾选互不影响(例如"仅收集叶子权限点"的场景),可以配合 checkRelation='unRelated'(见下文“节点选中关系”)。
受控组件
Tree 支持完全受控:通过 value + onChange 控制选中值。受控时 value 取的是节点 data 的 value 属性(v>=1.7.0 之后若节点未定义 value,则回退指向 key):
class Demo extends React.Component {
constructor() {
super();
this.state = { value: 'Shanghai' };
}
onChange(value) {
this.setState({ value });
}
render() {
return (
<Tree
treeData={treeData}
value={this.state.value}
onChange={value => this.onChange(value)}
style={style}
/>
);
}
}
搜索与过滤
开启搜索:filterTreeNode
通过 filterTreeNode 开启搜索框。默认对节点的 label 值进行匹配,可用 treeNodeFilterProp 改为其他字段;也可以直接传入函数自定义匹配逻辑,filterTreeNode 同时接受 boolean 与函数两种形式:
<Tree
treeData={treeData}
multiple
filterTreeNode // 开启搜索,默认按 label 过滤
showFilteredOnly={false} // 是否只展示过滤后的结果
style={style}
/>
- 当
showFilteredOnly为false(默认)时,搜索会保留不匹配节点的父链路,便于看清命中节点所处的层级; - 当
showFilteredOnly为true时,只渲染命中的节点与必要祖先,搜索结果更聚焦。
自定义搜索框:searchRender
开启搜索后,可通过 searchRender 自定义搜索框渲染。它接收包含 prefix 等 props 的对象,返回自定义输入组件;设为 false 可完全隐藏内置搜索框(常见于搜索框放在 Tree 外部、或与页面顶部全局搜索联动的场景):
<Tree
filterTreeNode
searchRender={({ prefix, ...restProps }) => (
<Input prefix="Search" {...restProps} />
)}
treeData={treeData}
/>
搜索框还支持 searchPlaceholder、searchStyle、searchClassName 等样式属性,以及 showClear(是否展示清空按钮,默认 true)。
手动触发搜索:ref + search()
当搜索框位于 Tree 之外时,可以通过 ref 拿到 Tree 实例并调用其 search 方法主动触发搜索。前提是同时设置 filterTreeNode 开启搜索能力,并用 searchRender={false} 隐藏内部搜索框:
() => {
const ref = useRef();
return (
<div>
<Input
aria-label="filter tree"
prefix="Search"
showClear
onChange={v => ref.current.search(v)}
/>
<Tree
ref={ref}
filterTreeNode
searchRender={false}
treeData={treeData}
blockNode={false}
/>
</div>
);
};
search 是 Tree 通过 ref 暴露的实例方法(见文档 Methods 一节),类型为 (value: string) => void。
数据格式:treeDataSimpleJson
除结构化的 treeData 外,Tree 还支持用 treeDataSimpleJson 传入极简 JSON 格式数据。转换规则为:JSON 键值对中的 key 作为节点的 key 与 label,value 作为节点的 value;value 为对象时递归展开为子节点,为标量时即为叶子节点:
() => {
const json = {
'Node1': {
'Child Node1': '0-0-1',
'Child Node2': '0-0-2',
},
'Node2': '0-1',
};
return (
<Tree
treeDataSimpleJson={json}
multiple
onChange={e => console.log('All selected values: ', e)}
onSelect={e => console.log('Current item: ', e)}
style={style}
/>
);
};
此时 onChange 的返回值同样是包含选中节点的 JSON 结构。该转换在源码中由 convertJsonToData 实现:它递归遍历 JSON,使用 strings.JSON_KEY_SPLIT('_SEMI_TREE_SPLIT_',见 constants.ts)拼接路径生成唯一 key,并将标量值写入 value 字段。
行显示与节点渲染定制
blockNode:整行高亮
blockNode 决定节点是否以整行显示:开启(默认 true)时悬浮与选中高亮作用于整行;关闭时仅高亮节点 label。常用于紧凑型目录或需内嵌操作的场景:
<Tree treeData={treeData} defaultValue="Shanghai" blockNode={false} />
<Tree treeData={treeData} defaultValue="Shanghai" multiple blockNode={false} />
自定义节点内容:label ReactNode 与 renderLabel
TreeNodeData.label 支持传入任意 ReactNode 做富内容渲染,例如在节点行内嵌按钮组、状态标签等。需要注意:默认搜索是按 label 的值匹配的,当 label 是 ReactNode 时,应传入自定义的 filterTreeNode 函数以满足搜索需求。
在 v>=1.6.0 中,还可用 renderLabel 传入自定义渲染方法,此时搜索仍基于 treeData 中对应的 label 原始值,非常适合实现"文本过长省略"等效果:
const renderLabel = (label, item) => (
<div style={{ display: 'flex' }}>
<Typography.Text ellipsis={{ showTooltip: true }} style={{ width: 'calc(100% - 48px)' }}>
{label}
</Typography.Text>
<Button icon={<IconMore />} size="small" onClick={e => { Toast.info({ content: item.key }); e.stopPropagation(); }} />
</div>
);
<Tree treeData={treeDataWithNode} renderLabel={renderLabel} style={treeStyle} />
renderLabel 的签名(v2.65.0 起新增 searchWord 参数):
(label: ReactNode, data: TreeNodeData, searchWord: string) => ReactNode
自定义图标:icon
通过 TreeNodeData.icon 可为单个节点设置自定义图标,例如:
import { IconMapPin } from '@douyinfe/semi-icons';
const treeData = [
{
label: 'Asia',
value: 'Asia',
key: '0',
icon: <IconMapPin style={{ color: 'var(--semi-color-text-2)' }} />,
children: [
{ label: 'China', value: 'China', key: '0-0', icon: <IconMapPin style={{ color: 'var(--semi-color-text-2)' }} /> },
{ label: 'Japan', value: 'Japan', key: '0-1', icon: <IconMapPin style={{ color: 'var(--semi-color-text-2)' }} /> },
],
},
];
icon 属性同样支持函数形式 (props: TreeNodeProps) => ReactNode。
目录树模式:directory
设置 directory 将 Tree 渲染为目录树样式:自带文件夹/文件图标(展开态与收起态图标自动切换),也可以被自定义 icon 覆盖。适合文件管理器、文档大纲等场景:
<Tree treeData={treeData} directory style={style} />
自定义展开图标与连线
expandIcon(v2.75.0 起):自定义展开/收起图标,接受 ReactNode 或函数。函数形式接收{ onClick, className, expanded },可用IconPlus/IconMinus等替换默认的箭头:
const expandIconFunc = useCallback((props) => {
const { expanded, onClick, className } = props;
return expanded
? <IconMinus size="small" className={className} onClick={onClick} />
: <IconPlus size="small" className={className} onClick={onClick} />;
});
<Tree expandIcon={<IconChevronDown size="small" className="testCls" />} treeData={treeData} />
类型定义为:
expandIcon: ReactNode | ((props: {
onClick: (e: MouseEvent) => void;
className: string;
expanded: boolean;
}))
showLine(v2.50.0 起,默认false):节点之间显示层级连线,营造类资源管理器的视觉层级:
<Tree showLine defaultExpandAll treeData={treeData} style={style} />
展开与收缩控制
defaultExpandAll 与 expandAll 的区别
两者都能设置默认展开状态,但生效时机不同:
| 属性 | 生效时机 | 数据动态更新时 |
|---|---|---|
defaultExpandAll |
仅初始化时 | 失效(不随新数据重新展开) |
expandAll(v1.30.0 起) |
初始化时 | 持续生效(treeData/treeDataSimpleJson 更新后仍全部展开) |
在源码 index.tsx 的 getDerivedStateFromProps 中可以看到关键分支:(!prevProps && (props.defaultExpandAll || props.expandAll)) || expandAllWhenDataChange 时,会将全部 key 加入 expandedKeys;其中 expandAllWhenDataChange = dataUpdated && props.expandAll,即只有 expandAll 会在数据更新后再次全量展开。典型应用是"点击按钮动态更换数据源后,树依然保持全展开"。
受控展开:expandedKeys + onExpand
传入 expandedKeys 后,Tree 的展开完全由外部控制,配合 onExpand 更新。注意:受控展开时如果开启了搜索,节点不会因搜索自动展开,展开行为完全由 expandedKeys 决定。此时可利用 onSearch 回调的 filteredExpandedKeys 参数(v2.38.0 起)实现"搜索即展开命中节点":
const [expandedKeys, setExpandedKeys] = useState([]);
<Tree
treeData={treeData}
filterTreeNode
expandedKeys={expandedKeys}
onExpand={expandedKeys => setExpandedKeys(expandedKeys)}
onSearch={(inputValue, filteredExpandedKeys) => {
setExpandedKeys([...filteredExpandedKeys]);
}}
/>;
filteredExpandedKeys 表示因搜索(或因 value/defaultValue)而需要展开的节点 key 集合,是受控展开下实现搜索联动展开的标准方案。
autoExpandParent:受控展开下的父节点策略
在受控展开场景下,autoExpandParent 控制展开子节点时是否自动展开其所有父节点。开启后,若想收起父节点,必须先收起其全部子节点(否则父节点会被自动拉回展开态)。默认 false,即父节点的收起不受子节点影响:
<Tree
autoExpandParent
treeData={treeData}
onExpand={v => this.onExpand(v)}
expandedKeys={this.state.expandedKeys}
style={style}
/>
高级交互能力
禁用与严格禁用
disabled:禁用整棵树的选中能力(v0.32.0 起)。TreeNodeData.disabled:禁用单个节点。disableStrictly(v1.4.0 起):开启严格禁用。开启后,被禁用节点的选中状态不会因父级/子级的联动关系而改变,避免"父节点全选时把禁用子项也带上"这类问题:
<Tree
treeData={treeData} // 其中 Beijing / Shanghai 节点 disabled: true
defaultValue="Shanghai"
multiple
disableStrictly
style={style}
/>
从源码结构看,严格禁用依赖 calcDisabledKeys 收集禁用节点集合(见 index.tsx 导入的 treeUtil.ts),在勾选联动计算时排除这些 key。
节点选中关系:checkRelation
v2.5.0 起,多选时可通过 checkRelation 设置节点选中关系的类型:
'related'(默认):父子节点勾选相互联动,父项全选子项时父项自动勾选,符合常规级联选择预期;'unRelated':节点之间勾选互不影响,各自独立,适合"独立权限点"或"标签自由组合"类场景。
<Tree
treeData={treeData}
multiple
checkRelation="unRelated"
defaultExpandAll
style={style}
/>
异步加载数据:loadData
通过 loadData 可在节点展开时异步加载子节点,返回值须为 Promise。关键约定:数据中需要用 isLeaf: true 标记叶子节点,否则所有节点都会被渲染出展开箭头并触发加载。配合 loadedKeys(受控标记已加载节点)与 onLoad(加载完成回调)可精细控制加载状态:
const initialData = [
{ label: 'Expand to load', value: '0', key: '0' },
{ label: 'Expand to load', value: '1', key: '1' },
{ label: 'Leaf Node', value: '2', key: '2', isLeaf: true },
];
function updateTreeData(list, key, children) {
return list.map(node => {
if (node.key === key) return { ...node, children };
if (node.children) return { ...node, children: updateTreeData(node.children, key, children) };
return node;
});
}
function onLoadData({ key, children }) {
return new Promise(resolve => {
if (children) { resolve(); return; }
setTimeout(() => {
setTreeData(origin => updateTreeData(origin, key, [
{ label: 'Child Node', key: `${key}-0` },
{ label: 'Child Node', key: `${key}-1` },
]));
resolve();
}, 1000);
});
}
return <Tree loadData={onLoadData} treeData={[...treeData]} />;
拖拽排序:draggable + onDrop
设置 draggable(v1.8.0 起)并配合 onDrop 即可实现节点拖拽重组。注意:拖拽与虚拟化(virtualize)目前不能同时使用。
拖拽事件回调签名如下:
- onDragEnd: function({ event, node: DragTreeNode })
- onDragEnter:function({ event, node: DragTreeNode, expandedKeys: string[] })
- onDragLeave:function({ event, node: DragTreeNode })
- onDragOver:function({ event, node: DragTreeNode })
- onDragStart:function({ event, node: DragTreeNode })
- onDrop: function({ event, node, dragNode, dragNodesKeys, dropPosition, dropToGap })
其中 DragTreeNode 在 TreeNodeData 基础上增加了 expanded(是否展开)与 pos(节点在整棵树中的位置字符串,如 '0-1-2-0' 表示第 0 层第 1 个节点的第 2 个子节点的第 0 个子节点)两个字段:
DragTreeNode {
expanded: boolean;
pos: string;
value?: string | number;
label?: React.ReactNode;
disabled?: boolean;
isLeaf?: boolean;
[key: string]: any;
}
onDrop 中的判定关键:
dropPosition:拖拽节点在当前层级落点的相对位置。插入到同层第 0 个节点之前为-1,之后为1,落在节点自身上为0,依此类推;dropToGap:是否落在节点之间的空隙。false表示落在某个节点之上(作为其子节点插入)。
一个完整的 onDrop 实现会先按 dragKey 从数据中摘除拖拽节点,再依据 dropToGap 与 dropPosition 决定插入为子节点、插入到同级顶部还是同级底部:
function onDrop(info) {
const { dropToGap, node, dragNode } = info;
const dropKey = node.key;
const dragKey = dragNode.key;
const dropPos = node.pos.split('-');
const dropPosition = info.dropPosition - Number(dropPos[dropPos.length - 1]);
const data = [...treeData];
const loop = (data, key, callback) => {
data.forEach((item, ind, arr) => {
if (item.key === key) return callback(item, ind, arr);
if (item.children) return loop(item.children, key, callback);
});
};
let dragObj;
loop(data, dragKey, (item, ind, arr) => { arr.splice(ind, 1); dragObj = item; });
if (!dropToGap) {
// 作为子节点插入
loop(data, dropKey, item => { item.children = item.children || []; item.children.push(dragObj); });
} else if (dropPosition === 1 && node.children && node.expanded) {
// 落在展开节点的底部空隙,插入为其子节点首位
loop(data, dropKey, item => { item.children = item.children || []; item.children.unshift(dragObj); });
} else {
let dropNodeInd, dropNodePosArr;
loop(data, dropKey, (item, ind, arr) => { dropNodePosArr = arr; dropNodeInd = ind; });
if (dropPosition === -1) dropNodePosArr.splice(dropNodeInd, 0, dragObj); // 插入同级顶部
else dropNodePosArr.splice(dropNodeInd + 1, 0, dragObj); // 插入同级底部
}
setTreeData(data);
}
return <Tree treeData={treeData} draggable onDrop={onDrop} />;
拖拽相关的辅助能力还包括:autoExpandWhenDragEnter(拖入节点时自动展开,默认 true)、hideDraggingNode(隐藏拖拽中的节点镜像)、renderDraggingNode(自定义拖拽镜像元素)、onDragStart/onDragEnter/onDragOver/onDragLeave/onDragEnd 完整事件链。
虚拟化长列表:virtualize
渲染海量树节点时开启虚拟化,仅渲染可视区域内的行。virtualize 是一个配置对象:
height:树高度。传数字或字符串,若传字符串,计算出的高度不能为 0(父节点需有 offsetHeight),默认'100%';width:树宽度,默认'100%';itemSize:必填,每行树节点的高度(px)。
虚拟化模式下为性能考虑会禁用展开/收起动画。若同时开启搜索,建议设置 showFilteredOnly={true} 进一步降低渲染量:
<Tree
treeData={this.state.gData} // 数千到数万个节点
filterTreeNode
showFilteredOnly
virtualize={{ height: 300, itemSize: 28 }}
/>
虚拟化模式下还可通过 ref 调用 scrollTo(v2.18.0 起)将指定已展开节点滚动到可视区:
scrollTo: ({ key: string; align?: 'center' | 'start' | 'end' | 'smart' | 'auto' }) => void
完全自定义渲染:renderFullLabel
v1.7.0 起,renderFullLabel 允许你完全接管整行节点的渲染,适用于"父节点仅作为分组、只允许选中叶子节点""选中父节点同时高亮全部子节点"等高度定制场景。其参数类型如下:
type RenderFullLabelProps = {
data: BasicTreeNodeData; // 行原始数据
level: number; // 层级,可用于自定义缩进
style: any; // 虚拟化所需样式,使用虚拟化时务必挂载到 DOM 上
className: string; // 内置样式类(缩进、展开按钮、过滤、禁用、选中等)
expandIcon: any; // 展开按钮图标
checkStatus: { // 选中状态
checked: boolean; // 多选下是否选中
halfChecked: boolean; // 多选下是否半选
};
expandStatus: { // 展开状态
expanded: boolean; // 是否已展开
loading: boolean; // 是否正在加载
};
filtered: boolean | undefined; // 节点是否满足搜索条件
searchWord: string | undefined; // 当前搜索框输入
onClick: (e: MouseEvent) => void; // 整行点击回调(控制展开与选中)
onCheck: (e: MouseEvent) => void; // 多选点击回调
onContextMenu: (e: MouseEvent) => void; // 右键回调
onDoubleClick: (e: MouseEvent) => void; // 双击回调
onExpand: (e: MouseEvent) => void; // 展开回调
}
重要约束:若开启了虚拟化,必须将参数中的 style 应用到目标 ReactNode 上,否则虚拟列表渲染会错位。另外,renderFullLabel 只负责 UI 渲染,不改变内部数据逻辑,可结合受控模式实现更复杂的数据行为。
典型场景一:父节点仅作为分组展示,只允许叶子节点被勾选(配合 leafOnly):
const renderLabel = ({ onClick, onContextMenu, onDoubleClick, className, onExpand, data, onCheck, checkStatus, expandIcon }) => {
const { label } = data;
const isLeaf = !(data.children && data.children.length);
return (
<li
className={className}
role="treeitem"
onClick={isLeaf ? onCheck : onExpand}
onContextMenu={onContextMenu}
onDoubleClick={onDoubleClick}
>
{isLeaf ? null : expandIcon}
{isLeaf ? (
<div onClick={onCheck} role="checkbox" tabIndex={0} aria-checked={checkStatus.checked}>
<Checkbox indeterminate={checkStatus.halfChecked} checked={checkStatus.checked} style={{ marginRight: 8 }} />
</div>
) : null}
<span>{label}</span>
</li>
);
};
<Tree treeData={treeData} renderFullLabel={renderLabel} multiple leafOnly style={treeStyle} />;
典型场景二:仅叶子节点可单选,父节点只负责展开分组:
const renderLabel = ({ className, onExpand, onClick, data, expandIcon }) => {
const { label } = data;
const isLeaf = !(data.children && data.children.length);
return (
<li className={className} role="treeitem" onClick={isLeaf ? onClick : onExpand}>
{expandIcon}
<span>{label}</span>
</li>
);
};
<Tree treeData={treeData} renderFullLabel={renderLabel} style={treeStyle} />;
典型场景三:选中父节点时,同时高亮其全部后代节点(通过 onSelect 计算后代 key 集合,再在渲染时做背景色分级)。
另外,v1.27.0 起 renderFullLabel 与 draggable 可以同时使用,实现"自定义渲染 + 拖拽重组"的组合能力。
数据动态更新
Tree 的数据是响应式的:直接替换 treeData 引用即可更新树。在源码的 getDerivedStateFromProps 中,组件会比较新旧 treeData 的结构(仅比较 key/value/children,避免 label 为 ReactNode 时因引用变化造成误判导致用户展开状态被重置),并重建 keyEntities 实体索引与 valueEntities 值索引(详见 convertDataToEntities)。配合 expandAll 使用,可保证数据更新后依然全量展开。
API 参考(Tree)
以下为 content/navigation/tree/index-en-US.md 中的完整属性表(含引入版本):
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| autoExpandParent | 是否自动展开父节点 | boolean | false | 0.34.0 |
| autoExpandWhenDragEnter | 拖入节点时是否自动展开 | boolean | true | 1.8.0 |
| autoMergeValue | 自动合并值:开启后选中父节点时,value 不包含其所有后代节点(在 leafOnly 为 false 时生效) | boolean | true | 2.61.0 |
| blockNode | 是否整行显示节点 | boolean | true | - |
| checkRelation | 多选时节点勾选状态的关系:'related'、'unRelated' |
string | 'related' |
2.5.0 |
| className | 类名 | string | - | - |
| defaultExpandAll | 初始化时是否展开全部节点;后续数据变化时此 API 不再生效(可改用 expandAll) | boolean | false | - |
| defaultExpandedKeys | 默认展开节点的 key 数组 | string[] | - | - |
| defaultValue | 默认值 | string | number | TreeNodeData | (string | number | TreeNodeData)[] | - | - |
| directory | 是否以目录模式显示 | boolean | false | - |
| disableStrictly | 严格禁用:禁用节点的状态不受父/子节点影响 | boolean | false | 1.4.0 |
| disabled | 禁用整棵树不可选 | boolean | false | 0.32.0 |
| draggable | 是否允许拖拽 | boolean | false | 1.8.0 |
| emptyContent | 无数据时的空内容 | ReactNode | no result |
0.32.0 |
| expandAction | 展开触发方式:false、'click'、'doubleClick',默认 false(仅点击展开图标) |
boolean | string | false | 0.35.0 |
| expandAll | 默认展开全部节点;数据动态更新后依然生效 | boolean | false | 1.30.0 |
| expandedKeys | (受控)展开节点的 key 数组 | string[] | - | - |
| expandIcon | 自定义展开图标 | ReactNode | (props: expandProps) => ReactNode | - | 2.75.0 |
| keyMaps | 自定义节点中 key/label/value 字段名。若自定义了 label 字段名并开启搜索,需同步设置 treeNodeFilterProp 或自定义 filterTreeNode | object | - | 2.47.0 |
| filterTreeNode | 是否可搜索,或传入函数自定义搜索行为(v2.28.0 起回调提供 data 参数) | boolean | ((inputValue: string, treeNodeString: string, data?: TreeNodeData) => boolean) | false | - |
| hideDraggingNode | 是否隐藏拖拽节点镜像 | boolean | false | 1.8.0 |
| icon | 图标 | ReactNode | (props: TreeNodeProps) => ReactNode | - | - |
| labelEllipsis | label 溢出时是否省略;有其他需求时设为 false | boolean | false | true(虚拟化) | 1.8.0 |
| leafOnly | 多选下仅叶子节点展示勾选并参与 onChange 回调 | boolean | false | 1.18.0 |
| loadData | 异步加载数据,返回值应为 Promise | (treeNode?: TreeNodeData) => Promise<void> | - | 1.0.0 |
| loadedKeys | (受控)标记节点为已加载,配合 loadData 使用 | string[] | - | 1.0.0 |
| motion | 是否开启动画 | boolean | true | - |
| multiple | 是否多选模式 | boolean | false | - |
| preventScroll | 是否阻止浏览器滚动以显示新聚焦元素(作用于组件内部 focus 方法,不含用户传入组件) | boolean | - | - |
| renderDraggingNode | 自定义拖拽节点的镜像元素 | (nodeInstance: HTMLElement, node: TreeNodeData) => HTMLElement | - | 1.8.0 |
| renderFullLabel | 自定义整行渲染函数 | (data: object) => ReactNode | - | 1.7.0 |
| renderLabel | 自定义 label 渲染函数(v2.65.0 起支持 searchWord 参数) | (label: ReactNode, data: TreeNodeData, searchWord: string) => ReactNode | - | 1.6.0 |
| searchClassName | 搜索框类名 | string | - | - |
| searchPlaceholder | 搜索框占位符 | string | - | - |
| searchRender | 自定义搜索框渲染;设为 false 隐藏搜索框(v1.0.0 起支持 false) | ((searchRenderProps: object) => ReactNode) | false | - | 0.35.0 |
| searchStyle | 搜索框样式 | CSSProperties | - | - |
| showClear | 是否支持清空输入框 | boolean | true | 0.35.0 |
| showFilteredOnly | 搜索模式下是否只展示过滤结果 | boolean | false | 0.32.0 |
| showLine | 节点之间显示连线 | boolean | false | 2.50.0 |
| style | 内联样式 | CSSProperties | - | - |
| treeData | 节点数据 | TreeNodeData[] | [] | - |
| treeDataSimpleJson | JSON 格式节点数据,返回值同样为 JSON | TreeDataSimpleJson | {} | - |
| treeNodeFilterProp | 用于搜索的节点属性名 | string | label |
- |
| value | 受控组件当前值 | string | number | TreeNodeData | (string | number | TreeNodeData)[] | - | - |
| virtualize | 高效渲染大列表,参考 VirtualizeObj;虚拟化时禁用动画 | VirtualizeObj | - | 0.32.0 |
| onChange | 节点选中变化回调,返回数据的 value 属性 | (string | number | TreeNodeData | (string | number | TreeNodeData)[]) => void | - | - |
| onChangeWithObject | 是否以对象形式返回完整选项({ value, label, ...rest });受控时 value 需传 { value } 结构,defaultValue 同理 | boolean | false | - |
| onDoubleClick | 双击回调 | (e: MouseEvent, node: TreeNodeData) => void | - | 0.35.0 |
| onDragEnd | 拖拽结束回调 | (dragProps: object) => void | - | 1.8.0 |
| onDragEnter | 拖入节点回调 | (dragEnterProps: object) => void | - | 1.8.0 |
| onDragLeave | 拖离节点回调 | (dragProps: object) => void | - | 1.8.0 |
| onDragOver | 拖拽经过回调 | (dragProps: object) => void | - | 1.8.0 |
| onDragStart | 拖拽开始回调 | (dragProps: object) => void | - | 1.8.0 |
| onDrop | 放下回调 | (onDragProps: object) => void | - | 1.8.0 |
| onExpand | 展开/收起回调 | (expandedKeys: string[], { expanded: boolean, node: TreeNodeData }) => void | - | - |
| onLoad | 节点加载完成回调 | (loadedKeys: Set<string>, treeNode: TreeNodeData) => void | - | 1.0.0 |
| onContextMenu | 右键点击回调 | (e: MouseEvent, node: TreeNodeData) => void | - | 0.35.0 |
| onSearch | 搜索值变化回调;filteredExpandedKeys 为因搜索或 value/defaultValue 而展开的节点 key,可用于受控 expandedKeys(v2.38.0 起支持该参数) |
function(input: string, filteredExpandedKeys: string[]) | - | - |
| onSelect | 选中回调,返回数据的 key 属性 | (selectedKey: string, selected: boolean, selectedNode: TreeNodeData) => void | - | - |
TreeNodeData
注意:
TreeNodeData的 key 必填且必须唯一,label可以重复。v1.7.0 之前value也必填且唯一;v1.7.0 之后value非必填,缺省时onChange、value、defaultValue、onChangeWithObject中的 value 将指向 key。请保持"是否使用 value"的一致性,以免行为异常。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 值 | string | number | - |
| label | 展示的标签 | string | ReactNode | - |
| icon | 图标 | ReactNode | - |
| disabled | 禁用 | boolean | false |
| key | 必填且唯一 | string | - |
| isLeaf | 是否为叶子节点,仅异步加载(loadData)时生效(v1.0.0 起) | boolean | - |
Virtualize Object
itemSize必填。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| height | 高度;传字符串时计算高度不能为 0,即父节点需有 offsetHeight | number | string | '100%' |
| itemSize | 每行树节点高度,必填 | number | - |
| width | 宽度 | number | string | '100%' |
Methods(通过 ref 调用)
| 名称 | 说明 | 类型 | 版本 |
|---|---|---|---|
| search | 手动触发搜索 | (value: string) => void | - |
| scrollTo | 虚拟化树中,将指定节点(须为已展开节点)滚动到可视区 | ({ key: string; align?: 'center' | 'start' | 'end' | 'smart' | 'auto' }) => void | 2.18.0 |
无障碍(Accessibility)
Tree 内置了对 WAI-ARIA 树形模式的支持:
- 支持传入
aria-label说明 Tree 的角色; - 为每个子节点自动设置
aria-disabled、aria-checked、aria-selected、aria-level以表达节点状态与层级; - 为对应部分设置
role="tree"与role="treeitem"。
<Tree
/* other attributes */
aria-label="example tree"
/>
内容撰写指南(Content Guidelines)
文档同时给出了树节点文案层面的规范建议,适用于任何用 Tree 呈现层级信息的业务:
- 尽量使用短语,并首字母大写(Try to use phrases, capitalize the first letter);
- 同一层级间保持术语形式一致,例如全部使用地名或全部使用国家名(Keep the same form of terminology between levels)。
源码级原理补充:数据管道与状态模型
Tree 的实现横跨两个包,理解其分层有助于排查复杂问题:
- UI 层 packages/semi-ui/tree:包含 index.tsx(组件主体,负责 props 派生状态
getDerivedStateFromProps、渲染与事件转发)、treeNode.tsx(单节点渲染)、nodeList.tsx(节点列表,配合 react-window 虚拟化)、treeUtil.tsx(克隆等辅助)等; - 逻辑层 packages/semi-foundation/tree:foundation.ts 持有全部状态机逻辑(勾选、展开、搜索、拖拽的 add/remove 计算),treeUtil.ts 提供纯函数数据变换(convertJsonToData 将 JSON 转为 treeData、convertDataToEntities 构建 key/value 双索引实体、filterTreeData 执行搜索过滤、
calcCheckedKeys系列维护勾选联动),constants.ts 定义 CSS 前缀与常量;样式位于 tree.scss。
这一分层遵循 Semi Design 的 Foundation 模式:UI 组件只做渲染与用户交互转发,所有状态变更都收敛到 foundation 的确定性函数中,这也解释了为何 treeData 结构变化(仅 key/value/children 变化)才会触发 expandedKeys 重算、而 label 引用变化不会破坏用户的展开状态——这是 index.tsx 中 isTreeDataStructureEqual 结构比较逻辑刻意设计的结果。
在测试与质量保障层面,仓库提供了覆盖搜索、过滤、异步加载、unRelated 勾选关系的端到端用例(见 cypress/e2e/tree.spec.js),以及 packages/semi-ui/tree/test 下的单测(tree.test.js、treeMultiple.test.js、treeNodeProps.test.js 等),可作为自定义行为验证时的参考。
最后,Tree 的视觉呈现完全由 Design Token 驱动(组件文档末尾的 DesignToken 区块),其主题变量定义于 packages/semi-theme-default/scss 中,可结合 Semi Design 的定制主题能力统一调整树形控件的间距、颜色与字体,实现与业务设计体系的无缝融合。