Tree树形控件

何时使用#

文件夹、组织架构、生物分类、国家地区等等,世间万物的大多数结构都是树形结构。使用树控件可以完整展现其中的层级关系,并具有展开收起选择等交互功能。

import { NzTreeModule } from 'ng-zorro-antd/tree';

代码演示

parent 1parent 1-0leaf 1-0-0leaf 1-0-1parent 1-1

最简单的用法,展示可勾选,可选中,禁用,默认展开等功能。

expand codeexpand code
      加载中
    
0-00-0-00-0-0-00-0-0-10-0-0-20-0-10-0-20-10-2

将节点拖拽到其他节点内部或前后。

expand codeexpand code
      加载中
    
Expand to loadExpand to loadTree Node

点击展开节点,动态加载数据。

expand codeexpand code
      加载中
    
parent 1parent 1-0leafleafleafparent 1-1parent 1-2

带连接线的树。

expand codeexpand code
      加载中
    
parent 0created by ng zorroleaf 0-0modified by ng zorroleaf 0-1modified by ng zorroparent 1created by ng zorro

使用 nzTreeTemplate 实现自定义目录结构,通过 let-origin="origin" 获得原始数据,let-node 获取当前节点状态。

expand codeexpand code
      加载中
    
0-00-0-00-0-0-00-0-0-10-0-0-20-0-10-0-1-00-0-1-10-0-1-20-0-20-10-2

受控操作示例(默认)。

expand codeexpand code
      加载中
    
0-00-0-00-0-1

nzBeforeDrop: 在拖拽放置事件(drop事件)之前做校验, 例如仅允许拖拽到内部(延时一秒)、放置前结合modal验证等。

expand codeexpand code
      加载中
    
parent 1leafleaf
parent 1leafleaf

可以针对不同的节点定制图标。

expand codeexpand code
      加载中
    

设定 nzVirtualHeight 开启虚拟滚动。

expand codeexpand code
      加载中
    

API#

nz-tree#

说明: 根据目前的数据结构设计,需要保证优先设置 nzData,否则各属性不会生效。异步操作待数据返回后,重新赋值其他各属性触发渲染(nzExpandAllnzExpandedKeysnzCheckedKeysnzSelectedKeysnzSearchValue)。重构优化工作请追踪 #5152

参数说明类型默认值全局配置
[nzData]元数据NzTreeNodeOptions[] | NzTreeNode[][]
[nzBlockNode]是否节点占据一行booleanfalse
[nzCheckable]节点前添加 Checkbox 复选框booleanfalse
[nzShowExpand]节点前添加展开图标booleantrue
[nzShowLine]是否展示连接线booleanfalse
[nzExpandedIcon]自定义展开图标TemplateRef<{ $implicit: NzTreeNode }>-
[nzShowIcon]是否展示 TreeNode title 前的图标,没有默认样式booleanfalse
[nzAsyncData]是否异步加载(显示加载状态)booleanfalse
[nzDraggable]设置节点可拖拽booleanfalse
[nzMultiple]支持点选多个节点(节点本身)booleanfalse
[nzHideUnMatched]搜索隐藏未匹配的节点booleanfalse
[nzCheckStrictly]checkable 状态下节点选择完全受控(父子节点选中状态不再关联)booleanfalse
[nzTreeTemplate]自定义节点TemplateRef<{ $implicit: NzTreeNode }>-
[nzExpandAll]默认展开所有树节点booleanfalse
[nzExpandedKeys]展开指定的树节点string[][]
[nzCheckedKeys]指定选中复选框的树节点string[][]
[nzSelectedKeys]指定选中的树节点string[][]
[nzSearchValue]按需筛选树高亮节点(参考可搜索的树),双向绑定stringnull
[nzSearchFunc]自定义匹配方法,配合 nzSearchValue 使用(node: NzTreeNodeOptions) => booleannull
[nzBeforeDrop]drop 前二次校验,允许用户自行决定是否允许放置(confirm: NzFormatBeforeDropEvent) => Observable<boolean>-
[nzVirtualHeight]虚拟滚动的总高度string-
[nzVirtualItemSize]虚拟滚动时每一列的高度,与 cdk itemSize 相同number28
[nzVirtualMaxBufferPx]缓冲区最大像素高度,与 cdk maxBufferPx 相同number500
[nzVirtualMinBufferPx]缓冲区最小像素高度,低于该值时将加载新结构,与 cdk minBufferPx 相同number28
(nzClick)点击树节点触发EventEmitter<NzFormatEmitEvent>-
(nzDblClick)双击树节点触发EventEmitter<NzFormatEmitEvent>-
(nzContextMenu)右键树节点触发EventEmitter<NzFormatEmitEvent>-
(nzCheckBoxChange)点击树节点 Checkbox 触发EventEmitter<NzFormatEmitEvent>-
(nzExpandChange)点击展开树节点图标触发EventEmitter<NzFormatEmitEvent>-
(nzSearchValueChange)搜索节点时调用(与 nzSearchValue 配合使用)EventEmitter<NzFormatEmitEvent>-
(nzOnDragStart)开始拖拽时调用EventEmitter<NzFormatEmitEvent>-
(nzOnDragEnter)dragenter 触发时调用EventEmitter<NzFormatEmitEvent>-
(nzOnDragOver)dragover 触发时调用EventEmitter<NzFormatEmitEvent>-
(nzOnDragLeave)dragleave 触发时调用EventEmitter<NzFormatEmitEvent>-
(nzOnDrop)drop 触发时调用EventEmitter<NzFormatEmitEvent>-
(nzOnDragEnd)dragend 触发时调用EventEmitter<NzFormatEmitEvent>-

