@vdnd/v3

# Introduction > To better understand the content of this chapter, please first read the API#Components chapter in the [README](../../README.md). We can customize details of the drag and drop interaction by **DndInstance** that also provides some helpful methods. Vdnd provides three functions to create **DndInstance**: `useNativeDnd`, `useMouseDnd` and `useTouchDnd`, they are used for `NativeDnd`, `MouseDnd` and `TouchDnd` respectively. In addition, `useDnd` is also provided, it distinguishs type of created instance by the `type` option. > Vdnd does not recommend `useDnd`, because we need to provide more generic types for better type inference. # Instance options The options are used for creating **DndInstance**. In the following, the mentioned options are general option by default, unless special instructions. ## strict Enables strict mode or not: **the current source** will not act as **the current drop target**. | Type | Required | Default | | ------- | -------- | ------- | | boolean | false | false | Enables strict mode means: - **The current source** cannot be used as conditions to emit `drag:enter`, `drag:leave`, `drag:over` or `drop` events. - Vdnd will not attach `classes['dropzone:over']`, `classes['dropzone:droppable']` and `classes['dropzone:disabled']` to **the current source**. ## debug Enables debugging mode or not. If enabled, vdnd will present properties of **source** and **dropzone** in DOM by [custom attributes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset). | Type | Required | Default | | ------------------- | -------- | ------- | | boolean \| string[] | false | false | We can customize the properties to be debugged: `id`, `label`, `value`, `value-type`, `role`, `draggable` and `droppable`, if `debug` is set to `string[]`. - `id`: internal unique id. - `role`: acts as **source** or **dropzone**, or both. - `value-type`: type of the `value`. If `debug` is true, all of the above properties will be debugged. ## source Class of **source**. vdnd will determine whether an element is **source** based on whether it owns the class. | Type | Required | Default | | ------ | -------- | ------------ | | string | false | 'dnd-source' | ## dropzone Class of **dropzone**. vdnd will determine whether an element is **dropzone** based on whether it owns the class. | Type | Required | Default | | ------ | -------- | -------------- | | string | false | 'dnd-dropzone' | ## handle Class of **handle**. vdnd will determine whether an element is **handle** based on whether it owns the class. | Type | Required | Default | | ------ | -------- | ------------ | | string | false | 'dnd-handle' | ## classes The classes attached to **source** and **dropzone** according to the interaction state. | Type | Required | Default | | ---------------- | -------- | --------- | | Partial<object\> | false | see below | <style> table tr td:nth-child(1), table tr td:nth-child(2), table tr td:nth-child(4) { white-space: nowrap; } </style> | Name | Type | Description | Default | | ------------------ | ------------------ | --------------------------------------------------------------------------------- | ------------------------- | | source:dragging | string \| string[] | classes attached to **the current source** | 'dnd-source--dragging' | | source:draggable | string \| string[] | classes attached to all draggable **sources** | 'dnd-source--draggable' | | source:disabled | string \| string[] | classes attached to all not draggable **sources** | 'dnd-source--disabled' | | dropzone:over | string \| string[] | after the interaction starts, classes attached to **the current drop target** | 'dnd-dropzone--over' | | dropzone:droppable | string \| string[] | after the interaction starts, classes attached to all droppable **dropzones** | 'dnd-dropzone--droppable' | | dropzone:disabled | string \| string[] | after the interaction starts, classes attached to all not droppable **dropzones** | 'dnd-dropzone--disabled' | ## mirror The mirror options. vdnd will create the mirror of **the current source** when the interaction starts. | Type | Required | Default | | ---------------- | -------- | --------- | | Partial<object\> | false | see below | | Name | Type | Description | Default | | ------------------- | ------------------ | --------------------------------------------------------------------------------- | ----------------------------------------- | | create | (e) => Node | customizes creation of the mirror | _cloneNode_ | | className | string \| string[] | classes attached to the mirror | 'dnd-mirror' | | constrainDimensions | boolean | keeps the dimensions of the mirror consistent with that of **the current source** | false | | cursorOffsetX | number | vdnd imitates DataTransfer.setDrawImage for implementation | | | cursorOffsetY | number | vdnd imitates DataTransfer.setDrawImage for implementation | | | appendTo | mixed | The parent node used when inserting the mirror | the parent node of **the current source** | https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer/setDragImage Note: this option only functions for `useMouseDnd` and `useTouchDnd`. ## delay `TouchDnd` considers the consecutive occurrences of `touchstart` and `touchmove` events as the start of the interaction. The `delay` option is used for defining the minimum time interval(milliseconds) between occurrences of `touchstart` and `touchmove` events, the interaction only starts when actual interval is greater than or equal to the minimum interval. This option will be helpful in the scrolling scene on mobile device: [online example](https://zhengbaodi.github.io/vdnd/?lang=en&index=6). | Type | Required | Default | | ------ | -------- | ------- | | number | false | 100 | Note: this option only functions for `useTouchDnd`. ## suppressUIEvent > This option is experimental. Browser will suppress `UIEvent` during the native drag and drop interaction, such as we cannot save the web page by `ctrl+s`. This option is used for imitating this behavior. | Type | Required | Default | | ------- | -------- | ------- | | boolean | false | false | Note: this option only functions for `useMouseDnd`. # Instance properties ## options | Type | Description | | ------ | ---------------- | | object | instance options | Vdnd supports updating instance options through **instance.options=xxx** and **instance.options.xxx = xxx**. When we update instance options, if the interaction is in progress, vdnd **will not apply the newest intance options immediately**, but after the end of the interaction. ## source | Type | Description | | -------------- | ---------------------- | | object \| null | **the current source** | ## over | Type | Description | | -------------- | -------------------------- | | object \| null | **the current dop target** | ## rootDndElement **Source** and **dropzone** are referred to as **DndElement**, and **DndElement** can nest each other. Vdnd will create a **RootDndElement** to build a **DndElementTree** (**RootDndElement** is neither **source** nor **dropzone**). | Type | Description | | ------ | ------------------ | | object | **RootDndElement** | # Instance methods ## on/once/off We can add the event handlers of the interaction events by `DndIntance`, these event handlers will be called after the event handlers of `DndProvider`. Please add event handlers after `DndProvider` emitting `initialized` event, otherwise it will be unsafe. ## isDragging Whether **the current source** meets the specified conditions or not? This method will read the `source` property of `DndInstance`, therefor reactive. ## isOver Whether **the current drop target** meets the specified conditions or not? This method will read the `over` property of `DndInstance`, therefor reactive.