Semi Design TreeSelect 树选择器完全指南:从基础用法到源码级原理

原创2026-09-23 10:11:191,825 阅读
文章标签:前端UI组件设计系统

Semi Design TreeSelect 树选择器完全指南:从基础用法到源码级原理

导读

本文基于 Semi Design(@douyinfe/semi-ui)官方文档,系统讲解 TreeSelect 树选择器组件的完整用法:从最基本的数据结构定义、单选/多选、搜索(本地与远程)、标签折叠、节点选中关系,到虚拟化、异步加载、自定义 Trigger 等高级主题,并深入 TreeSelect 源码 与 Foundation 层实现,解释每个核心属性的底层行为。读完本文,你将能够独立应对"多层级树形数据的结构化展示与选取"这一典型场景——例如文件目录选择、组织架构成员挑选、级联分类筛选等。

一、组件定位与引入方式

TreeSelect 用于多层级树形数据的结构化展示与选取,典型场景包括:显示文件夹与文件的列表、组织架构成员列表、地区/类目级联选择等。它本质上是"Select + Tree"的融合体:外观看是下拉选择框,展开后是树形面板,支持单选与多选。

引入方式非常简单,从 @douyinfe/semi-ui 中解构即可:

import { TreeSelect } from '@douyinfe/semi-ui';

从源码看,TreeSelect 在 packages/semi-ui/treeSelect/index.tsx 中定义,其类名为 TreeSelect 并声明 static __SemiComponentName__ = "TreeSelect",内部通过 TreeSelectFoundation(位于 packages/semi-foundation/treeSelect/foundation.ts)承担全部业务逻辑,UI 层只负责渲染与事件绑定——这是 Semi 一贯的 "Foundation + Adapter" 架构。

核心数据模型:treeData 与 TreeNodeData

TreeSelect 使用 treeData 数组描述树结构,每个节点是一个 TreeNodeData 对象。官方文档对其字段的要求非常明确:

属性 说明 类型 默认值
key 必填且要求唯一,用于内部标识节点 string -
value 属性值(选中后对外暴露的值) string | number -
label 展示的文本 string | ReactNode -
icon 自定义图标 ReactNode -
disabled 是否禁用(多选状态下支持) boolean false
isLeaf 是否为叶子节点(异步加载时用于判断是否还需加载) boolean -

关键约束:不同 TreeNodeData 的 key 值必填且唯一;label 允许重复;value 值非必填——此时 onChange、value、defaultValue 及 onChangeWithObject 中所取的 value 属性值将改为 key 值。为了保证行为符合预期,treeData 中的 value 值要么全部填写、要么全部不填且唯一,不建议混写。

这一约束在源码中有直接对应:组件内部通过 convertDataToEntities 将 treeData 转为 keyEntities(以 key 为键的实体映射)与 valueEntities(value 到 key 的映射),后续的选中、展开、过滤全部基于这套映射进行。

二、基础用法:从单选开始

最简单的用法为默认的单选模式,每一级菜单项均可选择。核心是构造 treeData 并传入:

import React from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';
() => {
    const treeData = [
        {
            label: '亚洲',
            value: 'Asia',
            key: '0',
            children: [
                {
                    label: '中国',
                    value: 'China',
                    key: '0-0',
                    children: [
                        { label: '北京', value: 'Beijing', key: '0-0-0' },
                        { label: '上海', value: 'Shanghai', key: '0-0-1' },
                    ],
                },
            ],
        },
        {
            label: '北美洲',
            value: 'North America',
            key: '1',
        }
    ];
    return (
        <TreeSelect
            style={{ width: 300 }}
            dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
            treeData={treeData}
            placeholder="请选择"
        />
    );
};

几个要点:

  • style={{ width: 300 }} 控制选择框宽度;dropdownStyle={{ maxHeight: 400, overflow: 'auto' }} 控制下拉面板高度与滚动。
  • 单选模式下,点击叶子节点后默认自动收起面板(clickToHide 默认为 true)。从 handleSingleSelect 可以看到:非多选时选中后若满足 clickToHide 且"无展开动作或该节点无子级",就会 close(e) 并触发 blur。
  • 下拉面板宽度默认与选择框对齐(dropdownMatchSelectWidth 默认 true),宽度计算逻辑见 foundation._setDropdownWidth:优先取 style.width(数字或非百分比字符串),否则回退到 Trigger 实测宽度。

