@vdnd/v3

# 简介简单易用的拖拽放置 vue 组件库。 vdnd 只抽象出拖拽了什么以及将其放置在了哪里，而不实现具体的放置效果。 # 示例 ```typescript import { ref } from 'vue'; import { push, remove } from '@vdnd/v3'; import { useMouseDnd, MouseDnd, DndSource, DndDropzone } from '@vdnd/v3'; import type { DropEvent } from '@vdnd/v3'; const dnd = useMouseDnd<number>({ strict: true, }); const left = ref([1, 2, 3]); const right = ref<number[]>([]); const onDrop = (e: DropEvent<number>) => { if (e.source.label === 'left' && e.dropzone.label === 'right') { push(right, remove(left, e.source.value!)); } }; ``` ```html <MouseDnd :instance="dnd" class="example" @drop="onDrop"> <div> <DndSource v-for="(number, index) in left" :key="index" label="left" :value="index"> {{ number }} </DndSource> </div> <DndDropzone label="right"> <div v-if="!right.length" class="empty">拖到这里来</div> <div v-for="(number, index) in right" :key="index" class="right-box">{{ number }}</div> </DndDropzone> </MouseDnd> ``` [在线示例](http://zbd329.top/vdnd/?lang=zh-cn&index=0) # API ## 插件 ### NativeDndPlugin 注册全局组件：`NativeDnd`、`DndSource`、`DndDropzone`、`DndHandle`。 ### MouseDndPlugin 注册全局组件：`MouseDnd`、`DndSource`、`DndDropzone`、`DndHandle`。 ### TouchDndPlugin 注册全局组件：`TouchDnd`、`DndSource`、`DndDropzone`、`DndHandle`。 ## 组件 ### DndProvider `DndProvider` 用于渲染**拖放容器**：只有来自该容器内的拖放（拖拽放置）交互才会被 `DndProvider` 感知。 vdnd 提供了 `NativeDnd`、`MouseDnd` 和 `TouchDnd` 三类 `DndProvider`，它们使用不同的事件描述拖放交互，例如： - `NativeDnd` 将 `dragstart` 事件的触发视为交互的开始； - `MouseDnd` 将 `mousedown` 和 `mousemove` 事件的接连触发视为交互的开始； - `TouchDnd` 将 `touchstart` 和 `touchmove` 事件的接连触发视为交互的开始。 #### 属性 | 名称 | 类型 | 说明 | 是否必选 | 默认值 | | -------- | ------ | ------------------------------------------- | -------- | ------ | | tag | string | 渲染**拖放容器**所使用的 html 标签 | 否 | 'div' | | instance | object | [拖放交互实例.md](./docs/zh-cn/instance.md) | 是 | | #### 插槽 | 名称 | 说明 | 参数 | 后备内容 | | ------- | -------------------- | ---- | -------- | | default | **拖放容器**的子节点 | 无 | 空 | #### 事件 | 名称 | 说明 | | ------------ | ------------------------------ | | drag | `API#DndSource` | | drag:start | `API#DndSource` | | drag:prevent | `API#DndSource` | | drag:enter | `API#DndDropzone` | | drag:over | `API#DndDropzone` | | drag:leave | `API#DndDropzone` | | drop | `API#DndDropzone` | | drag:end | `API#DndDropzone` | | initialized | `DndProvider` 初始化完成后触发 | 更多信息请参考[拖放交互事件.md](./docs/zh-cn/event.md)。 #### 组件实例 `DndProvider` 不使用 `expose` 暴露任何内容。 ### DndSource `DndSource` 用于渲染**源**：只有尝试拖拽**拖放容器**中的**源**时，`DndProvider` 才能感知到拖拽的发生。 #### 属性 | 名称 | 类型 | 说明 | 是否必选 | 默认值 | | --------- | ------- | ------------------------------------------------ | -------- | ------------------------------------- | | tag | string | 渲染**源**所使用的 html 标签 | 否 | 'div' | | label | string | 为**源**绑定一个标签，一般用于分组 | 否 | | | value | any | 为**源**绑定一个值，在某个组内，该值通常是唯一的 | 否 | | | draggable | boolean | 是否允许拖拽 | 否 | true | | dropzone | boolean | 是否同时作为**放置区域** | 否 | false | | droppable | boolean | 是否允许放置 | 否 | false；true，当 `dropzone` 为 true 时 | 当我们尝试拖拽一个可拖拽的**源**时，拖放交互开始，`DndProvider` 触发 `drag:start` 事件，并将该**源**作为**当前拖拽源**。反之，拖放交互被阻止，`DndProvider` 触发 `drag:prevent` 事件。拖放交互开始后，`DndProvider` 将会定时触发 `drag` 事件。 `DndProvider` 触发事件时，会将相关的**源**作为参数，并支持访问**源**的属性，例如 `label` 和 `value`：它们可以帮助我们快速识别出**源**的身份，并以此决定后续的操作。 > `label` 属性只是起到标记作用，vdnd 内部并没有任何关于分组的逻辑。 **源**可以同时作为**放置区域**，这会带来更多可能性。在后面，我们将了解到**放置区域**。 #### 插槽 | 名称 | 说明 | 参数 | 后备内容 | | ------- | -------------- | ---- | -------- | | default | **源**的子节点 | 无 | 空 | #### 事件 `DndSource` 不触发任何事件。 #### 组件实例 `DndSource` 不使用 `expose` 暴露任何内容。 ### DndDropzone `DndDropzone` 用于渲染**放置区域**：一般来说，只有当我们在**放置区域**上结束拖放交互时，才可能产生实际的放置效果，例如将**当前拖拽源**移动到交互结束时所在的**放置区域**中。 #### 属性 | 名称 | 类型 | 说明 | 是否必选 | 默认值 | | --------- | ------- | ------------------------------------------------------ | -------- | ------ | | tag | string | 渲染**放置区域**所使用的 html 标签 | 否 | 'div' | | label | string | 为**放置区域**绑定一个标签，一般用于分组 | 否 | | | value | any | 为**放置区域**绑定一个值，在某个组内，该值通常是唯一的 | 否 | | | droppable | boolean | 是否允许放置 | 否 | true | 在拖放交互开始后，当我们使用某种指向设备（例如鼠标）指向某个**放置区域**时，`DndProvider` 将会触发 `drag:enter` 事件，并将该**放置区域**作为**当前选择放置区域**。当我们取消指向**当前选择放置区域**时，`DndProvider` 将会触发 `drag:leave` 事件。在拖放交互进行中时，如果**当前选择放置区域**存在，`DndProvider` 将会定时触发 `drag:over` 事件。在拖放交互结束时，如果**当前选择放置区域**不存在，`DndProvider` 将只会触发 `drag:end` 事件。否则，`DndProvider` 将会根据**当前选择放置区域**的可放置与否决定触发 `drop` 或 `drag:leave` 事件，并随后触发 `drag:end` 事件。 #### 插槽 | 名称 | 说明 | 参数 | 后备内容 | | ------- | -------------------- | ---- | -------- | | default | **放置区域**的子节点 | 无 | 空 | #### 事件 `DndDropzone` 不触发任何事件。 #### 组件实例 `DndDropzone` 不使用 `expose` 暴露任何内容。 ### DndHandle `DndHandle` 用于渲染**拖拽触发器**。如果某个**源**中包含**拖拽触发器**，那么只有当我们尝试拖拽该**源**中的**拖拽触发器**时，`DndProvider` 才能感知到我们正在尝试拖拽该**源**，并随后触发 `drag:start` 或 `drag:prevent` 事件。 #### 属性 | 名称 | 类型 | 说明 | 是否必选 | 默认值 | | ---- | ------ | ------------------------------------ | -------- | ------ | | tag | string | 渲染**拖拽触发器**所使用的 html 标签 | 否 | 'div' | #### 插槽 | 名称 | 说明 | 参数 | 后备内容 | | ------- | ---------------------- | ---- | -------- | | default | **拖拽触发器**的子节点 | 无 | 空 | #### 事件 `DndHandle` 不触发任何事件。 #### 组件实例 `DndHandle` 不使用 `expose` 暴露任何内容。 ## 组合式函数 ### useDnd 创建一个[拖放交互实例](./docs/zh-cn/instance.md)，通过选项 `type` 区分实例种类。 ### useNativeDnd 创建一个 `NativeDnd` 专用的[拖放交互实例](./docs/zh-cn/instance.md)。 ### useMouseDnd 创建一个 `MouseDnd` 专用的[拖放交互实例](./docs/zh-cn/instance.md)。 ### useTouchDnd 创建一个 `TouchDnd` 专用的[拖放交互实例](./docs/zh-cn/instance.md)。 ## 数组工具函数 vdnd 提供了一组更新响应式数组的工具函数，在实现具体的放置效果时会十分有帮助。 ### unshift 在数组头部插入一个元素。 ### shift 移除数组中的第一个元素。 ### push 在数组尾部插入一个元素。 ### pop 移除数组中的最后一个元素。 ### splice 移除数组中的多个元素，并可以在移除的位置上插入多个元素。 ### find 返回第一个满足条件的元素（从左向右查找）。 ### findLast 返回第一个满足条件的元素（从右向左查找）。 ### findIndex 返回第一个满足条件的元素的索引（从左向右查找）。 ### findLastIndex 返回第一个满足条件的元素的索引（从右向左查找）。 ### swap - 交换两个数组中的元素。 - 交换一个数组中的两个元素。 ### remove 移除数组中满足条件的第一个元素。 ### insert 在数组某个位置的前或后插入多个元素。 # 感谢 [@shopify/draggable](https://www.npmjs.com/package/@shopify/draggable)为 vdnd 带来了灵感。