@vdnd/v3

# 介绍 > 为了更好地理解本章内容，请先阅读[README](../../README.zh-cn.md)中的API#组件章节。 **拖放交互实例**允许我们自定义拖放交互的细节，并提供了一些非常实用的方法。 vdnd 提供了 `useNativeDnd`、`useMouseDnd` 和 `useTouchDnd` 三种创建**拖放交互实例**的方法，它们分别用于 `NativeDnd`、`MouseDnd` 和 `TouchDnd`。vdnd 也提供了方法 `useDnd`，它通过 `type` 选项来定义实例的种类。 > vdnd 不推荐使用 `useDnd`，因为它需要指定更多的泛型才能带来良好的类型推导。 # 实例选项创建**拖放交互实例**时提供的选项对象。在下文中，若不对选项做特殊说明，则默认其为通用选项。 ## strict 是否开启严格模式：**当前拖拽源**无法作为**当前选择放置区域**。 | 类型 | 是否必选 | 默认值 | | ------- | -------- | ------ | | boolean | 否 | false | 开启严格模式意味着： - **当前拖拽源**无法作为触发 `drag:enter`、`drag:leave`、`drag:over` 、`drop` 事件的条件。 - vdnd 不会为**当前拖拽源**附加 `classes['dropzone:over']`、`classes['dropzone:droppable']`、`classes['dropzone:disabled']` 类名。 ## debug 是否开启调试模式。开启调试模式后，vdnd 会通过[自定义属性](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLElement/dataset)的方式将**源**和**放置区域**的属性呈现在 DOM 中。 | 类型 | 是否必选 | 默认值 | | ------------------- | -------- | ------ | | boolean \| string[] | 否 | false | 通过将 `debug` 设置为 `string[]` 类型的数据，可以自定义要调试的属性：`id`、`label`、`value`、`value-type`、`role`、`draggable`、`droppable`。 - `id`：vdnd 内部生成的唯一标识。 - `role`：作为**源**还是**放置区域**，亦或都是。 - `value-type`：值的类型如果 `debug` 的值为 true，将会调试以上所有属性。 ## source **源**的类名。vdnd 会根据一个元素是否拥有该类名判断其是否为**源**。 | 类型 | 是否必选 | 默认值 | | ------ | -------- | ------------ | | string | 否 | 'dnd-source' | ## dropzone **放置区域**的类名。vdnd 会根据一个元素是否拥有该类名判断其是否为**放置区域**。 | 类型 | 是否必选 | 默认值 | | ------ | -------- | -------------- | | string | 否 | 'dnd-dropzone' | ## handle **拖拽触发器**的类名。vdnd 会根据一个元素是否拥有该类名判断其是否为**拖拽触发器**。 | 类型 | 是否必选 | 默认值 | | ------ | -------- | ------------ | | string | 否 | 'dnd-handle' | ## classes 根据拖放交互状态为**源**或**放置区域**附加的类名。 | 类型 | 是否必选 | 默认值 | | ---------------- | -------- | ------ | | Partial<object\> | 否 | 见下 | | 属性名 | 类型 | 说明 | 默认值 | | ------------------ | ------------------ | ------------------------------------------------------ | ------------------------- | | source:dragging | string \| string[] | 为**当前拖拽源**附加的类名 | 'dnd-source--dragging' | | source:draggable | string \| string[] | 为所有可拖拽的**源**附加的类名 | 'dnd-source--draggable' | | source:disabled | string \| string[] | 为所有不可拖拽的**源**附加的类名 | 'dnd-source--disabled' | | dropzone:over | string \| string[] | 拖放交互开始后，为**当前选择放置区域**附加的类名 | 'dnd-dropzone--over' | | dropzone:droppable | string \| string[] | 拖放交互开始后，为所有可放置的**放置区域**附加的类名 | 'dnd-dropzone--droppable' | | dropzone:disabled | string \| string[] | 拖放交互开始后，为所有不可放置的**放置区域**附加的类名 | 'dnd-dropzone--disabled' | ## mirror 镜像相关选项。vdnd 会在拖放交互开始后，基于**当前拖拽源**创建镜像。 | 类型 | 是否必选 | 默认值 | | ---------------- | -------- | ------ | | Partial<object\> | 否 | 见下 | | 属性名 | 类型 | 说明 | 默认值 | | ------------------- | ----------- | -------------------------------------------------- | ---------------------- | | create | (e) => Node | 自定义镜像的创建 | _cloneNode_ | | className | string | 为镜像附加的类名 | 'dnd-mirror' | | constrainDimensions | boolean | 是否使镜像的尺寸（宽与高）与**当前拖拽源**保持一致 | false | | cursorOffsetX | number | vdnd 模仿了 DataTransfer.setDrawImage 进行实现 | | | cursorOffsetY | number | vdnd 模仿了 DataTransfer.setDrawImage 进行实现 | | | appendTo | mixed | 插入镜像时所使用的父元素 | **当前拖拽源**的父元素 | https://developer.mozilla.org/zh-CN/docs/Web/API/DataTransfer/setDragImage 注：该选项仅对 `useMouseDnd` 和 `useTouchDnd` 生效。 ## delay `TouchDnd` 将 `touchstart` 和 `touchmove` 事件的接连触发视为拖放交互的开始。而 `delay` 选项用于定义这两个事件发生的最小间隔时间（毫秒），只有实际间隔时间大于或等于最小间隔时间时，拖放交互才会开始。该选项在移动端的滚动场景中会十分有帮助：[在线示例](http://zbd329.top/vdnd/?lang=zh-cn&index=6)。 | 类型 | 是否必选 | 默认值 | | ------ | -------- | ------ | | number | 否 | 100 | 注：该选项仅对 `useTouchDnd` 生效。 ## suppressUIEvent > 该选项是实验性的。浏览器的原生拖放交互会在交互进行中时**抑制** `UIEvent` 的发生，例如我们将无法使用 `ctrl+s` 保存网页。该选项用来模拟此行为。 | 类型 | 是否必选 | 默认值 | | ------- | -------- | ------ | | boolean | 否 | false | 注：该选项仅对 `useMouseDnd` 生效。 # 实例属性 ## options | 类型 | 说明 | | ------ | -------- | | object | 实例选项 | vdnd 支持通过 **instance.options = xxx** 和 **instance.options.xxx = xxx** 来更新实例选项。当我们更新实例选项时，如果拖放交互正在进行，vdnd 将**不会立即应用最新的实例选项**，而是会在拖放交互结束后应用。反之，vdnd 将会立即应用。 ## source | 类型 | 说明 | | -------------- | -------------- | | object \| null | **当前拖拽源** | ## over | 类型 | 说明 | | -------------- | -------------------- | | object \| null | **当前选择放置区域** | ## rootDndElement **源**和**放置区域**统称为**拖放元素**，**拖放元素**可以存在嵌套关系。而 `DndProvider` 会生成一个**根拖放元素**来构建一棵**拖放元素树**（**根拖放元素**即不是**源**也不是**放置区域**）。 | 类型 | 说明 | | ------ | -------------- | | object | **根拖放元素** | # 实例方法 ## on/once/off vdnd 支持通过**拖放交互实例**监听拖放交互事件。通过**拖放交互实例**添加的事件监听器会晚于 `DndProvider` 上的监听器触发。请确保你的监听操作在 `DndProvider` 触发 `initialized` 事件后执行，否则将是**不安全**的。 ## isDragging **当前拖拽源**是否满足指定条件？该方法会读取**拖放交互实例**的 `source` 属性，因而是响应式的。 ## isOver **当前选择放置区域**是否满足指定条件？该方法会读取**拖放交互实例**的 `over` 属性，因而是响应式的。