Skip to content

Commit 57a1b38

Browse files
ZiZIGYZiZIGY
committed
updated docs
1 parent d2bfd7b commit 57a1b38

File tree

7 files changed

+224
-14
lines changed

7 files changed

+224
-14
lines changed

‎docs/guide/core/use-drag-container.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,100 @@ const result = useDragContainer();
1212

1313
The `useDragContainer` composable doesn't accept any parameters.
1414

15+
### Props Support
16+
17+
The drag container component can accept props using `defineProps()`. This allows you to pass custom data and configuration to your container component:
18+
19+
```vue
20+
<script setup lang="ts">
21+
import { useDragContainer } from '@vue-dnd-kit/core';
22+
23+
// Define props for your container
24+
const props = defineProps<{
25+
theme?: 'light' | 'dark';
26+
animation?: 'fade' | 'slide';
27+
customData?: any;
28+
}>();
29+
30+
const { elementRef, isDragging, draggingElements } = useDragContainer();
31+
</script>
32+
33+
<template>
34+
<div
35+
v-if="isDragging"
36+
ref="elementRef"
37+
class="drag-container"
38+
:class="{
39+
'drag-container--light': theme === 'light',
40+
'drag-container--dark': theme === 'dark',
41+
'drag-container--fade': animation === 'fade',
42+
'drag-container--slide': animation === 'slide',
43+
}"
44+
>
45+
<!-- Your dragged elements will be rendered here -->
46+
</div>
47+
</template>
48+
```
49+
50+
### Reactive Props
51+
52+
For reactive props, pass them in their reactive state without calling `.value`. You can use `ref`, `reactive`, or `computed`:
53+
54+
```vue
55+
<script setup lang="ts">
56+
import { ref, computed } from 'vue';
57+
import { useDraggable } from '@vue-dnd-kit/core';
58+
59+
// Reactive state
60+
const currentTheme = ref('light');
61+
const isAnimationEnabled = ref(true);
62+
const userPreferences = ref({ fontSize: 14, color: 'blue' });
63+
64+
// Computed props
65+
const containerStyle = computed(() => ({
66+
fontSize: userPreferences.value.fontSize + 'px',
67+
color: userPreferences.value.color,
68+
}));
69+
70+
const { elementRef } = useDraggable({
71+
id: 'my-draggable',
72+
containerProps: {
73+
// Pass refs directly (without .value)
74+
theme: currentTheme,
75+
animation: isAnimationEnabled,
76+
77+
// Pass computed values
78+
style: containerStyle,
79+
80+
// Pass reactive objects
81+
preferences: userPreferences,
82+
83+
// Static values
84+
staticProp: 'always-the-same',
85+
},
86+
});
87+
</script>
88+
```
89+
90+
### Using Props with Dragged Elements
91+
92+
You can access container props within your dragged elements by passing them through the `containerProps` option in `useDraggable`:
93+
94+
```vue
95+
<script setup lang="ts">
96+
import { useDraggable } from '@vue-dnd-kit/core';
97+
98+
const { elementRef } = useDraggable({
99+
id: 'my-draggable',
100+
containerProps: {
101+
theme: 'dark',
102+
animation: 'fade',
103+
customData: { userId: 123 },
104+
},
105+
});
106+
</script>
107+
```
108+
15109
### Return Value
16110

17111
`useDragContainer` returns an object with the following properties:
@@ -53,3 +147,9 @@ The `pointerPosition` object includes:
53147
8. For performance reasons, apply `will-change: transform` to elements that will move during dragging.
54148

55149
9. You may want to conditionally show the container only when `isDragging` is true to improve performance.
150+
151+
10. **Props Support**: Container components can accept props using `defineProps()` and access them within the component template and logic.
152+
153+
11. **Container Props**: Use the `containerProps` option in `useDraggable` to pass custom data to your container component.
154+
155+
12. **Reactive Props**: When passing reactive values (ref, reactive, computed), pass them directly without calling `.value`. Vue will automatically track reactivity.

‎docs/guide/core/use-draggable.md‎

Lines changed: 61 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,18 @@ useDraggable(options?: IUseDragOptions)
1212