三、多选模式:multiple 与 leafOnly

设置 multiple 即可多选。多选场景下有两个关键行为:

  1. 父子联动:所有子项都被选择时,自动勾选并显示其父项(半选态由 halfCheckedKeys 维护)。
  2. 只选叶子(leafOnly):通过 leafOnly 属性,可以设置只展示叶子节点,同时 onChange 的回调入参也只会包含叶子节点的值。
import React from 'react';
import { TreeSelect } 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: 'Chengdu', value: 'Chengdu', key: '0-0-2' },
                    ],
                },
                {
                    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' },
            ],
        }
    ];
    return (
        <div>
            <TreeSelect
                style={{ width: 300 }}
                multiple
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                placeholder="请选择"
            />
            <br/>
            <br/>
            <TreeSelect
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                multiple
                leafOnly
                placeholder="只渲染叶子节点"
            />
            <br/>
            <br/>
        </div>
    );
};

从实现层面看,多选时组件同时维护 checkedKeys(完整勾选集)、halfCheckedKeys(半选集)与 realCheckedKeys(真实勾选集)。在 handleMultipleSelect 中:

  • checkRelation='related'(默认)时走父子联动逻辑,通过 calcCheckedKeysForChecked / calcCheckedKeysForUnchecked 计算级联勾选;
  • leafOnly 生效时,normalizeKeyList 会剥离非叶子节点,保证 onChange 只回传叶子 key。

限制标签展示数量:maxTagCount 与 showRestTagsPopover

在多选场景中,利用 maxTagCount 可以限制展示的标签数量,超出部分以 +N 方式展示。showRestTagsPopover(>= v2.22.0)可设置在超出 maxTagCount 后,hover +N 时是否显示 Popover 展示剩余内容,默认为 false;并可通过 restTagsPopoverProps 配置该 Popover(例如调整弹出位置)。

import React from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';
() => {
    // treeData 与上文多选示例一致(Asia/China/Japan/North America 结构)
    const treeData = [ /* ... */ ];
    return (
        <div>
            <h4 style={{ margin: '20px 0 10px' }}>maxTagCount=2:</h4>
            <TreeSelect
                multiple
                maxTagCount={2}
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                placeholder="当选中标签超过两个将折叠"
                defaultValue={['Beijing', 'Chengdu', 'Canada']}
            />
            <h4 style={{ margin: '20px 0 10px' }}>maxTagCount=2, showRestTagsPopover:</h4>
            <TreeSelect
                showRestTagsPopover={true}
                restTagsPopoverProps={{ position: 'top' }}
                multiple
                maxTagCount={2}
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                placeholder="hover +N 查看"
                defaultValue={['Beijing', 'Chengdu', 'Canada']}
            />
        </div>
    );
};

相关属性一览(含默认值与引入版本):

属性 说明 类型 默认值
maxTagCount 最多显示多少个 tag number -
showRestTagsPopover 超过 maxTagCount 后,hover +N 是否通过 Popover 显示剩余内容(v2.22.0+) boolean false
restTagsPopoverProps Popover 配置属性(position、zIndex、trigger 等,参考 Popover API)(v2.22.0+) PopoverProps {}

四、搜索能力:本地过滤与远程搜索

4.1 可搜索的(filterTreeNode)

通过设置 filterTreeNode 属性可支持搜索功能。默认对 label 值进行搜索,可通过 treeNodeFilterProp 更改搜索字段。如果只希望展示过滤后的结果(而非同时保留匹配节点的祖先路径),可以设置 showFilteredOnly。若想获取搜索结果的详细信息,可使用 onSearch 回调。

filterTreeNode 的类型为 boolean | (inputValue: string, treeNodeString: string, data?: TreeNodeData) => boolean(data 参数自 v2.28.0 开始提供)。当传入函数时,即为自定义过滤函数。

