sl-vue-tree
    TypeScript icon, indicating that this package has built-in type declarations

    1.8.5 • Public • Published

    sl-vue-tree

    Customizable draggable tree component for Vue.js

    preview

    demo

    install

    npm i sl-vue-tree

    Quick start

     
    <div id="app">
      <sl-vue-tree v-model="nodes"/>
    </div>
     
    <link rel="stylesheet" href="dist/sl-vue-tree-dark.css">
    <script src="dist/sl-vue-tree.js"></script>
     
    <script>
     
      var nodes = [
        {title: 'Item1', isLeaf: true},
        {title: 'Item2', isLeaf: true, data: { visible: false }},
        {title: 'Folder1'},
        {
          title: 'Folder2', isExpanded: true, children: [
            {title: 'Item3', isLeaf: true},
            {title: 'Item4', isLeaf: true}
          ]
        }
      ];
     
      new Vue({
        el: '#app',
        components: { SlVueTree },
        data: function () {
         return {
           nodes: nodes
         }
        }
      });
      
    </script>    
     

    The value property is an array of ISlTreeNodeModel nodes:

    interface ISlTreeNodeModel<TDataType> {
        title: string;
        isLeaf?: boolean;
        children?: ISlTreeNodeModel<TDataType>[];
        isExpanded?: boolean;
        isSelected?: boolean;
        isDraggable?: boolean;
        isSelectable?: boolean;
        data?: TDataType; // any serializable user data
    }

    For convenience the component's events return ISlTreeNode objects. Those actually are ISlTreeNodeModel with some computed props:

    interface ISlTreeNode<TDataType> extends ISlTreeNodeModel<TDataType> {
        isFirstChild: boolean;
        isLastChild: boolean;
        isVisible: boolean; // node is visible if all of its parents are expanded
        level: number; // nesting level
        ind: number; // index in the array of siblings 
        path: number[]; // path to node as array of indexes, for example [2, 0, 1] in the example above is path to `Item4` 
        pathStr: string; // serialized path to node
        children: ISlTreeNode<TDataType>[];
    }

    You can get the list of ISlTreeNode from the computed slVueTree.nodes property

    Props

    prop type default description
    value ISlTreeNodeModel[] [] An array of nodes to show. Each node is represented by ISlTreeNodeModel interface
    allowMultiselect Boolean true Disable or enable the multiselect feature
    allowToggleBranch Boolean true Disable or enable the expand/collapse button
    edgeSize Number 3 Offset in pixels from top and bottom for folder-node element. While dragging cursor is in that offset, the dragging node will be placed before or after the folder-node instead of being placed inside the folder.
    scrollAreaHeight Number 70 Offset in pixels from top and bottom for the component element. While dragging cursor is in that area, the scrolling starts.
    maxScrollSpeed Number 20 The scroll speed is relative to the cursor position. Defines the max scroll speed.
    multiselectKey String/String[] ['ctrlKey', 'metaKey'] The keys for multiselect mode. Allowed values are ['ctrlKey', 'metaKey', 'altKey']

    Computed props

    prop type description
    nodes ISlTreeNode[] List of nodes with some computed props. See ISlTreeNode interface.
    cursorPosition ICursorPosition Represents the current cursor position that describes the action that will be applied to the dragged node on mouseup event. See ICursorPosition interface
    selectionSize Number The count of selected nodes
    dragSize Number The count of selected and draggable nodes
    isDragging Boolean True if nodes are dragging
    interface ICursorPosition<TDataType> {
      node: ISlTreeNode<TDataType>;
      placement: 'before' | 'inside' | 'after';
    }  
    

    Events

    event callback arguments description
    input nodes: ISlTreeNodeModel[] triggers for any changes to value property
    select selectedNodes: ISlTreeNode[], event: MouseEvent triggers when a node has been selected/deselected
    toggle toggledNode: ISlTreeNode, event: MouseEvent triggers when a node has been collapsed/expanded
    drop draggingNodes: ISlTreeNode[], position: ICursorPosition, event: MouseEvent triggers when dragging nodes have been dropped
    nodeclick node: ISlTreeNode, event: MouseEvent handle click event on node
    nodedblclick node: ISlTreeNode, event: MouseEvent handle dblclick event on node
    nodecontextmenu node: ISlTreeNode, event: MouseEvent handle contextmenu event on node
    externaldrop cursorPosition: ICursorPosition, event: MouseEvent handle drop event for external items demo

    Methods

    method description
    getNode(path: number[]): ISlTreeNode Find the node by using its path
    traverse(cb: (node: ISlTreeNode, nodeModel: ISlTreeNodeModel, siblings: ISlTreeNodeModel[]) => boolean) Helpful method to traverse all nodes. The traversing will be stopped if callback returns false.
    updateNode(path: number[], patch: Partial) Update the node by using its path
    select(path: number[], addToSelection = false) Select the node by using its path
    getNodeEl(): HTMLElement Get the node HTMLElement by using its path
    getSelected(): ISlTreeNode[] Get selected nodes
    insert(position: ICursorPosition, nodeModel: ISlTreeNodeModel) Insert nodes by the current cursor position.
    remove(paths: number[][]) Remove nodes by paths. For example .remove([[0,1], [0,2]])
    getFirstNode(): ISlTreeNode Get the first node in the tree
    getLastNode(): ISlTreeNode Get the last node in the tree
    getNextNode(path: number[], filter?: (node: ISlTreeNode) => boolean): ISlTreeNode; Get the next node. You can skip the next nodes by using filter
    getPrevNode(path: number[], filter?: (node: ISlTreeNode) => boolean): ISlTreeNode; Get the previous node. You can skip the previous nodes by using filter

    Slots

    slot context description
    title ISlTreeNode Slot for item title
    toggle ISlTreeNode Slot for expand/collapse button
    sidebar ISlTreeNode Sidebar content
    draginfo SlVueTree Slot that follows the mouse cursor while dragging. By default shows the dragging nodes count.
    empty-node ISlTreeNode Slot for (optional) message when folder is open, but empty

    IE 11 support

    You must add a babel-polyfill for it to work correctly in IE11
    See IE11 example

    Examples

    Add a folder or item icon via title slot

    <sl-vue-tree v-model="nodes">
        <template slot="title" slot-scope="{ node }">
     
          <span class="item-icon">
            <i class="fa fa-file" v-if="node.isLeaf"></i>
            <i class="fa fa-folder" v-if="!node.isLeaf"></i>
          </span>
        
          {{ node.title }}
          
        </template>
    </sl-vue-tree>
     

    Select all nodes

    slVueTree.traverse((node, nodeModel, path) => {
        Vue.set(nodeModel, 'isSelected', true);
    })

    Handle keydown and keyup events via getNextNode and getPrevNode methods

    demo

    Contributing

    see CONTRIBUTING.md

    Changelog

    v1.8.5

    v1.8.4

    v1.8.3

    v1.8.1

    v1.8.0

    • added empty-node slot

    v1.7.1

    • added multiselectKey property

    v1.7.0

    • added isSelectable and isDraggable flags

    v1.6.0

    v1.5.1

    v1.5.0

    • SlVueTree.select method added
    • SlVueTree.@nodeclick event fixed

    Install

    npm i sl-vue-tree

    DownloadsWeekly Downloads

    2,130

    Version

    1.8.5

    License

    MIT

    Unpacked Size

    394 kB

    Total Files

    26

    Last publish

    Collaborators

    • holiber