1313
The `options` object can include the following properties:
1414

15-
| Property | Type | Description | Required |
16-
| --------- | ------------------------- | ----------------------------------------------- | -------- |
17-
| id | `string \| number` | Unique identifier for the draggable element | No |
18-
| groups | `string[]` | Groups this draggable belongs to | No |
19-
| disabled | `boolean \| Ref<boolean>` | Whether dragging is disabled | No |
20-
| events | `Object` | Event handlers (see Events section) | No |
21-
| data | `Object` | Custom data to associate with draggable element | No |
22-
| keyboard | `Object` | Keyboard navigation configuration | No |
23-
| container | `Component` | Custom overlay component | No |
24-
| layer | `Component \| null` | Custom layer component | No |
25-
| sensor | `Object` | Custom sensor configuration | No |
15+
| Property | Type | Description | Required |
16+
| -------------- | ------------------------- | ----------------------------------------------- | -------- |
17+
| id | `string \| number` | Unique identifier for the draggable element | No |
18+
| groups | `string[]` | Groups this draggable belongs to | No |
19+
| disabled | `boolean \| Ref<boolean>` | Whether dragging is disabled | No |
20+
| events | `Object` | Event handlers (see Events section) | No |
21+
| data | `Object` | Custom data to associate with draggable element | No |
22+
| keyboard | `Object` | Keyboard navigation configuration | No |
23+
| container | `Component` | Custom overlay component | No |
24+
| layer | `Component \| null` | Custom layer component | No |
25+
| containerProps | `Record<string, any>` | Props to pass to the drag container component | No |
26+
| sensor | `Object` | Custom sensor configuration | No |
2627

2728
#### Events Object
2829

@@ -58,6 +59,45 @@ The `payload` parameter provides access to all dragging elements:
5859
| -------- | -------- | --------------------------------------------- |
5960
| moveStep | `number` | Pixels to move when using keyboard navigation |
6061

62+
### Container Props
63+
64+
The `containerProps` option allows you to pass custom data and configuration to your drag container component. This is useful for customizing the appearance and behavior of the container during drag operations:
65+
66+
```ts
67+
import { ref, computed } from 'vue';
68+
69+
const currentTheme = ref('dark');
70+
const animationType = ref('fade');
71+
72+
const { elementRef } = useDraggable({
73+
id: 'my-draggable',
74+
containerProps: {
75+
// Static values
76+
theme: 'light',
77+
animation: 'slide',
78+
79+
// Reactive values (pass refs directly)
80+
currentTheme: currentTheme,
81+
animationType: animationType,
82+
83+
// Computed values
84+
style: computed(() => ({
85+
backgroundColor: currentTheme.value === 'dark' ? '#333' : '#fff',
86+
transition:
87+
animationType.value === 'fade' ? 'opacity 0.3s' : 'transform 0.3s',
88+
})),
89+
90+
// Custom data
91+
customData: {
92+
userId: 123,
93+
itemType: 'task',
94+
},
95+
},
96+
});
97+
```
98+
99+
**Important**: When passing reactive values (ref, reactive, computed), pass them directly without calling `.value`. Vue will automatically track reactivity.
100+
61101
### Return Value
62102