import React, { useState } from 'react';
import { TreeSelect, Switch } from '@douyinfe/semi-ui';
() => {
    const [showFilteredOnly, setShowFilteredOnly] = useState(false);
    const treeData = [ /* Asia/China/Japan/North America 结构 */ ];

    function onSearch(inputValue, filteredExpandedKeys, filteredNodes) {
        console.log('onSearch', inputValue, filteredExpandedKeys, filteredNodes);
    }

    return (
        <>
            <span>showFilteredOnly</span>
            <Switch checked={showFilteredOnly} onChange={setShowFilteredOnly} size="small" />
            <br/><br/>
            <TreeSelect
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                filterTreeNode
                showFilteredOnly={showFilteredOnly}
                placeholder="单选可搜索的"
                onSearch={onSearch}
            />
            <br/><br/>
            <TreeSelect
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                multiple
                filterTreeNode
                maxTagCount={2}
                showFilteredOnly={showFilteredOnly}
                placeholder="多选可搜索的"
                searchPlaceholder="请输入关键字开始搜索"
                onSearch={onSearch}
            />
            <br/><br/>
            <TreeSelect
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                multiple
                filterTreeNode
                maxTagCount={2}
                showFilteredOnly={showFilteredOnly}
                placeholder="搜索框autofocus"
                searchPlaceholder="autofocus"
                searchAutoFocus
                onSearch={onSearch}
            />
        </>
    );
};

底层过滤逻辑位于 foundation.handleInputChange:遍历 keyEntities 中每个节点,调用 filter(sugInput, data, filterTreeNode, realFilterProp) 判断是否命中;随后计算 filteredKeys(命中集合)、filteredExpandedKeys(命中节点的祖先 key 集合)与 filteredShownKeys(命中节点的后代),并据此重建扁平化节点列表。onSearch 的三个入参即来源于此:inputValue、filteredExpandedKeys、filteredNodes(命中节点数组)。

4.2 远程搜索(remote)

