Guide
Installation#
# Vue3
npm i --save @he-tree/vue
# Vue2. Only Vue@2.6 supported
npm i --save @he-tree/vue @vue/composition-api
!!! IMPORTANT, if use Vue2, he-tree does not work with Vue2.7, you can copy this example folder to start: https://github.com/phphe/he-tree/tree/dev/examples/example-vue2-no-ts
CDN#
Import#
Vue3#
import { BaseTree, Draggable } from '@he-tree/vue'
import '@he-tree/vue/style/default.css'
Vue2#
import { BaseTree, Draggable } from '@he-tree/vue/vue2'
import '@he-tree/vue/style/default.css'
BaseTree is the base tree component. Draggable component extends BaseTree.
Examples#
Example Projects#
Basic#
Fold and Checkbox#
Only function provided, you need add your own ui by slot. stat.checked has 3 value:true, false, 0. 0 mean only some child checked. When the parent node is checked, all child nodes will be checked. When all child nodes are checked, the parent node will be checked. When some child nodes are checked, the checked value of the parent node becomes 0. If you need other checkbox logic, don't stick to the "checked" attribute. You can add another attribute to the node to achieve it. Related methods: getChecked, getUnchecked, updateCheck, openAll, closeAll, openNodeAndParents, isVisible.
Drag and Drop#
Material Design and Tree line#
Indent#
Don't set node indent by css. Use prop indent.
Data#
Follow is example data. Key children can be modified by prop childrenKey, text can be modified by prop textKey.
{
text: 'Root',
children: [
{text: 'Child'}
]
}
Data update by component#
First use v-model. The component will clone data as inner data. When inner data changed, there are 3 ways to emit new data. It modifies binded data directly by default. Use prop updateBehavior to set the new data emit behavior. Available values of updateBehavior:
- modify: modify binded data. For example, when a node changes, only that node is modified while the data object binded to
v-modelremains the same. - new: emit new data, suit for vuex. The data object binded to
v-modelwill be a new object. More check below's Vuex example. - disabled: don't do anything. You can use getData method to generate and get new data when you want.
Vuex Example#
<template>
<YourTree v-model="treeData" />
</template>
<script>
export default {
computed: {
treeData: {
get() {
return this.$store.state.treeData
},
set(value) {
this.$store.commit('updateTreeData', value)
},
},
},
}
</script>
Data update by user#
The component creates stat object for every node. It stores runtime info, such as open, parent, children, level. You can use prop statHandler handle each stat after they created. Related data: stats, statsFlat.
The methods to handle data: getStat, has, updateCheck, getChecked, getUnchecked, openAll, closeAll, isVisible, move, add, addMulti, remove, removeMulti, iterateParent, getSiblings, getData.
Material Design#
Code and demo. The library provides predefined simple styles with Material Design. To enable them, follow these steps:
Import CSS:
import '@he-tree/vue/style/default.css' import '@he-tree/vue/style/material-design.css'jsAdd CSS class
mtl-tree:<Draggable class="mtl-tree" v-model="treeData" />htmlThe library includes a collapsible icon component
OpenIcon, which you can use as your collapsible icon.material-design.cssincludes a simple checkbox stylemtl-checkbox, which you can apply to your checkboxes for decoration. Code and demo.
Tree Line#
Code and Demo. Enable it with the treeLine prop and set the offset with the treeLineOffset prop. This feature is not valid in table mode.
The style of the tree line can be controlled by css classes. For example:
tree-line: sets the color of the tree line..your-tree .tree-line { background: red; }csstree-vline: sets the color and width of the vertical tree line..your-tree .tree-vline { background: red; width: 1px; }csstree-hline: sets the color, width, and height of the horizontal tree line..your-tree .tree-hline { background: red; height: 1px; width: 10px; }css
Virtual List#
Set height or max-height fot tree or its parent, or it will not work.Related props: virtualization, virtualizationPrerenderCount
Virtual list is implemented by another library of mine: virtual-list.
Iterate tree-data#
Use walkTreeData
// Vue3
import { walkTreeData } from '@he-tree/vue'
// Vue2
import { walkTreeData } from '@he-tree/vue/vue2'
walkTreeData(node, (node, index, parent) => {}, {
childrenKey: 'children',
reverse: false,
childFirst: false,
})
Tree-data examples, childrenKey must be same with the data's:
let treeData1 = { a: 1, children: [{ b: 1 }] }
let treeData2 = [{ a: 1, children: [{ b: 1 }] }, { c: 1 }]
let treeData3 = { a: 1, sub: [{ b: 1 }] }
Typescript type：
declare function walkTreeData<T extends Object>(
obj: T | T[],
handler: WalkTreeDataHandler<T>,
opt?: WalkTreeDataOptions
): void
declare type WalkTreeDataHandler<T> = (
node: T,
index: number,
parent: T | null,
path: TreeDataPath
) => void | false | 'skip children' | 'skip siblings'
declare type WalkTreeDataOptions = {
childrenKey?: string
reverse?: boolean
childFirst?: boolean
}
WalkTreeDataHandler return values:
false: stop iteratingskip children: skip current node's child nodesskip siblings: skip current node's siblings- other values: no effect
WalkTreeDataOptions:
childrenKey:keyof tree-data's children, defaultchildren.reverse: iterate from last to firstchildFirst: iterate child node first
Example, find all level-2 nodes:
let results = []
walkTreeData(tree.rootChildren, (stat) => {
if (stat.level === 2) {
results.push(stat)
return `skip children`
}
})
Open all nodes by default#
Related props: defaultOpen
Display from right to left#
Related props: rtl
Tree start from bottom to top#
Related props: btt
Render as Table#
| action | Text | Level |
|---|---|---|
| Projects | 1 | |
| Frontend | 2 | |
| Vue | 3 | |
| Nuxt | 4 | |
| React | 3 | |
| Next | 4 | |
| Angular | 3 | |
| Backend | 2 | |
| Photos | 1 | |
| Videos | 1 | |
| action | Text | Level |
Render as table and virtual list can work at the same time. Related props: table. Use slot prepend, append to add table head and foot. Draggable table is pro feature, get pro to enable it.
About Drag and Drop#
Drag Trigger Element#
Related props: triggerClass
Draggable and Droppable#
Use stat to control draggable and droppable for each node. Also can be controled by hooks. Related props: disableDrag, disableDrop, eachDraggable, eachDroppable, rootDroppable, maxLevel
Max Level#
Related props: maxLevel
Drag Open#
When drag over a node, it will be open by default. Use prop dragOpen to change it. Use prop dragOpenDelay to set delay time. Hook prop: beforeDragOpen
Placeholder#
It is the drop area when drag. It will use a light blue box to mark droppable position when drag. Use slot placeholder to customize it, such as add tips.
When drag leave tree, placeholder will be removed. Use prop keepPlaceholder to keep placeholder even leave tree.
It has css class name drag-placeholder. You can use the name to customize its style.
Runtime info when drag#
In drag process, runtime info is in an exported object dragContext.
// vue3
import { dragContext } from '@he-tree/vue'
// vue2
import { dragContext } from '@he-tree/vue/vue2'
Drop from outside#
When dropped from outside by Drag and Drop API, you can use hook props: onExternalDragOver, externalDataHandler to handle it. he-tree can work with any code which use HTML5 Drag and Drop API.
Touch & Mobile#
It is based on HTML5 Drag and Drop API. So it works in any device that supports Drag and Drop API. For others, you can try Drag and Drop API polyfill.
NOTICE: In mobile, user need touch and hold to trigger drag.
Watermark#
This is disabled by default. It prints a watermark information to browser console. Use prop watermark to disable it.
Pro#
pro has follow advanced features.
Drag cross trees.
Drag copy: copy node when drag start.
Draggable table.