方法#

方法名说明返回值
getTreeNodes获取组件 NzTreeNode 节点NzTreeNode[]
getTreeNodeByKey按 key 获取 NzTreeNode 节点NzTreeNode
getCheckedNodeList获取组件 checkBox 被点击选中的节点NzTreeNode[]
getSelectedNodeList获取组件被选中的节点NzTreeNode[]
getHalfCheckedNodeList获取组件半选状态节点NzTreeNode[]
getExpandedNodeList获取组件展开状态节点NzTreeNode[]
getMatchedNodeList获取组搜索匹配到的节点NzTreeNode[]

NzTreeNodeOptions props#

参数说明类型默认值
title标题string-
key整个树范围内的所有节点的 key 值不能重复且不为空!string-
icon节点前的图标,与 nzShowIcon 组合使用string-
children子节点NzTreeNodeOptions[]-
isLeaf设置为叶子节点(叶子节点不可被拖拽模式放置)booleanfalse
checked设置节点 Checkbox 是否选中booleanfalse
selected设置节点本身是否选中booleanfalse
expanded设置节点是否展开(叶子节点无效)booleanfalse
selectable设置节点是否可被选中booleantrue
disabled设置是否禁用节点(不可进行任何操作)booleanfalse
disableCheckbox设置节点禁用 Checkboxbooleanfalse
[key: string]自定义数据,可通过 NzTreeNode 的 origin 字段获取any -

NzFormatEmitEvent props#

属性说明类型默认值
eventName事件名enum: clickdblclickcontextmenucheckexpandsearch & dragstartdragenterdragoverdragleavedropdragend-
node当前操作节点(拖拽时表示目标节点)NzTreeNodenull
event原生事件'MouseEvent' | 'DragEvent'null
dragNode?当前拖拽节点(拖拽时存在)NzTreeNodenull
selectedKeys?已选中的节点 key(单击时存在)NzTreeNode[][]
checkedKeys?checkBox 已选中的节点 key(点击 checkBox 存在)NzTreeNode[][]
matchedKeys?搜索时匹配到的节点 keyNzTreeNode[][]
keys?非拖拽事件相关的全部节点的 key 数组string[][]
nodes?非拖拽事件相关的全部节点NzTreeNode[][]

NzFormatBeforeDropEvent props#

属性说明类型默认值
dragNode当前拖拽节点(拖拽时存在)NzTreeNode-
node当前操作节点(拖拽时表示目标节点)NzTreeNode-
pos放置位置(-1:目标节点前面, 0: 目标节点内部, 1: 目标节点后面)number-

NzTreeNode props#

属性说明类型默认值
title标题stringNzTreeNodeOptions.title
keykey 值stringNzTreeNodeOptions.key
level层级(最顶层为 0,子节点逐层加 1)numbernumber
children子节点NzTreeNode[][]
origin原始节点树结构(用户提供,用于展示额外信息)NzTreeNodeOptions-
getParentNode获取父节点functionnull
isLeaf是否为叶子节点booleanfalse
isExpanded是否已展开booleanfalse
isDisabled是否禁用booleanfalse
isDisableCheckbox是否禁用 checkBoxbooleanfalse
isSelectable是否可选中booleantrue
isChecked是否选中 checkBoxbooleanfalse
isHalfChecked子节点有选中但未全选booleanfalse
isSelected是否已选中booleanfalse
isLoading是否异步加载状态(影响展开图标展示)booleanfalse
isMatchedtitle 是否包含 nzSearchValue(搜索使用)booleanfalse
setSyncChecked设置 checked 状态并同步其他节点状态function-
getChildren获取子节点,返回 NzTreeNode 数组function-
addChildren添加子节点,接收 NzTreeNode 或 NzTreeNodeOptions 数组,第二个参数为插入的索引位置,默认插入末尾(children: array, index?: number )=>{}-
clearChildren清除子节点function-
remove清除当前节点(非根节点)function-

注意#

  • 当前请确保 nzData 在其他数据相关的属性之前被初始化:
// 示例
this.nzExpandAll = false;
const nodes = []; // 源数据
this.nzData = [...nodes];
// nzData 值异步获取变化后重新渲染一下属性
this.nzExpandedKeys = [...this.nzExpandedKeys];
// this.nzExpandAll = true;
this.nzCheckedKeys = [...this.nzCheckedKeys];
this.nzSelectedKeys = [...this.nzSelectedKeys];
  • NzTreeNodeOptions 可以接受用户自定义属性,可通过 NzTreeNodeorigin 属性取得。
  • 使用 ViewChild 时,Tree 方法需要在 ngAfterViewInit 中调用。
  • nzData 属性请传递 NzTreeNodeOptions 数组。