通过设置 remote 属性可启用远程搜索。开启后,输入时不会执行本地过滤,而是仅触发 onSearch 回调,由用户自行处理远程数据获取并更新 treeData。这一分支在源码中清晰可见:foundation.handleInputChange 在 remote 为 true 时直接 notifySearch(sugInput, <a href="https://link.gitcode.com/i/d95285a030805758012429f5f336a9f8" target="_blank">], []) 并 rePositionDropdown() 后返回;同时在 [index.tsx 的 getDerivedStateFromProps 中通过 isSearching = Boolean(props.filterTreeNode && !props.remote && ...) 判断,确保远程模式下跳过本地过滤。

import React, { useState, useCallback } from 'react';
import { TreeSelect, Toast } from '@douyinfe/semi-ui';

() => {
    const [value, setValue] = useState();
    const [treeData, setTreeData] = useState([]);
    const [loading, setLoading] = useState(false);

    // 模拟远程搜索
    const handleSearch = useCallback((inputValue) => {
        if (!inputValue) {
            setTreeData([]);
            return;
        }
        setLoading(true);
        // 模拟网络请求
        setTimeout(() => {
            const mockData = [
                { label: `${inputValue} - 结果1`, value: `${inputValue}-1`, key: `${inputValue}-1` },
                { label: `${inputValue} - 结果2`, value: `${inputValue}-2`, key: `${inputValue}-2` },
                { label: `${inputValue} - 结果3`, value: `${inputValue}-3`, key: `${inputValue}-3` },
            ];
            setTreeData(mockData);
            setLoading(false);
        }, 500);
    }, []);

    return (
        <TreeSelect
            style={{ width: 300 }}
            placeholder="请输入关键字进行远程搜索"
            treeData={treeData}
            filterTreeNode
            remote
            loading={loading}
            value={value}
            onChange={setValue}
            onSearch={handleSearch}
        />
    );
};

4.3 搜索框位置(searchPosition)

searchPosition 可设置搜索框的位置,可选:dropdown(默认)、trigger。当输入框位于 trigger 时:

  1. 搜索框占位符由 placeholder 控制;
  2. showClear=true 时,点击输入框的清空按钮,将同时清空 inputValue 和 value(逻辑见 foundation.handleClear)。
import React from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';

() => {
    const treeData = [ /* ... */ ];
    return (
        <>
            <TreeSelect
                searchPosition="trigger"
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                filterTreeNode
                placeholder="单选"
            />
            <br /><br />
            <TreeSelect
                searchPosition="trigger"
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                multiple
                filterTreeNode
                maxTagCount={2}
                placeholder="多选"
            />
        </>
    );
};

4.4 Trigger 内多行换行(triggerTagWrap)

当你在多选 + 搜索框位于 trigger 的场景下,选择了较多项或输入较长文本时,默认 trigger 可能倾向于保持单行展示。通过设置 triggerTagWrap={true},可以让 trigger 内的已选标签支持自动换行(多行展示)。该属性仅在 multiple 且 filterTreeNode 开启、并且 searchPosition="trigger" 时生效(默认 false,其声明见 index.tsx TreeSelectProps)。

import React from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';

() => {
    const treeData = [ /* Asia(China/Beijing/Shanghai/Shenzhen/Guangzhou、Japan/Osaka)、North America(United States/Canada) 结构 */ ];
    return (
        <TreeSelect
            searchPosition="trigger"
            triggerTagWrap
            style={{ width: 260 }}
            dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
            treeData={treeData}
            multiple
            filterTreeNode
            placeholder="请选择多个选项或输入长文本"
            defaultValue={['Beijing', 'Shanghai', 'Shenzhen', 'Guangzhou']}
        />
    );
};

五、尺寸与禁用控制

5.1 尺寸大小(size)

size 可选 'small'、'default'、'large',默认 'default'(与 constants.ts 中的 SIZE_SET 及 defaultProps 保持一致):

<div>
    <TreeSelect size="small" multiple treeData={treeData} placeholder="small" />
    <br /><br />
    <TreeSelect size="default" multiple treeData={treeData} placeholder="default" />
    <br /><br />
    <TreeSelect size="large" multiple treeData={treeData} placeholder="large" />
</div>

5.2 禁用(disabled)

设置 disabled 可整体禁用组件,无论是单选、带默认值的单选还是多选,均呈现禁用态且不可交互:

<div>
    <TreeSelect disabled treeData={treeData} placeholder="禁用下拉菜单" />
    <br /><br />
    <TreeSelect disabled defaultValue={'Shanghai'} treeData={treeData} />
    <br /><br />
    <TreeSelect disabled multiple defaultValue={['Shanghai', 'North America']} treeData={treeData} />
</div>

5.3 严格禁用(disableStrictly)

disableStrictly 用于开启严格禁用。开启后,当节点是 disabled 时,不能通过子级或父级的关系改变其选中状态。以下面 demo 为例,节点"中国"开启了严格禁用,因此改变其父节点"亚洲"的选中状态时,不会影响到节点"中国"的选中状态。

import React from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';

() => {
    const treeData = [
        {
            label: '亚洲', value: 'Asia', key: '0',
            children: [
                {
                    label: '中国', value: 'China', key: '0-0', disabled: true,
                    children: [
                        { label: '北京', value: 'Beijing', key: '0-0-0' },
                        { label: '上海', value: 'Shanghai', key: '0-0-1' },
                    ],
                },
                { label: '日本', value: 'Japan', key: '0-1' },
            ],
        },
        { label: '北美洲', value: 'North America', key: '1' }
    ];
    return (
        <TreeSelect
            style={{ width: 300 }}
            dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
            treeData={treeData}
            disableStrictly
            multiple
            defaultValue={['Shanghai']}
        />
    );
};

实现层面,组件在 getTreeNodeProps 中当 disableStrictly 且节点在 disabledKeys 中时强制注入 disabled: true;多选级联计算时走 calcNonDisabledCheckedKeys 与 calcCheckedStatus,只把"非禁用"的后代纳入勾选传播,从而实现"严格禁用不受父子影响"。

六、受控用法

6.1 值受控(value + onChange)

传入 value 时即为受控组件,配合 onChange 使用:

import React, { useState } from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';
() => {
    const [value, setValue] = useState('Shanghai');
    const treeData = [ /* Asia(中国/北京/上海)、北美洲 结构 */ ];
    return (
        <TreeSelect
            style={{ width: 300 }}
            dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
            treeData={treeData}
            value={value}
            placeholder="请选择"
            onChange={setValue}
        />
    );
};

6.2 展开受控(expandedKeys + onExpand)

传入 expandedKeys 时即为展开受控组件,配合 onExpand 使用。当展开受控时,如果开启 filterTreeNode 并进行搜索,节点不会再自动展开——展开完全由 expandedKeys 控制。此时可利用 onSearch 的入参 filteredExpandedKeys(>= v2.6.0)实现"搜索即展开"的效果:

import React, { useState } from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';

() => {
    const [expandedKeys, setExpandedKeys] = useState([]);
    const treeData = [ /* 亚洲/中国/北京/上海、日本、北美洲 结构 */ ];
    return (
        <TreeSelect
            style={{ width: 300 }}
            dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
            treeData={treeData}
            filterTreeNode
            expandedKeys={expandedKeys}
            onExpand={expandedKeys => {
                setExpandedKeys(expandedKeys);
            }}
            onSearch={(inputValue, filteredExpandedKeys, filteredNodes) => {
                setExpandedKeys([...filteredExpandedKeys, ...expandedKeys]);
            }}
        />
    );
};

6.3 节点选中关系(checkRelation)

多选时,使用 checkRelation 设置节点之间选中关系的类型,可选:'related'(默认)、'unRelated'(>= v2.5.0)。当选中关系为 'unRelated' 时,节点之间的选中互不影响(每个节点独立勾选,父级不联动子级、子级也不反哺父级):

import React from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';
() => {
    const treeData = [ /* 亚洲/中国/北京/上海、北美洲 结构 */ ];
    return (
        <TreeSelect
            multiple
            defaultValue="Asia"
            checkRelation="unRelated"
            style={{ width: 300 }}
            dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
            treeData={treeData}
        />
    );
};

从源码 getTreeNodeProps 可看到两种关系的状态来源差异:related 时节点的 checked/halfChecked 取自 checkedKeys/halfCheckedKeys;unRelated 时取自独立的 realCheckedKeys,且无半选态。多选分支 handleMultipleSelect 也据此分别走"级联计算"或"独立增删"。

七、大数据量优化

7.1 默认展开 vs 展开所有(defaultExpandAll / expandAll)

defaultExpandAll 与 expandAll 均可在初始化时展开所有节点,二者区别在于:defaultExpandAll 只在初始化时生效;而 expandAll 不仅初始化时生效,当数据(treeData)发生动态更新时仍然生效。如下 demo 中,treeData 更新后 defaultExpandAll 失效,expandAll 仍然生效:

import React, { useEffect, useState } from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';
() => {
    const treeData = [ /* 亚洲/中国/北京/上海、北美洲 结构 */ ];
    const [data, setData] = useState([]);
    useEffect(() => {
        setTimeout(() => setData(treeData), 500);
    }, []);
    return (
        <>
            <TreeSelect style={{ width: 300, marginBottom: 20 }} expandAll treeData={data} placeholder="expandAll" />
            <TreeSelect style={{ width: 300 }} defaultExpandAll treeData={data} placeholder="defaultExpandAll" />
        </>
    );
};

源码中 getDerivedStateFromProps 的 expandAllWhenDataChange = needUpdateTreeData && props.expandAll 正是这一差异的实现:只要 expandAll 为 true 且 treeData 发生变化,就重新把全部 key 放入 expandedKeys。

7.2 虚拟化(virtualize)

虚拟化用于大量树节点的情况,开启后动画效果将被关闭。virtualize 是一个对象,包含以下值:

  • height:高度值;如果为 string,必须有可计算高度才能渲染出来(即父节点有 offsetHeight),建议传入数值;
  • width:宽度值,默认 100%;
  • itemSize:每行 treeNode 的高度,必传。

如果带搜索框,建议同时开启 showFilteredOnly 减少多余节点的渲染。下方 demo 演示了生成数千节点并进行虚拟化渲染:

import React, { useState } from 'react';
import { TreeSelect, Button } from '@douyinfe/semi-ui';
() => {
    const [gData, setGData] = useState([]);
    const [total, setTotal] = useState(0);

    function generateData(x = 5, y = 4, z = 3, data = []) {
        // x:每一级下的节点总数;y:每级节点里有 y 个节点存在子节点;z:树的 level 层级数(0 表示一级)
        function _loop(_level, _preKey, _tns) {
            const preKey = _preKey || '0';
            const tns = _tns || data;
            const children = [];
            for (let i = 0; i < x; i++) {
                const key = `${preKey}-${i}`;
                tns.push({ label: `${key}-标签`, key: `${key}-key`, value: `${key}-value` });
                if (i < y) {
                    children.push(key);
                }
            }
            if (_level < 0) {
                return tns;
            }
            const __level = _level - 1;
            children.forEach((key, index) => {
                tns[index].children = [];
                return _loop(__level, key, tns[index].children);
            });
            return null;
        }
        _loop(z);

        function calcTotal(x, y, z) {
            const rec = n => (n >= 0 ? x * y ** n-- + rec(n) : 0);
            return rec(z + 1);
        }
        return { gData: data, total: calcTotal(x, y, z) };
    }

    function onGen() {
        const { gData, total } = generateData();
        setGData(gData);
        setTotal(total);
    }

    return (
        <div style={{ padding: '0 20px' }}>
            <Button onClick={onGen}>生成数据: </Button>
            <span>共 {total} 个节点</span>
            <br/><br/>
            {gData.length ? (
                <TreeSelect
                    style={{ width: 300 }}
                    treeData={gData}
                    filterTreeNode
                    showFilteredOnly
                    placeholder="Please select"
                    dropdownStyle={{ overflow: 'hidden' }}
                    virtualize={{
                        itemSize: 28,
                        // dropdown height 300 减去搜索框高度与 padding 8*2;
                        // 或设置 dropdown 高度后,将填满剩余空间
                        height: 236
                    }}
                />
            ) : null}
        </div>
    );
};

八、动态与异步数据

8.1 动态更新数据

treeData 是受控式数据源,可以直接通过 setState 更新,组件会基于新数据重新构建 keyEntities 与扁平化节点(见 getDerivedStateFromProps 中 needUpdateTreeData 分支):

import React, { useState } from 'react';
import { TreeSelect, Button } from '@douyinfe/semi-ui';
() => {
    const [treeData, setTreeData] = useState([]);

    function add() {
        const itemLength = Math.floor(Math.random() * 5) + 1;
        const nextTreeData = new Array(itemLength).fill(0).map((v, i) => {
            const length = Math.floor(Math.random() * 3);
            const children = new Array(length).fill(0).map((cv, ci) => ({
                key: `${i}-${ci}`,
                label: `Leaf-${i}-${ci}`,
                value: `${i}-${ci}`
            }));
            return { key: `${i}`, label: `Item-${i}`, value: `${i}`, children };
        });
        setTreeData(nextTreeData);
    }

    return (
        <>
            <TreeSelect
                style={{ width: 300 }}
                dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
                treeData={treeData}
                placeholder="请选择"
            />
            <br/><br/>
            <Button onClick={add}>动态改变数据</Button>
        </>
    );
};

8.2 异步加载数据(loadData)

通过设置 loadData 可以动态加载数据,此时需要在数据中传入 isLeaf 标明叶子节点。loadData 接收当前展开的 treeNode,必须返回一个 Promise;加载完成后将子节点合并进 treeData:

import React, { useState } from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';

() => {
    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 },
    ];
    const [treeData, setTreeData] = useState(initialData);

    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 (
        <TreeSelect
            loadData={onLoadData}
            treeData={treeData}
            style={{ width: 300 }}
            placeholder="请选择"
        />
    );
};

