Semi Design TreeSelect 树选择器完全指南:从基础用法到源码级原理
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 即可多选。多选场景下有两个关键行为:
- 父子联动:所有子项都被选择时,自动勾选并显示其父项(半选态由
halfCheckedKeys维护)。 - 只选叶子(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 时:
- 搜索框占位符由
placeholder控制; 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="请选择部门(支持搜索与多选)"
/>
);
}
延伸阅读
- 组件源码:packages/semi-ui/treeSelect/index.tsx
- 逻辑层实现:packages/semi-foundation/treeSelect/foundation.ts
- 常量与样式类定义:packages/semi-foundation/treeSelect/constants.ts、packages/semi-foundation/treeSelect/treeSelect.scss
- 测试用例(覆盖多选联动、leafOnly、searchPosition、triggerTagWrap 等):packages/semi-ui/treeSelect/test/treeSelect.test.js、packages/semi-ui/treeSelect/test/treeMultiple.test.js
- 英文版文档:content/input/treeselect/index-en-US.md