API

he-tree导出两个组件, BaseTree 和 Draggable. BaseTree 是基础组件. Draggable 继承于前者, 包含拖拽功能. 下文中的内容根据此粗略地分成了两部分.

下文中的Stat<never>, Stat<unknown>是 TypeScript 的类型格式. 其中的unknown, never, any基本都是指使用者提供的节点数据类型. Stat<never>Stat<unknown>是一样的, 表示使用者的节点数据的stat.

下文中的所有坐标原点是窗口左上角. 如Element.getBoundingClientRect()返回的坐标.

BaseTree#

props#

updateBehavior#

当内部数据变动时, 更新到外部的方式.

  • modify: 默认. 直接修改绑定的数据对象.
  • new: 提交一个新的数据对象, 适用于 vuex.
  • disabled: 不提交. 你可以使用getData方法手动生成并获取当前数据.

childrenKey#

{ type: String, default: "children" }
js

指定数据中的children key

textKey#

{ type: String, default: "text" }
js

指定数据中的text key. 默认模板会显示它. 如果你通过插槽自定义了节点, 这个可能就不需要了.

indent#

{ type: Number, default: 20 }
js

节点缩进像素.

virtualization#

{ type: Boolean, default: false }
js

启用虚拟列表.

virtualizationPrerenderCount#

{ type: Number, default: 20 }
js

虚拟列表初始渲染数量.用于 SSR(服务端渲染).

defaultOpen#

{ type: Boolean, default: true }
js

默认展开所有节点.

statHandler#

{ type: (stat: Stat<any>) => Stat<any> }
js

钩子函数. 数据初始时处理每一个stat.

rtl#

{ type: Boolean, default: false }
js

由右向左显示.

btt#

{ type: Boolean, default: false }
js

由下向上显示.

table#

{ type: Boolean, default: false }
js

渲染为表格.

watermark#

{ type: Boolean, default: true }
js

向浏览器控制台输出一条水印信息.

data#

stats#

所有 stats, 树形结构.

statsFlat#

所有 stats, 扁平结构.

dragNode#

拖拽时的节点 stat.

dragOvering#

有东西拖拽到了此树上.

self#

此树实例, 即this.

methods(方法)#

getStat#

(nodeData: unknown): Stat<unknown>
ts

根据节点数据获取节点的stat.

has#

(nodeData: unknown): boolean
ts

判断此树是否包含对应节点数据的stat.

getChecked#

(withDemi?: boolean | undefined): Stat<unknown>[]
ts

获取所有勾选的节点 stat. 参数withDemi表示是否包含半选的节点(后代节点未完全选中).

getUnchecked#

(withDemi?: boolean | undefined): Stat<unknown>[]
ts

获取所有未勾选的节点 stat. 参数withDemi表示是否包含半选的节点(后代节点未完全选中).

updateCheck#

(): void
ts

从末端到根, 重新计算每个节点的勾选状态.

openAll#

(): void
ts

展开所有节点.

closeAll#

(): void
ts

折叠所有节点.

isVisible#

(statOrNodeData: Stat<unknown>|unknown): boolean;
ts

判断节点是否可见. 如果父级折叠, 则后代不可见. 参数可以是节点数据或 stat.

move#

(stat: Stat<unknown>, parent: Stat<unknown> | null, index: number): boolean;
ts

移动节点. parent 为 null 时代表根节点.

add#

(nodeData: unknown, parent?: Stat<unknown> | null | undefined, index?: number | null | undefined): void;
ts

增加节点. parent 为 null 时代表根节点.

addMulti#

(
  dataArr: any[],
  parent?: Stat<any> | null,
  startIndex?: number | null
): void;
ts

增加多个连续节点. parent 为 null 时代表根节点.

remove#

(stat: Stat<unknown>): boolean;
ts

删除节点.

removeMulti#

(dataArr: any[]): boolean;
ts

删除多个节点.

batchUpdate#

(task: () => any | Promise<any>): void;
ts

操作数据时, 会导致组件内部提交整个树的新数据. 此方法可以合并多个操作, 从而只提交一次.

iterateParent#

(stat: Stat<unknown>, opt?: {
    withSelf: boolean;
} | undefined): Generator<Stat<unknown>, void, unknown>;
ts

遍历节点的父级. 参数opt.withSelf表示是否包含该节点. 例:

for (const parentStat of tree.iterateParent(nodeStat, { withSelf: false })) {
  //
}
ts

getSiblings#

(stat: Stat<never>): Stat<never>[];
ts

获取一个节点的同级.

getData#

(filter?: ((data: never) => never) | undefined, root?: Stat<never> | undefined): never[];
ts

生成并获取当前树的树形数据. 移除了 stat. 参数filter可以对每个数据进行处理.

getRootEl#

(): HTMLElement;
ts

获取当前树的根元素.

events(事件)#

click:node#

参数: stat. 点击节点时触发.

open:node#

参数: stat. 展开节点时触发.

close:node#

参数: stat. 折叠节点时触发.

check:node#

参数: stat. 节点勾选状态改变时触发.

slots(插槽)#

default(默认插槽)#

用来自定义节点样式. 参数:

  • node: 节点数据
  • stat: 节点内部信息
  • indentStyle: 节点缩进样式. 仅当渲染为表格时需要使用者将其应用到某列上, 一般是第一列.
  • tree: 树的实例.