异步加载的内部流程在 foundation.handleNodeLoad 中:未加载且未在加载中的节点,调用 loadData(data).then(...) 后把该 key 移入 loadedKeys(非受控时)并从 loadingKeys 移除,同时通过 notifyLoad 触发 onLoad 回调;受控模式下配合 loadedKeys 属性使用。

九、自定义渲染:Trigger 与已选项

9.1 自定义 Trigger(triggerRender)

如果默认触发器样式满足不了需求,可以用 triggerRender 自定义选择框的展示。其入参接口如下(TriggerRenderProps):

interface TriggerRenderProps {
    componentProps: TreeSelectProps; // 所有用户传给 TreeSelect 的 props
    disabled: boolean;               // 是否禁用 TreeSelect
    value: TreeNodeData[];           // 已选中的 node 的数据
    inputValue: string;              // 当前 input 框的输入值
    onClear: (e) => void;            // 用于清空值的函数
    placeholder: string;             // placeholder
    onRemove: (key) => void;         // 删除单个 item 时调用,入参为 item 的 key(v2.32.0+)
    onSearch: (inputValue) => void;  // 用于在 Input 框值更新时启动搜索;
                                     // 自定义 Trigger 的 Input 组件值更新时应调用该函数,
                                     // 同时需设置 filterTreeNode 非 false,searchPosition 为 'trigger'(v2.32.0+)
}