63103
`useDraggable` returns an object with the following properties:
@@ -83,6 +123,10 @@ const { elementRef } = useDraggable({
83123
data: computed(() => ({
84124
task: props.task,
85125
})),
126+
containerProps: {
127+
theme: 'dark',
128+
animation: 'fade',
129+
},
86130
events: {
87131
onStart: (store, payload) => {
88132
// Access the first dragged element (most common scenario)
@@ -217,7 +261,13 @@ const { elementRef } = useDraggable({
217261
task: props.task,
218262
status: currentStatus.value,
219263
})),
264+
containerProps: {
265+
theme: computed(() => currentTheme.value),
266+
animation: computed(() => animationType.value),
267+
},
220268
});
221269
```
222270

223271
This ensures Vue correctly tracks dependencies and updates the draggable behavior when your reactive values change.
272+
273+
8. **Container Props**: Use the `containerProps` option to pass custom data and configuration to your drag container component. This allows for dynamic customization of the container during drag operations.

‎packages/core/src/components/DragOverlay.vue‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,10 @@
1111
1212
const overlay = computed(() => ({
1313
component: activeContainer.component.value ?? DefaultOverlay,
14-
props,
14+
props: {
15+
...props,
16+
...activeContainer.props.value,
17+
},
1518
}));
1619
</script>
1720

‎packages/core/src/composables/useDnDStore.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ export const useDnDStore = createGlobalState(() => {
2424
component: ref<Component | null>(null),
2525
ref: shallowRef<HTMLElement | null>(null),
2626
options: shallowRef<TransitionProps | null>(null),
27+
props: shallowRef<Record<string, any> | null>(null),
2728
animating: {
2829
enter: shallowRef<boolean>(false),
2930
leave: shallowRef<boolean>(false),

‎packages/core/src/managers/useEventManager.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,9 @@ export const useEventManager = createGlobalState(() => {
102102
(event.target as HTMLElement).blur();
103103

104104
if (options?.container) activeContainer.component.value = options.container;
105+
if (options?.containerProps) {
106+
activeContainer.props.value = options.containerProps;
107+
}
105108

106109
const { activate, track, deactivate } = useSensor(elementRef, options);
107110

‎packages/core/src/plugin.ts‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,54 @@ export const VueDndKitPlugin = {
2424
overlayContainer.id = 'vue-dnd-kit-overlay';
2525
overlayContainer.style.pointerEvents = 'none';
2626

27-
rootEl.appendChild(overlayContainer);
27+
// Применяем кастомный z-index если указан
28+
if (options?.overlayPosition?.zIndex) {
29+
overlayContainer.style.zIndex =
30+
options.overlayPosition.zIndex.toString();
31+
}
32+
33+
// Применяем кастомный класс если указан
34+
if (options?.overlayPosition?.className) {
35+
overlayContainer.className = options.overlayPosition.className;
36+
}
37+
38+
// Определяем метод вставки overlay
39+
const insertMethod = options?.overlayPosition?.method || 'append';
40+
const targetElement = options?.overlayPosition?.target
41+
? typeof options.overlayPosition.target === 'string'
42+
? document.querySelector(options.overlayPosition.target)
43+
: options.overlayPosition.target
44+
: rootEl;
45+
46+
if (targetElement && targetElement instanceof Element) {
47+
switch (insertMethod) {
48+
case 'prepend':
49+
targetElement.insertBefore(
50+
overlayContainer,
51+
targetElement.firstChild
52+
);
53+
break;
54+
case 'after':
55+
targetElement.parentNode?.insertBefore(
56+
overlayContainer,
57+
targetElement.nextSibling
58+
);
59+
break;
60+
case 'before':
61+
targetElement.parentNode?.insertBefore(
62+
overlayContainer,
63+
targetElement
64+
);
65+
break;
66+
case 'append':
67+
default:
68+
targetElement.appendChild(overlayContainer);
69+
break;
70+
}
71+
} else {
72+
// Fallback к старому поведению
73+
rootEl.appendChild(overlayContainer);
74+
}
2875

2976
// Передаем опции напрямую в компонент
3077
const vnode = createVNode(DragOverlay, {

‎packages/core/src/types/index.d.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,13 @@ export interface IPluginOptions {
1818
defaultOverlay?: {
1919
styles?: CSSProperties;
2020
};
21+
overlayPosition?: {
22+
target?: string | Element | HTMLElement;
23+
method?: 'append' | 'prepend' | 'after' | 'before';
24+
zIndex?: number;
25+
className?: string;
26+
};
2127
}
22-
2328
export interface IPointerPosition {
2429
start: Ref<IPoint | null>;
2530
current: Ref<IPoint | null>;
@@ -121,6 +126,7 @@ export interface IUseDragOptions extends IUseSensorOptions {
121126
};
122127
layer?: Component | null;
123128
container?: Component;
129+
containerProps?: Record<string, any>;
124130
sensor?: {
125131
throttle?: number;
126132
setup?: (store: IDnDStore) => Element | Element[] | null;

0 commit comments

Comments
 (0)