Tree

代码演示

如何引入

import { Tree } from '@chenzy-design/svelte';

基本用法

最简单的用法，默认为单选模式，每一级菜单项均可选择。

多选

设置 multiple，可以进行多选。多选情况下所有子项都被选择时，自动勾选显示其父项。

可搜索的

通过设置 filterTreeNode 属性可支持搜索功能。默认对 label 值进行搜索，可通过 treeNodeFilterProp 更改。如果只希望展示过滤后的结果，可以设置 showFilteredOnly。

设置 filterTreeNode 属性开启搜索后，可以通过设置 searchRender 自定义搜索框的渲染方法，设置为 false 时可以隐藏搜索框。

手动触发搜索

可以通过 bind:this 的方式获取 tree 的实例，调用 tree 的 search 方法进行搜索。注意需要同时设置 filterTreeNode 开启搜索，如果搜索框在 tree 外部，可以通过设置 searchRender={false} 隐藏 tree 内部的搜索框。

简单 JSON 格式的数据

可以通过 treeDataSimpleJson 传入 JSON 形式的 treeNodes 数据。此时 key-value 键值对中的 key 值将作为 TreeNodeData 的 key 和 label，value 值将作为 TreeNodeData 的 value。返回值为包含选中节点的 JSON 数据。

行显示节点

可以通过设置 blockNode 使节点显示为整行，此时悬浮选中高亮状态都会显示整行。默认打开。关闭时只高亮节点 label。

自定义节点内容

TreeNodeData 的 label 属性支持传入 Snippet 来自定义显示的节点内容。注意如果设置 filterTreeNode 开启搜索，默认是对 label 的值进行搜索，当 label 为 Snippet 时，需要自定义 filterTreeNode 的函数来满足搜索需求。

你也可以使用 renderLabel 来传入自定义的渲染方法，此时搜索值仍为 treeData 中相应的 label 属性。

过长省略：可以使用 renderLabel 来实现文本过长省略的效果。

自定义图标

通过设置节点数据的 icon 属性可添加节点级自定义图标；也可以设置组件级 icon（Snippet 或函数）统一渲染。节点级 icon 优先级高于组件级。

目录树模式

通过设置 directory 属性可显示为目录树模式。目录树模式下自带目录图标，可以通过自定义图标覆盖。

禁用

可以使用 disableStrictly 来开启严格禁用。开启严格禁用后，当节点是 disabled 的时候，则不能通过子级或者父级的关系改变选中状态。

节点选中关系

版本：>= 2.5.0

多选时，可以使用 checkRelation 来设置节点选中关系的类型，可选：related（默认）、unRelated。当选中关系为 unRelated，意味着节点之间的选中互不影响。

默认展开

defaultExpandAll 和 expandAll 均可以设置 Tree 的默认展开/收起状态。二者的区别是，defaultExpandAll 只在初始化时生效，而 expandAll 不仅会在初始化时生效，当数据发生动态更新时，expandAll 也仍然生效。

开启搜索的展开受控

传入 expandedKeys 时即为展开受控组件，可以配合 onExpand 使用。当展开受控时，如果开启 filterTreeNode 并进行搜索是不会再自动展开节点的，此时，节点的展开完全由 expandedKeys 来控制。你可以利用 onSearch 的入参 filteredExpandedKeys 来实现展开受控时的搜索展开效果。

受控

传入 value 时即为受控组件，可以配合 onChange 使用。

自动展开父节点

在展开受控的情况下，当开启了 autoExpandParent，如果想要收起父元素，则需要把它的所有子元素均收起后才可以。默认情况下，autoExpandParent 为 false，即父元素收起不受到子元素的影响。

自定义展开 Icon

可以通过 expandIcon 自定义展开 Icon，支持传入 Snippet（静态图标）或按展开态条件切换的内容。

连接线

通过 showLine 设置节点之间的连接线，默认为 false。

虚拟化

列表虚拟化，用于大量树节点的情况。开启后，动画效果将被关闭。virtualize 是一个包含 height、width、itemSize 的对象。如果带搜索框，建议开启 showFilteredOnly 减少多余节点的渲染。

动态更新数据

异步加载数据

通过设置 loadData 可以动态加载数据，此时需要在数据中传入 isLeaf 标明叶子节点。loadData 返回该节点的子节点数组（由组件内部缓存合并进渲染树，不写回受控 treeData）。

可拖拽的 Tree

通过设置 draggable 配合 onDrop 可以实现 Tree 节点的拖拽。目前不支持与虚拟化同时使用。