使用示例:在自定义 Trigger 中组合 TagInput 实现"标签输入 + 搜索"的触发器:

import React, { useState, useCallback, useMemo } from 'react';
import { TreeSelect, Button, Tag, TagInput } from '@douyinfe/semi-ui';

function Demo() {
    const treeData = useMemo(() => [
        {
            label: '亚洲', value: '亚洲', key: '0',
            children: [
                { label: '中国', value: '中国', key: '0-0',
                  children: [
                    { label: '北京', value: '北京', key: '0-0-0' },
                    { label: '上海', value: '上海', key: '0-0-1' },
                  ] },
            ],
        },
        { label: '北美洲', value: '北美洲', key: '1' },
    ], []);

    const onValueChange = useCallback((value) => {
        console.log('onChange', value);
    });

    const renderTrigger = useCallback((props) => {
        const { value, onSearch, onRemove, inputValue } = props;
        const tagInputValue = value.map(item => item.key);
        const renderTagInMultiple = (key) => {
            const label = value.find(item => item.key === key).label;
            const onCloseTag = (value, e, tagKey) => {
                onRemove(tagKey);
            };
            return <Tag style={{ marginLeft: 2 }} tagKey={key} key={key} onClose={onCloseTag} closable>{label}</Tag>;
        };
        return (
            <TagInput
                inputValue={inputValue}
                value={tagInputValue}
                onInputChange={onSearch}
                renderTagItem={renderTagInMultiple}
            />
        );
    }, []);

    return (
        <TreeSelect
            triggerRender={renderTrigger}
            filterTreeNode
            searchPosition="trigger"
            multiple
            treeData={treeData}
            placeholder="Custom Trigger"
            onChange={onValueChange}
            style={{ width: 300 }}
        />
    );
}

