Tree: update drag and drop docs (#10396)

.github/ISSUE_TEMPLATE.md

@@ -1,4 +1,12 @@
 <!--
+重要: 请使用以下链接创建新 issue
+
+  https://elementui.github.io/issue-generator
+
+未通过以上链接创建的 issue 会被机器人直接关闭。
+
+########
+
 IMPORTANT: Please use the following link to create a new issue:
 
   https://elementui.github.io/issue-generator

examples/docs/en-US/tree.md

@@ -151,6 +151,42 @@
     }]
   }];
   
+  const data6 = [{
+    label: 'Level one 1',
+    children: [{
+      label: 'Level two 1-1',
+      children: [{
+        label: 'Level three 1-1-1'
+      }]
+    }]
+  }, {
+    label: 'Level one 2',
+    children: [{
+      label: 'Level two 2-1',
+      children: [{
+        label: 'Level three 2-1-1'
+      }]
+    }, {
+      label: 'Level two 2-2',
+      children: [{
+        label: 'Level three 2-2-1'
+      }]
+    }]
+  }, {
+    label: 'Level one 3',
+    children: [{
+      label: 'Level two 3-1',
+      children: [{
+        label: 'Level three 3-1-1'
+      }]
+    }, {
+      label: 'Level two 3-2',
+      children: [{
+        label: 'Level three 3-2-1'
+      }]
+    }]
+  }];
+
   let id = 1000;
 
   const regions = [{
@@ -191,6 +227,30 @@
       handleNodeClick(data) {
         console.log(data);
       },
+      handleDragStart(node, ev) {
+        console.log('drag start', node);
+      },
+      handleDragEnter(draggingNode, dropNode, ev) {
+        console.log('tree drag enter: ', dropNode.label);
+      },
+      handleDragLeave(draggingNode, dropNode, ev) {
+        console.log('tree drag leave: ', dropNode.label);
+      },
+      handleDragOver(draggingNode, dropNode, ev) {
+        console.log('tree drag over: ', dropNode.label);
+      },
+      handleDragEnd(draggingNode, dropNode, dropType, ev) {
+        console.log('tree drag end: ', dropNode && dropNode.label, dropType);
+      },
+      handleDrop(draggingNode, dropNode, dropType, ev) {
+        console.log('tree drop: ', dropNode.label, dropType);
+      },
+      allowDrop(draggingNode, dropNode) {
+        return dropNode.data.label !== 'Level two 3-1';
+      },
+      allowDrag(draggingNode) {
+        return draggingNode.data.label.indexOf('Level three 3-1-1') === -1;
+      },
       loadNode(node, resolve) {
         if (node.level === 0) {
           return resolve([{ name: 'Root1' }, { name: 'Root2' }]);
@@ -300,6 +360,7 @@
         data3,
         data4: JSON.parse(JSON.stringify(data2)),
         data5: JSON.parse(JSON.stringify(data2)),
+        data6,
         regions,
         defaultProps,
         props,
@@ -998,7 +1059,7 @@ Only one node among the same level can be expanded at one time.
 
 ### Draggable
 
-Tree nodes can be drag and drop.
+You can drag and drop Tree nodes by adding a `draggable` attribute.
 
 :::demo
 ```html
@@ -1076,7 +1137,7 @@ Tree nodes can be drag and drop.
         console.log('tree drag over: ', dropNode.label);
       },
       handleDragEnd(draggingNode, dropNode, dropType, ev) {
-        console.log('tree drag end: ', dropNode.label, dropType);
+        console.log('tree drag end: ', dropNode && dropNode.label, dropType);
       },
       handleDrop(draggingNode, dropNode, dropType, ev) {
         console.log('tree drop: ', dropNode.label, dropType);
@@ -1160,12 +1221,12 @@ Tree nodes can be drag and drop.
 | current-change | triggers when current node changes       | two parameters: node object corresponding to the current node, `node` property of TreeNode |
 | node-expand    | triggers when current node open          | three parameters: node object corresponding to the node opened, `node` property of TreeNode, TreeNode itself |
 | node-collapse  | triggers when current node close         | three parameters: node object corresponding to the node closed, `node` property of TreeNode, TreeNode itself |
-| node-drag-start | triggers when dragging start   | two parameters: node object corresponding to the dragging node、event. |
+| node-drag-start | triggers when dragging starts  | two parameters: node object corresponding to the dragging node, event. |
-| node-drag-enter | triggers when dragging node enters a node  | three parameters: node object corresponding to the dragging node、node object corresponding to the dragging enter node、event. |
+| node-drag-enter | triggers when the dragging node enters another node  | three parameters: node object corresponding to the dragging node, node object corresponding to the entering node, event. |
-| node-drag-leave | triggers when dragging node leaves a node  | three parameters: node object corresponding to the dragging node、node object corresponding to the dragging leave node、event.  |
+| node-drag-leave | triggers when the dragging node leaves a node  | three parameters: node object corresponding to the dragging node, node object corresponding to the leaving node, event.  |
-| node-drag-over | triggers when dragging over a node（like browser mouseover event） | three parameters: node object corresponding to the dragging node、node object corresponding to the dragging over node、event.  |
+| node-drag-over | triggers when dragging over a node (like mouseover event) | three parameters: node object corresponding to the dragging node, node object corresponding to the dragging over node, event.  |
-| node-drag-end  | triggers when dragging end  | four parameters: node object corresponding to the dragging node、node object corresponding to the dragging end node、node drop type (before、after、inner)、event. |
+| node-drag-end  | triggers when dragging ends  | four parameters: node object corresponding to the dragging node, node object corresponding to the dragging end node (may be `undefined`), node drop type (before / after / inner), event. |
-| node-drop  | triggers after dragging and dropping onto a node  | four parameters: node object corresponding to the dragging node、node object corresponding to the dragging end node、node drop type (before、after、inner)、event. |
+| node-drop  | triggers after the dragging node is dropped | four parameters: node object corresponding to the dragging node, node object corresponding to the dropped node, node drop type (before / after / inner), event. |
 
 ### Scoped slot
 | name | Description |

examples/docs/es/tree.md

@@ -151,6 +151,42 @@
     }]
   }];
   
+  const data6 = [{
+    label: 'Level one 1',
+    children: [{
+      label: 'Level two 1-1',
+      children: [{
+        label: 'Level three 1-1-1'
+      }]
+    }]
+  }, {
+    label: 'Level one 2',
+    children: [{
+      label: 'Level two 2-1',
+      children: [{
+        label: 'Level three 2-1-1'
+      }]
+    }, {
+      label: 'Level two 2-2',
+      children: [{
+        label: 'Level three 2-2-1'
+      }]
+    }]
+  }, {
+    label: 'Level one 3',
+    children: [{
+      label: 'Level two 3-1',
+      children: [{
+        label: 'Level three 3-1-1'
+      }]
+    }, {
+      label: 'Level two 3-2',
+      children: [{
+        label: 'Level three 3-2-1'
+      }]
+    }]
+  }];
+
   let id = 1000;
 
   const regions = [{
@@ -191,6 +227,30 @@
       handleNodeClick(data) {
         console.log(data);
       },
+      handleDragStart(node, ev) {
+        console.log('drag start', node);
+      },
+      handleDragEnter(draggingNode, dropNode, ev) {
+        console.log('tree drag enter: ', dropNode.label);
+      },
+      handleDragLeave(draggingNode, dropNode, ev) {
+        console.log('tree drag leave: ', dropNode.label);
+      },
+      handleDragOver(draggingNode, dropNode, ev) {
+        console.log('tree drag over: ', dropNode.label);
+      },
+      handleDragEnd(draggingNode, dropNode, dropType, ev) {
+        console.log('tree drag end: ', dropNode && dropNode.label, dropType);
+      },
+      handleDrop(draggingNode, dropNode, dropType, ev) {
+        console.log('tree drop: ', dropNode.label, dropType);
+      },
+      allowDrop(draggingNode, dropNode) {
+        return dropNode.data.label !== 'Level two 3-1';
+      },
+      allowDrag(draggingNode) {
+        return draggingNode.data.label.indexOf('Level three 3-1-1') === -1;
+      },
       loadNode(node, resolve) {
         if (node.level === 0) {
           return resolve([{ name: 'Root1' }, { name: 'Root2' }]);
@@ -300,6 +360,7 @@
         data3,
         data4: JSON.parse(JSON.stringify(data2)),
         data5: JSON.parse(JSON.stringify(data2)),
+        data6,
         regions,
         defaultProps,
         props,
@@ -998,7 +1059,7 @@ Solo puede ser expandido un nodo del mismo nivel a la vez.
 
 ### Draggable
 
-Tree nodes can be drag and drop.
+You can drag and drop Tree nodes by adding a `draggable` attribute.
 
 :::demo
 ```html
@@ -1076,7 +1137,7 @@ Tree nodes can be drag and drop.
         console.log('tree drag over: ', dropNode.label);
       },
       handleDragEnd(draggingNode, dropNode, dropType, ev) {
-        console.log('tree drag end: ', dropNode.label, dropType);
+        console.log('tree drag end: ', dropNode && dropNode.label, dropType);
       },
       handleDrop(draggingNode, dropNode, dropType, ev) {
         console.log('tree drop: ', dropNode.label, dropType);
@@ -1158,12 +1219,12 @@ Tree nodes can be drag and drop.
 | current-change    | cambia cuando el nodo actual cambia      | dos parámetros: objeto nodo que se corresponde al nodo actual y propiedad `node` del TreeNode |
 | node-expand       | se lanza cuando el nodo actual se abre   | tres parámetros: el objeto del nodo abierto, propiedad `node` de TreeNode y el TreeNode en si |
 | node-collapse     | se lanza cuando el nodo actual se cierra | tres parámetros: el objeto del nodo cerrado, propiedad `node` de TreeNode y el TreeNode en si |
-| node-drag-start | triggers when dragging start   | two parameters: node object corresponding to the dragging node、event. |
+| node-drag-start | triggers when dragging starts  | two parameters: node object corresponding to the dragging node, event. |
-| node-drag-enter | triggers when dragging node enters a node  | three parameters: node object corresponding to the dragging node、node object corresponding to the dragging enter node、event. |
+| node-drag-enter | triggers when the dragging node enters another node  | three parameters: node object corresponding to the dragging node, node object corresponding to the entering node, event. |
-| node-drag-leave | triggers when dragging node leaves a node  | three parameters: node object corresponding to the dragging node、node object corresponding to the dragging leave node、event.  |
+| node-drag-leave | triggers when the dragging node leaves a node  | three parameters: node object corresponding to the dragging node, node object corresponding to the leaving node, event.  |
-| node-drag-over | triggers when dragging over a node（like browser mouseover event） | three parameters: node object corresponding to the dragging node、node object corresponding to the dragging over node、event.  |
+| node-drag-over | triggers when dragging over a node (like mouseover event) | three parameters: node object corresponding to the dragging node, node object corresponding to the dragging over node, event.  |
-| node-drag-end  | triggers when dragging end  | four parameters: node object corresponding to the dragging node、node object corresponding to the dragging end node、node drop type (before、after、inner)、event. |
+| node-drag-end  | triggers when dragging ends  | four parameters: node object corresponding to the dragging node, node object corresponding to the dragging end node (may be `undefined`), node drop type (before / after / inner), event. |
-| node-drop  | triggers after dragging and dropping onto a node  | four parameters: node object corresponding to the dragging node、node object corresponding to the dragging end node、node drop type (before、after、inner)、event. |
+| node-drop  | triggers after the dragging node is dropped | four parameters: node object corresponding to the dragging node, node object corresponding to the dropped node, node drop type (before / after / inner), event. |
 
 ### Scoped slot
 | name | Description |

examples/docs/zh-CN/tree.md

@@ -240,23 +240,26 @@
       handleDragStart(node, ev) {
         console.log('drag start', node);
       },
-      handleDragEnter(node, ev) {
+      handleDragEnter(draggingNode, dropNode, ev) {
-        console.log('tree drag enter: ', node.label);
+        console.log('tree drag enter: ', dropNode.label);
       },
-      handleDragLeave(node, ev) {
+      handleDragLeave(draggingNode, dropNode, ev) {
-        console.log('tree drag leave: ', node.label);
+        console.log('tree drag leave: ', dropNode.label);
       },
-      handleDragEnd(from, target, position, ev) {
+      handleDragOver(draggingNode, dropNode, ev) {
-        console.log('tree drag end: ', target.label);
+        console.log('tree drag over: ', dropNode.label);
-        if (position !== null) {
-          console.log(`target position: parent node: ${position.parent.label}, index: ${position.index}`);
-        }
       },
-      allowDrop(from, target) {
+      handleDragEnd(draggingNode, dropNode, dropType, ev) {
-        return target.data.label !== '二级 3-1';
+        console.log('tree drag end: ', dropNode && dropNode.label, dropType);
       },
-      allowDrag(node) {
+      handleDrop(draggingNode, dropNode, dropType, ev) {
-        return node.data.label.indexOf('三级 3-1-1') === -1;
+        console.log('tree drop: ', dropNode.label, dropType);
+      },
+      allowDrop(draggingNode, dropNode) {
+        return dropNode.data.label !== '二级 3-1';
+      },
+      allowDrag(draggingNode) {
+        return draggingNode.data.label.indexOf('三级 3-1-1') === -1;
       },
       loadNode(node, resolve) {
         if (node.level === 0) {
@@ -1153,7 +1156,7 @@
         console.log('tree drag over: ', dropNode.label);
       },
       handleDragEnd(draggingNode, dropNode, dropType, ev) {
-        console.log('tree drag end: ', dropNode.label, dropType);
+        console.log('tree drag end: ', dropNode && dropNode.label, dropType);
       },
       handleDrop(draggingNode, dropNode, dropType, ev) {
         console.log('tree drop: ', dropNode.label, dropType);
@@ -1237,14 +1240,14 @@
 | check-change   | 节点选中状态发生变化时的回调 | 共三个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、节点本身是否被选中、节点的子树中是否有被选中的节点 |
 | check          | 当复选框被点击的时候触发 | 共两个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、树目前的选中状态对象，包含 checkedNodes、checkedKeys、halfCheckedNodes、halfCheckedKeys 四个属性 |
 | current-change | 当前选中节点变化时触发的事件 | 共两个参数，依次为：当前节点的数据，当前节点的 Node 对象          |
-| node-expand    | 节点被展开时触发的事件    | 共三个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、节点对应的 Node、节点组件本身。 |
+| node-expand    | 节点被展开时触发的事件    | 共三个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、节点对应的 Node、节点组件本身 |
-| node-collapse  | 节点被关闭时触发的事件    | 共三个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、节点对应的 Node、节点组件本身。 |
+| node-collapse  | 节点被关闭时触发的事件    | 共三个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、节点对应的 Node、节点组件本身 |
-| node-drag-start | 节点开始拖拽时触发的事件  | 共两个参数，依次为：被拖拽节点对应的 Node、event。 |
+| node-drag-start | 节点开始拖拽时触发的事件  | 共两个参数，依次为：被拖拽节点对应的 Node、event |
-| node-drag-enter | 拖拽进入其他节点时触发的事件  | 共三个参数，依次为：被拖拽节点对应的 Node、所进入节点对应的 Node、event。|
+| node-drag-enter | 拖拽进入其他节点时触发的事件  | 共三个参数，依次为：被拖拽节点对应的 Node、所进入节点对应的 Node、event |
-| node-drag-leave | 拖拽离开某个节点时触发的事件  | 共三个参数，依次为：被拖拽节点对应的 Node、所离开节点对应的 Node、event。 |
+| node-drag-leave | 拖拽离开某个节点时触发的事件  | 共三个参数，依次为：被拖拽节点对应的 Node、所离开节点对应的 Node、event |
-| node-drag-over | 在拖拽节点时触发的事件（类似浏览器的 mouseover 事件） | 共三个参数，依次为：被拖拽节点对应的 Node、当前进入节点对应的 Node、event。 |
+| node-drag-over | 在拖拽节点时触发的事件（类似浏览器的 mouseover 事件） | 共三个参数，依次为：被拖拽节点对应的 Node、当前进入节点对应的 Node、event |
-| node-drag-end  | 拖拽结束时（可能未成功）触发的事件  | 共四个参数，依次为：被拖拽节点对应的 Node、结束拖拽时最后进入的节点（可能为空）、被拖拽节点的放置位置（before、after、inner）、event。|
+| node-drag-end  | 拖拽结束时（可能未成功）触发的事件  | 共四个参数，依次为：被拖拽节点对应的 Node、结束拖拽时最后进入的节点（可能为空）、被拖拽节点的放置位置（before、after、inner）、event |
-| node-drop  | 拖拽成功完成时触发的事件  | 共四个参数，依次为：被拖拽节点对应的 Node、结束拖拽时最后进入的节点、被拖拽节点的放置位置（before、after、inner）、event。|
+| node-drop  | 拖拽成功完成时触发的事件  | 共四个参数，依次为：被拖拽节点对应的 Node、结束拖拽时最后进入的节点、被拖拽节点的放置位置（before、after、inner）、event |
 
 ### Scoped slot
 | name | 说明 |

packages/tree/src/tree.vue

@@ -336,7 +336,7 @@
         event.dataTransfer.effectAllowed = 'move';
         event.dataTransfer.setData('text/plain', treeNode.node.label);
         dragState.draggingNode = treeNode;
-        this.$emit('node-drag-start', event, treeNode.node);
+        this.$emit('node-drag-start', treeNode.node, event);
       });
 
       this.$on('tree-node-drag-over', (event, treeNode) => {