onDrop 回调入参 dropPosition 为 'before' | 'inside' | 'after'，分别表示插入到目标节点之前、成为目标节点子节点、插入到目标节点之后。

高级定制·叶子分组勾选

Tree 组件的 API 支持了大部分的渲染需求，如果有非常特殊的定制要求，可以使用 renderFullLabel 来接管整行 option 的渲染效果。此例针对「希望只有叶子节点可以选中，父节点只起到分组作用」的场景：只渲染叶子节点前的 Checkbox，并且点击父节点时不触发选中，点击叶子节点触发。同时开启 leafOnly 可以使 onChange 的回调入参都是叶子节点。

高级定制·叶子分组单选

此例针对「希望只有叶子节点可以单选，父节点只起到分组作用」的场景：点击父节点时不触发选中（仅触发展开/收起），点击叶子节点才触发选中。

高级定制·单选高亮子节点

此例针对「单选选中父节点同时也高亮子节点」的场景，通过 renderFullLabel 接管渲染并配合 onSelect 实现。

可拖拽的高级定制

支持可拖拽（draggable）和高级定制（renderFullLabel）同时使用。

字段映射

可以通过 keyMaps 自定义节点中 key、label、value、children 的字段。

自定义搜索谓词

将 filterTreeNode 置为自定义函数，定制你想要的搜索策略。

API 参考

Tree

属性	说明	类型	默认值
autoExpandParent	是否自动展开父节点	boolean	false
autoExpandWhenDragEnter	是否允许拖拽到节点上时自动展开该节点	boolean	true
autoMergeValue	开启后，当某个父节点被选中时，value 将不包括该节点的子孙节点（在 leafOnly 为 false 时生效）	boolean	true
blockNode	行显示节点	boolean	true
checkRelation	多选时，节点之间选中状态的关系，可选：related、unRelated	string	related
class	类名	string	-
defaultExpandAll	设置在初始化时是否展开所有节点	boolean	false
defaultExpandedKeys	默认展开的节点，显示其直接子级	string[]	-
defaultValue	指定默认选中的条目	string \| number \| array	-
directory	目录树模式	boolean	false
disableStrictly	当节点的 disabled 状态确定时，不可通过子级或父级的关系选中	boolean	false
disabled	禁用整个树，不可选择	boolean	false
draggable	是否允许拖拽	boolean	false
emptyContent	当搜索无结果时展示的内容	string \| Snippet	暂无数据
expandAction	展开逻辑，可选 false、click、doubleClick	boolean \| string	false
expandAll	设置是否默认展开所有节点，若后续数据发生改变，展开情况也受此 api 影响	boolean	false
expandedKeys	（受控）展开的节点，默认展开节点显示其直接子级	string[]	-
expandIcon	自定义展开图标	Snippet	-
keyMaps	自定义节点中 key、label、value、children 的字段	object	-
filterTreeNode	是否根据输入项进行筛选，默认用 treeNodeFilterProp 的值筛选	boolean \| ((input, treeNodeString, data) => boolean)	false
hideDraggingNode	是否隐藏正在拖拽的节点的 dragImg	boolean	false
icon	组件级自定义图标（统一渲染），节点级 TreeNodeData.icon 优先级更高	Snippet	-
labelEllipsis	是否开启 label 的超出省略，默认虚拟化状态开启	boolean	false \| true(虚拟化)
leafOnly	多选模式下 onChange 回调入参及展示标签只有叶子节点	boolean	false
loadData	异步加载数据，返回该节点的子节点数组	(node) => Promise<TreeNodeData[]>	-
loadedKeys	（受控）已经加载的节点，配合 loadData 使用	string[]	-
motion	是否开启动画	boolean	true
multiple	是否支持多选	boolean	false
preventScroll	聚焦时是否阻止浏览器滚动文档，作用于组件内搜索框的聚焦	boolean	false
renderDraggingNode	自定义正在拖拽节点的 dragImg 的 DOM 元素	(nodeInstance, node) => HTMLElement	-
renderFullLabel	完全自定义 label 的渲染函数	Snippet	-
renderLabel	自定义 label 的渲染函数	Snippet	-
searchClassName	搜索框的 className 属性	string	-
searchPlaceholder	搜索框默认文字	string	-
searchRender	自定义搜索框的渲染方法，为 false 时可以隐藏组件的搜索框	Snippet \| false	-
searchStyle	搜索框的样式	string	-
showClear	支持清除搜索框	boolean	true
showFilteredOnly	搜索状态下是否只展示过滤后的结果	boolean	false
showLine	显示连接线	boolean	false
style	样式	string	-
treeData	treeNodes 数据，key 值在整个树范围内唯一	TreeNodeData[]	[]
treeDataSimpleJson	简单 JSON 形式的 TreeNodeData 数据	object	{}
treeNodeFilterProp	搜索时输入项过滤对应的 TreeNodeData 属性	string	label
value	当前选中的节点的 value 值，传入时作为受控组件	string \| number \| array	-
virtualize	列表虚拟化，由 height、width、itemSize 组成，开启后将关闭动画效果	object	-
onChange	选中树节点时调用，默认返回当前所有选中项的 value 值	(value?) => void	-
onChangeWithObject	是否将选中项 option 的其他属性作为回调	boolean	false
onDoubleClick	双击事件的回调	(e, node) => void	-
onDragEnd	onDragEnd 事件回调	(dragProps) => void	-
onDragEnter	onDragEnter 事件回调	(dragProps) => void	-
onDragLeave	onDragLeave 事件回调	(dragProps) => void	-
onDragOver	onDragOver 事件回调	(dragProps) => void	-
onDragStart	onDragStart 事件回调	(dragProps) => void	-
onDrop	onDrop 事件回调	(info: { dragNode, dropNode, dropPosition }) => void	-
onExpand	展示节点时调用	(expandedKeys, object) => void	-
onLoad	节点加载完毕时触发的回调	(loadedKeys, node) => void	-
onContextMenu	右键点击的回调	(e, node) => void	-
onSearch	文本框值变化时回调	(input, filteredExpandedKeys) => void	-
onSelect	被选中时调用，返回值为当前事件选项的 key 值	(selectedKey, selected, selectedNode) => void	-