9.2 自定义渲染已选项(renderSelectedItem)

renderSelectedItem 可自定义选择框中已选项标签的渲染结构:

  • 单选时:renderSelectedItem(treeNode: TreeNodeData) => ReactNode;
  • 多选时:renderSelectedItem(treeNode: TreeNodeData, { index, onClose }) => { isRenderInTag: boolean, content: ReactNode }:
    • isRenderInTag 为 true 时,自动将 content 包裹在 Tag 中渲染(带背景色及关闭按钮);
    • isRenderInTag 为 false 时,直接渲染返回的 content。
import React, { useState, useCallback, useMemo } from 'react';
import { TreeSelect, Tag } from '@douyinfe/semi-ui';

function Demo() {
    const [value, setValue] = useState([]);
    const treeData = useMemo(() => [
        { label: '亚洲', value: 'Asia', key: '0',
          children: [
            { label: '中国', value: 'China', key: '0-0',
              children: [
                { label: '北京', value: 'Beijing', key: '0-0-0' },
                { label: '上海', value: 'Shanghai', key: '0-0-1' },
              ] },
          ] },
        { label: '北美洲', value: 'North America', key: '1' },
        { label: '南美洲', value: 'South America', key: '2' },
        { label: '南极洲', value: 'Antarctica', key: '3' },
    ], []);

    return (
        <>
            <h4>单选</h4>
            <TreeSelect
                style={{ width: 300 }}
                treeData={treeData}
                renderSelectedItem={item => item.label}
            />
            <h4>多选 + isRenderInTag=true</h4>
            <TreeSelect
                style={{ width: 300 }}
                treeData={treeData}
                multiple
                renderSelectedItem={(item, { index, onClose }) => ({ content: item.label, isRenderInTag: true })}
            />
            <h4>多选 + isRenderInTag=false</h4>
            <TreeSelect
                style={{ width: 300 }}
                treeData={treeData}
                multiple
                maxTagCount={2}
                renderSelectedItem={(item, { index, onClose }) => ({
                    content: (
                        <Tag key={index} color="white" closable onClose={onClose}>
                            {item.value}
                        </Tag>
                    ),
                    isRenderInTag: false
                })}
            />
        </>
    );
}

十、其他常用属性速查

以下属性在实际业务中高频使用,均来自官方 API 表并与源码 TreeSelectProps 及 defaultProps 一一对应:

