Skip to content

Commit 3a76d18

Browse files
Alfred-SkyblueAlfred-Skyblue
committed
docs: complete the doc
1 parent cca750c commit 3a76d18

File tree

3 files changed

+219
-87
lines changed

3 files changed

+219
-87
lines changed

‎src/__docs__/api/index.en-US.md

Lines changed: 79 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,18 @@ All event functions starting with `on` can be passed to components using `v-on`.
1212
```vue
1313
1414
<template>
15-
<VueDraggable v-model="list" @start="onStart" @end="onEnd"></VueDraggable>
15+
<VueDraggable v-model="list" @start="onStart" @end="onEnd">
16+
<div
17+
v-for="item in list"
18+
:key="item.id"
19+
>
20+
{{ item.name }}
21+
</div>
22+
</VueDraggable>
1623
</template>
1724
<script lang="ts" setup>
1825
import { ref } from "vue";
19-
import { VueDraggable } from 'vue-draggable-plus'
20-
import { SortableEvent } from "sortablejs";
26+
import { VueDraggable, DraggableEvent } from 'vue-draggable-plus'
2127
2228
const list = ref([
2329
{
@@ -38,11 +44,11 @@ const list = ref([
3844
}
3945
])
4046
41-
function onStart(event: SortableEvent) {
47+
function onStart(event: DraggableEvent) {
4248
console.log('start drag')
4349
}
4450
45-
function onEnd(event: SortableEvent) {
51+
function onEnd(event: DraggableEvent) {
4652
console.log('end drag')
4753
}
4854
</script>
@@ -51,6 +57,44 @@ function onEnd(event: SortableEvent) {
5157

5258
> For information on using Hooks and directives, please refer to the documentation.
5359
60+
## Types
61+
62+
```ts
63+
64+
type SortableMethod = 'closest' | 'save' | 'toArray' | 'destroy' | 'option'
65+
66+
/**
67+
* The return value of useDraggable
68+
*/
69+
export interface UseDraggableReturn extends Pick<Sortable, SortableMethod> {
70+
/**
71+
* Starts dragging
72+
* @param {HTMLElement} target - The element to be dragged
73+
* @default - The component's root element, refer to [Target Container](/demo/target-container/), defaults to the component's root element
74+
*/
75+
start: (target?: HTMLElement) => void
76+
/**
77+
* Pauses dragging
78+
*/
79+
pause: () => void
80+
/**
81+
* Resumes dragging
82+
*/
83+
resume: () => void
84+
}
85+
86+
export interface UseDraggableOptions<T> extends Options {
87+
clone?: (element: T) => T
88+
immediate?: boolean
89+
customUpdate?: (event: DraggableEvent) => void
90+
}
91+
92+
interface DraggableEvent<T = any> extends DraggableEvent {
93+
data: T
94+
clonedData: T
95+
}
96+
```
97+
5498
## Options
5599

56100
`Options` inherits all configuration items from `Sortablejs`. For details, please see the [`Sortablejs` official documentation](https://github.com/SortableJS/Sortable).
@@ -138,15 +182,34 @@ type ScrollFn = ((
138182
| scrollSensitivity | The distance in pixels the mouse must be to the edge to start scrolling | `Number` | - |
139183
| scrollSpeed | The scrolling speed in ms/px | `number` | - |
140184
| bubbleScroll | Enables automatic scrolling for all parent elements to make it easier to move items | `Boolean` | `true` |
141-
| onChoose | Triggered when an item is selected | `((event: SortableEvent) => void)` | - |
142-
| onUnchoose | Triggered when an item is deselected | `((event: SortableEvent) => void)` | - |
143-
| onStart | Triggered when an item is picked up for drag and drop | `((event: SortableEvent) => void)` | - |
144-
| onEnd | Triggered when an item is no longer being dragged | `((event: SortableEvent) => void)` | - |
145-
| onAdd | Triggered when an item is moved from one list to another | `((event: SortableEvent) => void)` | - |
146-
| onUpdate | Triggered when the order of the items is updated | `((event: SortableEvent) => void)` | - |
147-
| onSort | Triggered whenever any changes are made to the list | `((event: SortableEvent) => void)` | - |
148-
| onRemove | Triggered when an item is removed from the list and moved to another | `((event: SortableEvent) => void)` | - |
149-
| onFilter | Triggered when trying to drag a filtered item | `((event: SortableEvent) => void)` | - |
185+
| onChoose | Triggered when an item is selected | `((event: DraggableEvent) => void)` | - |
186+
| onUnchoose | Triggered when an item is deselected | `((event: DraggableEvent) => void)` | - |
187+
| onStart | Triggered when an item is picked up for drag and drop | `((event: DraggableEvent) => void)` | - |
188+
| onEnd | Triggered when an item is no longer being dragged | `((event: DraggableEvent) => void)` | - |
189+
| onAdd | Triggered when an item is moved from one list to another | `((event: DraggableEvent) => void)` | - |
190+
| onUpdate | Triggered when the order of the items is updated | `((event: DraggableEvent) => void)` | - |
191+
| onSort | Triggered whenever any changes are made to the list | `((event: DraggableEvent) => void)` | - |
192+
| onRemove | Triggered when an item is removed from the list and moved to another | `((event: DraggableEvent) => void)` | - |
193+
| onFilter | Triggered when trying to drag a filtered item | `((event: DraggableEvent) => void)` | - |
150194
| onMove | Triggered while an item is being dragged | `((event: MoveEvent,originalEvent: Event) => void)` | - |
151-
| onClone | Triggered when an item is cloned | `((event: SortableEvent) => void)` | - |
152-
| onChange | Triggered when an item is dragged and changes position | `((event: SortableEvent) => void)` | - |
195+
| onClone | Triggered when an item is cloned | `((event: DraggableEvent) => void)` | - |
196+
| onChange | Triggered when an item is dragged and changes position | `((event: DraggableEvent) => void)` | - |
197+
198+
199+
## Component (Component Properties)
200+
201+
### Props
202+
203+
The component's props include all options from `Sortablejs` and can be passed to the component. For details, see [Options](#options).
204+
205+
| Parameter | Description | Required | Default |
206+
|------------------------|---------------------------------------------------------------|----------|---------|
207+
| modelValue (v-model) | The list for two-way binding | Yes | - |
208+
| tag | The tag name of the component's root element | No | `div` |
209+
| target | Specifies the target container. If not provided, the component's root element is used as the container. See [Target Container](/demo/target-container/) for details. | No | - |
210+
211+
### Slots
212+
213+
| Name | Description | Parameters |
214+
|---------|-------------|---------------------|
215+
| default | Default slot | UseDraggableReturn |

0 commit comments

Comments
 (0)