API
he-tree
导出两个组件, BaseTree 和 Draggable. BaseTree 是基础组件. Draggable 继承于前者, 包含拖拽功能. 下文中的内容根据此粗略地分成了两部分.
下文中的Stat<never>
, Stat<unknown>
是 TypeScript 的类型格式. 其中的unknown
, never
, any
基本都是指使用者提供的节点数据类型. Stat<never>
和Stat<unknown>
是一样的, 表示使用者的节点数据的stat.
下文中的所有坐标原点是窗口左上角. 如Element.getBoundingClientRect()
返回的坐标.
BaseTree#
props#
btt#
{ type: Boolean, default: false }
由下向上显示.
childrenKey#
{ type: String, default: "children" }
指定数据中的children
key
defaultOpen#
{ type: Boolean, default: true }
默认展开所有节点.
indent#
{ type: Number, default: 20 }
节点缩进像素.
nodeKey#
使用 index 或者返回一个唯一值作为 Vue 循环的 key。
{ type: "index" | ((stat: Stat<any>, index: number) => any), default: 'index' }
rtl#
{ type: Boolean, default: false }
由右向左显示.
statHandler#
{ type: (stat: Stat<any>) => Stat<any> }
钩子函数. 数据初始时处理每一个stat.
table#
{ type: Boolean, default: false }
渲染为表格.
textKey#
{ type: String, default: "text" }
指定数据中的text
key. 默认模板会显示它. 如果你通过插槽自定义了节点, 这个可能就不需要了.
updateBehavior#
当内部数据变动时, 更新到外部的方式.
- modify: 默认. 直接修改绑定的数据对象.
- new: 提交一个新的数据对象, 适用于 vuex.
- disabled: 不提交. 你可以使用getData方法手动生成并获取当前数据.
virtualization#
{ type: Boolean, default: false }
启用虚拟列表.
virtualizationPrerenderCount#
{ type: Number, default: 20 }
虚拟列表初始渲染数量.用于 SSR(服务端渲染).
treeLine#
{ type: Boolean, default: false }
显示树连接线。此功能在表格模式下无效。
treeLineOffset#
{ type: Number, default: 8 }
树连接线水平方向位移,单位:像素。
watermark#
{ type: Boolean, default: false }
向浏览器控制台输出一条水印信息.
data#
dragNode#
拖拽时的节点 stat.
dragOvering#
有东西拖拽到了此树上.
self#
此树实例, 即this
.
stats#
type 类型 = Stat<你的节点类型>[]
所有 stats, 树形结构.
statsFlat#
type 类型 = Stat<你的节点类型>[]
所有 stats, 扁平结构.
computed#
rootChildren#
type 类型 = Stat<你的节点类型>[]
树的第一级节点的数组的 stats。可以看作不存在的根节点的子集。
methods(方法)#
methods examples#
一些方法的例子,点击右上角图标查看源码。
add#
(nodeData: unknown, parent?: Stat<unknown> | null | undefined, index?: number | null | undefined): void;
增加节点. parent 为 null 时代表根节点. 示例
addMulti#
(
dataArr: any[],
parent?: Stat<any> | null,
startIndex?: number | null
): void;
增加多个连续节点. parent 为 null 时代表根节点. 示例
batchUpdate#
(task: () => any): void;
操作数据时, 会导致组件内部提交整个树的新数据. 此方法可以合并多个操作, 从而只提交一次. 示例
closeAll#
(): void
折叠所有节点. 示例
getChecked#
(withDemi?: boolean | undefined): Stat<unknown>[]
获取所有勾选的节点 stat. 参数withDemi
表示是否包含半选的节点(后代节点未完全选中). 示例
getData#
(filter?: ((data: never) => never) | undefined, root?: Stat<never> | undefined): never[];
生成并获取当前树的树形数据. 移除了 stat. 参数filter
可以对每个数据进行处理. 示例
getRootEl#
(): HTMLElement;
获取当前树的根元素.
getSiblings#
(stat: Stat<never>): Stat<never>[];
获取一个节点的同级.
getStat#
(nodeData: unknown): Stat<unknown>
根据节点数据获取节点的stat
.
getUnchecked#
(withDemi?: boolean | undefined): Stat<unknown>[]
获取所有未勾选的节点 stat. 参数withDemi
表示是否包含半选的节点(后代节点未完全选中).
has#
(nodeData: unknown): boolean
判断此树是否包含对应节点数据的stat
.
isVisible#
(statOrNodeData: Stat<unknown>|unknown): boolean;
判断节点是否可见. 如果父级折叠, 则后代不可见. 参数可以是节点数据或 stat.
iterateParent#
(stat: Stat<unknown>, opt?: {
withSelf: boolean;
} | undefined): Generator<Stat<unknown>, void, unknown>;
遍历节点的父级. 参数opt.withSelf
表示是否包含该节点. 例:
for (const parentStat of tree.iterateParent(nodeStat, { withSelf: false })) {
//
}
move#
(stat: Stat<unknown>, parent: Stat<unknown> | null, index: number): boolean;
移动节点. parent 为 null 时代表根节点. 参考add
的例子:示例
openAll#
(): void
展开所有节点. 示例
openNodeAndParents#
(nodeDataOrStat): void
打开节点及其所有父级节点,以确保该节点不会因为父级未打开而不显示. 参数 nodeDataOrStat
可以是节点数据或者节点stat
. 示例
remove#
(stat: Stat<unknown>): boolean;
删除节点.
removeMulti#
(dataArr: any[]): boolean;
删除多个节点.
updateCheck#
(): void
从末端到根, 重新计算每个节点的勾选状态.
events(事件)#
check:node#
参数: stat. 节点勾选状态改变时触发.
click:node#
参数: stat. 点击节点时触发.
close:node#
参数: stat. 折叠节点时触发.
open:node#
参数: stat. 展开节点时触发.
slots(插槽)#
default(默认插槽)#
用来自定义节点样式. 参数:
- node: 节点数据
- stat: 节点内部信息
- indentStyle: 节点缩进样式. 仅当渲染为表格时需要使用者将其应用到某列上, 一般是第一列.
- tree: 树的实例.
placeholder#
占位元素内部. 可以用来添加提示性文字. 参数:
- tree: 树的实例.
prepend#
树的根元素内开始处. 仅用于渲染为表格时添加表头(thead). 参数:
- tree: 树的实例.
append#
树的根元素内结束前. 仅用于渲染为表格时添加表底部(tfoot). 参数:
- tree: 树的实例.
Draggable#
props#
beforeDragOpen#
(stat: Stat<any>) : void | Promise<void>
钩子函数. 拖动到节点上层时打开节点前执行. 可以返回 Promise.
disableDrag#
{
type: Boolean
}
禁用此树的拖出功能.
disableDrop#
{
type: Boolean
}
禁用此树的拖入功能.
dragOpen#
{ type: Boolean, default: true }
拖动到节点上层时是否打开节点.
dragOpenDelay#
{ type: Number, default: 0 }
拖动到节点上层时打开节点前的等待的毫秒.
eachDraggable#
(stat: Stat<any>) : boolean | null
钩子函数. 设置每个节点是否可拖动. 子级如果没有指定, 会继承父级的值.
eachDroppable#
(stat: Stat<any>) : boolean | null
钩子函数. 设置每个节点是否可拖入. 子级如果没有指定, 会继承父级的值.
externalDataHandler#
(event: DragEvent) : any
当外部使用 Drag and Drop API 拖拽到树上层并结束拖拽时发生. 用来告知树此次拖拽应该接收的数据.
keepPlaceholder#
{ type: Boolean, default: false }
拖拽离开树时是否保留占位元素.
maxLevel#
{
type: Number
}
拖拽时的最大层级数. 如果拖拽将导致树超过此层数, 则会阻止拖放.
onExternalDragOver#
(event: DragEvent) : boolean
当外部使用 Drag and Drop API 拖拽到树上层时发生. 参数 event 是 Drag and Drop API 原生事件dragover
的事件对象. 返回布尔值判断是否处理该事件.
resolveStartMovePoint#
"mouse" | "default" | ((dragElement: HTMLElement) : Point)
拖动节点将被看做一个点. 拖动开始时如何获取拖动点的坐标. 默认获取节点的左上角. mouse
表示使用鼠标坐标. 或者传入函数返回自定义坐标: {x:number,y:number}
.
rootDroppable#
boolean | () : boolean
钩子函数. 设置最高级(根)是否可拖入. 默认true
.
triggerClass#
{
type: [String, Array]
} // string | string[]
触发拖拽的元素样式. 默认是节点本身. 可以设置成节点的某个子元素. 支持多个样式.
methods(方法)#
getNodeByElement#
(el: HTMLElement): Stat<any> | null
根据 HTML 元素获取节点 stat.
isDraggable#
(node: Stat<any>): boolean
判断节点是否可拖动.
isDroppable#
(node: Stat<any>): boolean
判断节点是否可拖入.
ondragstart#
(event: DragEvent) => void
HTML 拖放 API 的 dragstart 事件钩子。您可以使用 HTML 拖放 API 的 setDragImage 方法自定义拖动图像。请参考问题: https://github.com/phphe/he-tree/issues/99#issuecomment-1916000535
events(事件)#
before-drag-start#
参数: dragNode. 拖拽开始前触发.
after-drop#
参数: 无. 拖拽完成时触发. 跨树时, 仅在拖入的树触发.
change#
参数: 无. 拖拽完成且造成改变时触发. 跨树时, 两棵树都会触发.
enter#
参数: DragEvent. 拖拽进入树元素边界时触发.
leave#
参数: DragEvent. 拖拽离开树元素边界时触发.
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 | 0 // 是否勾选. 0表示后代节点部分勾选
draggable: boolean | null // 是否可拖动. null表示继承父级.
droppable: boolean | null // 是否可拖入. null表示继承父级.
style: any // 自定义样式. 支持Vue的style格式.
class: any // 自定义样式类. 支持Vue的class格式.
}
dragContext#
拖拽时的相关信息对象,例子. 包括属性: startInfo, targetInfo, dragNode, startTree, targetTree. 引入:
// vue3
import { dragContext } from '@he-tree/vue'
// vue2
import { dragContext } from '@he-tree/vue/vue2'
startInfo#
类型: StartInfo. 拖拽开始的信息.
targetInfo#
类型: StartInfo. 拖拽的目标的信息.
dragNode#
类型: Stat. 拖拽的节点.
startTree#
Draggable 组件实例. 拖拽的起始树.
targetTree#
Draggable 组件实例. 拖拽的目标树.
closestNode#
类型: Stat|null. 拖拽时最近的节点.可以在 eachDroppable 中使用.
Example - dragContext#
在eachDroppable中通过 dragContext 获取 dragNode,达成效果:奇数节点只接收奇数节点,偶数节点只接收偶数节点。
StartInfo#
{
tree: DraggableTreeType; // Draggable组件的实例
dragNode: Stat<any>; // 拖拽节点
parent: Stat<any> | null; // 拖拽节点父级
siblings: Stat<any>[]; // 拖拽节点同级
indexBeforeDrop: number; // 拖拽节点在拖拽结束前的索引
}