placeholder#

占位元素内部. 可以用来添加提示性文字. 参数:

  • tree: 树的实例.

prepend#

树的根元素内开始处. 仅用于渲染为表格时添加表头(thead). 参数:

  • tree: 树的实例.

append#

树的根元素内结束前. 仅用于渲染为表格时添加表底部(tfoot). 参数:

  • tree: 树的实例.

Draggable#

props#

triggerClass#

{
  type: [String, Array]
} // string | string[]
js

触发拖拽的元素样式. 默认是节点本身. 可以设置成节点的某个子元素. 支持多个样式.

disableDrag#

{
  type: Boolean
}
js

禁用此树的拖出功能.

disableDrop#

{
  type: Boolean
}
js

禁用此树的拖入功能.

eachDraggable#

(stat: Stat<any>) : boolean | null
ts

钩子函数. 设置每个节点是否可拖动. 子级如果没有指定, 会继承父级的值.

eachDroppable#

(stat: Stat<any>) : boolean | null
ts

钩子函数. 设置每个节点是否可拖入. 子级如果没有指定, 会继承父级的值.

rootDroppable#

boolean | () : boolean
ts

钩子函数. 设置最高级(根)是否可拖入. 默认true.

dragOpen#

{ type: Boolean, default: true }
js

拖动到节点上层时是否打开节点.

dragOpenDelay#

{ type: Number, default: 0 }
js

拖动到节点上层时打开节点前的等待的毫秒.

beforeDragOpen#

(stat: Stat<any>) : void | Promise<void>
ts

钩子函数. 拖动到节点上层时打开节点前执行. 可以返回 Promise.

resolveStartMovePoint#

"mouse" | "default" | ((dragElement: HTMLElement) : Point)
ts

拖动节点将被看做一个点. 拖动开始时如何获取拖动点的坐标. 默认获取节点的左上角. mouse表示使用鼠标坐标. 或者传入函数返回自定义坐标: {x:number,y:number}.

keepPlaceholder#

{ type: Boolean, default: false }
ts

拖拽离开树时是否保留占位元素.

maxLevel#

{
  type: Number
}
ts

拖拽时的最大层级数. 如果拖拽将导致树超过此层数, 则会阻止拖放.

onExternalDragOver#

(event: DragEvent) : boolean
ts

当外部使用 Drag and Drop API 拖拽到树上层时发生. 参数 event 是 Drag and Drop API 原生事件dragover的事件对象. 返回布尔值判断是否处理该事件.

externalDataHandler#

(event: DragEvent) : any
ts

当外部使用 Drag and Drop API 拖拽到树上层并结束拖拽时发生. 用来告知树此次拖拽应该接收的数据.

methods(方法)#

getNodeByElement#

(el: HTMLElement): Stat<any> | null
ts

根据 HTML 元素获取节点 stat.

isDraggable#

(node: Stat<any>): boolean
ts

判断节点是否可拖动.

isDroppable#

(node: Stat<any>): boolean
ts

判断节点是否可拖入.

events(事件)#

enter#

参数: DragEvent. 拖拽进入时触发.

leave#

参数: DragEvent. 拖拽离开时触发.

after-drop#

参数: 无. 拖拽完成时触发. 跨树时, 仅在拖入的树触发.

change#

参数: 无. 拖拽完成且造成改变时触发. 跨树时, 两棵树都会触发.

Others#

Stat#

组件内部将会为每一个节点创建 stat 对象, 用了存储运行时数据.

{
  [x: string]: any // 可以向stat附加任何键值
  data: T // 指向对应的节点数据
  open: boolean // 是否展开
  parent: Stat<T> | null // 父级节点stat
  children: Stat<T>[] // 子级节点
  level: number // 层级. 层级从1开始.
  isStat: boolean // 是否是stat对象
  hidden: boolean // 是否隐藏
  checked: boolean | null // 是否勾选. null表示后代节点部分勾选
  draggable: boolean | null // 是否可拖动. null表示继承父级.
  droppable: boolean | null // 是否可拖入. null表示继承父级.
  style: any // 自定义样式. 支持Vue的style格式.
  class: any // 自定义样式类. 支持Vue的class格式.
}
ts

dragContext#

拖拽时的相关信息对象. 包括属性: startInfo, targetInfo, dragNode, startTree, targetTree. 引入:

// vue3
import { dragContext } from '@he-tree/vue'
// vue2
import { dragContext } from '@he-tree/vue/vue2'
ts

startInfo#

类型: StartInfo. 拖拽开始的信息.

targetInfo#

类型: StartInfo. 拖拽的目标的信息.

dragNode#

类型: Stat. 拖拽的节点.

startTree#

Draggable 组件实例. 拖拽的起始树.

targetTree#

Draggable 组件实例. 拖拽的目标树.

StartInfo#

{
  tree: DraggableTreeType; // Draggable组件的实例
  dragNode: Stat<any>; // 拖拽节点
  parent: Stat<any> | null; // 拖拽节点父级
  siblings: Stat<any>[]; // 拖拽节点同级
  indexBeforeDrop: number; // 拖拽节点在拖拽结束前的索引
}
ts