TreeNodeData

不同 TreeNodeData 的 key 值要求必填且唯一。label 允许重复。value 值非必填，此时 onChange、value、defaultValue 中所取的 value 属性值将改为 key 值。

属性	说明	类型	默认值
value	属性值	string \| number	-
label	展示的文本	string \| Snippet	-
icon	节点级自定义图标，优先级高于组件级 icon	Snippet	-
disabled	是否禁用	boolean	false
key	required 且要求唯一	string	-
isLeaf	设置节点为叶子节点，在异步加载数据即传入 loadData 时有效	boolean	-

Virtualize

itemSize 必传。

属性	说明	类型	默认值
height	高度值，如果为 string 必须保证有计算高度	number \| string	100%
itemSize	每行的 treeNode 的高度，必传	number	-
width	宽度值	number \| string	100%

Methods

绑定在组件实例上的方法，可以通过 bind:this 拿到实例后调用：

名称	描述
search	手动触发搜索
scrollTo	在虚拟化 Tree 中，使指定节点滚动到视图

Accessibility

ARIA

• Tree 支持传入 aria-label 来表示该 Tree 作用。
• Tree 会自动为每个子节点分别设置 aria-disabled、aria-checked、aria-selected、aria-level 来表明节点状态及层级。
• Tree 会自动为对应部分分别设置 role 为 tree、treeitem。

设计变量

color

font

height

radius

spacing

width

变量	默认值	用法
--cd-color-tree-option-bg-active	var(--cd-color-primary-light-default)	树选项选中/激活背景（$color-tree_option-bg-active）
--cd-color-tree-option-bg-hover	var(--cd-color-fill-0)	树选项悬停背景（$color-tree_option-bg-hover）
--cd-color-tree-option-disabled-text-default	var(--cd-color-disabled-text)	禁用树选项文字颜色（$color-tree_option_disabled-text-default）
--cd-color-tree-option-draggable-insert-border-default	var(--cd-color-primary)	可拖拽插入指示线颜色（$color-tree_option_draggable_insert-border-default）
--cd-color-tree-option-highlight-text	var(--cd-color-primary)	搜索命中高亮文本色（$color-tree_option_hightlight-text）
--cd-color-tree-option-icon-active	var(--cd-color-black)	展开图标按下色（$color-tree_option-icon-active）
--cd-color-tree-option-icon-default	var(--cd-color-text-2)	展开箭头 / 节点图标颜色（$color-tree_option-icon-default）
--cd-color-tree-option-icon-hover	var(--cd-color-text-0)	展开图标悬停色（$color-tree_option-icon-hover）
--cd-color-tree-option-line	var(--cd-color-text-3)	showLine 连接线颜色（Semi 用 --semi-color-text-3）
--cd-color-tree-option-loading-icon-default	var(--cd-color-primary)	树选项加载 spin 颜色（$color-tree_option_loading-icon-default）

显示第 1 条-第 10 条，共 35 条

• 1
• 2
• 3
• 4