属性 说明 类型 默认值
showClear 当值不为空时,trigger 是否展示清除按钮 boolean false
clearIcon 自定义清除按钮(v2.25.0+,showClear 为 true 时有效) ReactNode -
onClear 点击清除按钮时触发的回调(v2.52.0+) (e: Event) => void -
autoMergeValue 开启后,父节点被选中时 value 不含其子孙节点(leafOnly 为 false 时生效)(v2.61.0+) boolean true
onChangeWithObject 为 true 时 onChange 入参为节点对象,受控时 value 需为含 value 键的对象 boolean false
expandAction 展开逻辑:false / 'click' / 'doubleClick',false 表示仅点击展开按钮才展开 boolean | string false
expandIcon 自定义展开图标(v2.75.0+) ReactNode | (props) => ReactNode -
showLine 选项面板中选项显示连接线(v2.50.0+) boolean false
keyMaps 自定义节点中 key、label、value 字段名(v2.47.0+) object -
emptyContent 搜索无结果时的展示内容 ReactNode 暂无数据
position 下拉菜单位置,可选值参考 Tooltip position(v2.25.0+) string bottomLeft
zIndex 下拉菜单 zIndex number 1030
prefix / suffix 前缀 / 后缀标签 ReactNode -
borderless 无边框模式(v2.33.0+) boolean false
validateStatus 校验结果:warning / error / default(只影响样式背景色) string -
autoExpandParent 是否自动展开父节点 boolean false
motionExpand 是否开启选项树节点动画 boolean true
outerTopSlot / outerBottomSlot 渲染在弹出层顶部/底部的自定义 slot(outerTopSlot 开启 filterTreeNode 时会取代搜索框) ReactNode -
onVisibleChange 弹出层展示/隐藏时回调 (isVisible: boolean) => void -
onFocus / onBlur 聚焦 / 失焦回调 (event) => void -
onSelect 节点被选中时回调,返回 (selectedKey, selected, selectedNode) Function -
onLoad 节点加载完毕回调(配合 loadData) (loadedKeys: Set<string>, treeNode) => void -

说明:treeNodeFilterProp 默认 'label',treeNodeLabelProp 默认 'label'。若使用 keyMaps 自定义了 label 字段名且开启搜索,为保证搜索正确,需将 treeNodeFilterProp 设置为 treeData 的键之一,或通过 filterTreeNode 自定义搜索函数。

十一、Methods:外部调用 search

TreeSelect 提供绑定在组件实例上的方法,可通过 ref 调用:

Name Description
search(sugInput: string) 如果需要在外部自定义搜索框,可以在自定义搜索框值变更时主动调用该方法,改变筛选结果

示例:

import React, { useRef } from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';

function Demo() {
    const ref = useRef(null);
    return (
        <>
            <button onClick={() => ref.current && ref.current.search('上海')}>外部搜索</button>
            <TreeSelect ref={ref} filterTreeNode treeData={treeData} />
        </>
    );
}

十二、无障碍(Accessibility)

TreeSelect 内置了完整的 ARIA 支持:

  • 组件会自动设置 aria-label 为 'TreeSelect',也支持用户自行设置 aria-label 来表示该 TreeSelect 的作用;
  • 允许用户设置 aria-describedby、aria-errormessage、aria-invalid、aria-labelledby、aria-required;另外,Form 会为 Form.TreeSelect 自动设置这些属性;
  • 组件会自动为每个子节点分别设置 aria-disabled、aria-checked、aria-selected、aria-level,以表明节点状态及层级。

示例:

<TreeSelect
    /* other attributes */
    aria-label='example treeSelect'
/>

此外,从 Foundation 源码还能看到键盘与焦点语义:ESC 键关闭面板(handleKeyDown),Enter 键模拟点击选择(handleSelectionEnterPress),点击外部区域自动失焦并关闭弹层(_registerClickOutsideHandler 与 handlerTriggerBlur),这些共同构成了键盘可访问的基础。

十三、小结:一个可落地的完整示例

将本文要点组合起来,即可得到一个覆盖"多选 + 搜索 + 标签折叠 + 受控 + 严格禁用"的企业级完整用法:

import React, { useState } from 'react';
import { TreeSelect } from '@douyinfe/semi-ui';

const departmentTree = [
    {
        label: '技术中心', value: 'tech', key: '0',
        children: [
            {
                label: '前端组', value: 'frontend', key: '0-0',
                children: [
                    { label: 'Semi 平台', value: 'semi', key: '0-0-0' },
                    { label: '中后台', value: 'admin', key: '0-0-1' },
                ],
            },
            { label: '后端组', value: 'backend', key: '0-1' },
        ],
    },
    { label: '产品中心', value: 'product', key: '1' },
];

function DeptPicker() {
    const [value, setValue] = useState([]);
    return (
        <TreeSelect
            multiple
            filterTreeNode
            showFilteredOnly
            maxTagCount={3}
            showRestTagsPopover
            restTagsPopoverProps={{ position: 'top' }}
            searchPosition="trigger"
            value={value}
            onChange={setValue}
            treeData={departmentTree}
            style={{ width: 360 }}
            placeholder="请选择部门(支持搜索与多选)"
        />
    );
}

延伸阅读

登录后查看全文
semi-design