Semi Design Tree 树形控件完全指南:从基础用法到高级定制与源码原理

原创2026-09-23 14:59:101,751 阅读
文章标签:前端UI组件设计系统

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 的实现横跨两个包,理解其分层有助于排查复杂问题:

这一分层遵循 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 的定制主题能力统一调整树形控件的间距、颜色与字体,实现与业务设计体系的无缝融合。

登录后查看全文
semi-design