Migrer depuis la v2

La v3 est une réécriture de la v2. Le modèle reste : un provider, et des composables que vous appelez sur vos propres éléments. Mais la plupart des noms et des options ont changé, le tri est passé dans la bibliothèque, et le handler de dépôt que vous écriviez pour chaque liste disparaît. Cette page fait correspondre chaque partie de la v2 à la v3, puis montre les cas courants avant et après.

Ce qui a changé

• Le tri est intégré. En v2, une liste était une zone de dépôt, ses lignes étaient des éléments déplaçables avec un payload [index, items], et vous triiez dans onDrop avec e.helpers.suggestSort(). En v3, makeSortableList et makeSortableItem s'en chargent : la liste rend un brouillon de votre tableau qui se réordonne pendant le glissement, et le dépôt écrit le nouveau tableau dans votre ref. La plupart des handlers de dépôt de la v2 sont supprimés, pas portés.
• Les choses bougent toutes seules. Les lignes glissent vers leurs nouvelles places (FLIP), l'overlay atterrit sur son emplacement au dépôt et revient à sa place à l'annulation. <TransitionGroup> disparaît.
• Toujours un seul paquet. @vue-dnd-kit/core contient les listes, les arbres, le multi-drag, les modificateurs, les capteurs et les fonctions de collision. Le module Nuxt reste ; @vue-dnd-kit/actions (glissements programmatiques) et @vue-dnd-kit/devtools sont nouveaux et optionnels.
• Un vrai overlay. Il est téléporté dans body et montre un clone profond, à la taille de l'emplacement où il va atterrir. Les composants d'overlay reçoivent le glissement en props au lieu de lire les rouages internes du provider.
• Des ids, pas des éléments. La sélection, les événements et l'état du glissement sont indexés par des ids issus de vos données. Il n'y a plus de maps d'éléments du DOM à lire.
• Les types et les règles d'acceptation remplacent groups pour les éléments déplaçables simples et les cibles. Les listes échangent des items par le nom de leur group.
• Des décisions avant le dépôt. onBeforeDrop accepte, refuse, laisse le glissement continuer ou ne prend qu'une partie des items. onDrop ne fait qu'appliquer.
• Des capteurs. Les entrées au pointeur et au clavier sont des capteurs. L'activation se règle par type de pointeur, et les glissements tactiles commencent par un appui long, si bien que les listes continuent de défiler sous le doigt.
• Des zones. makeDragArea remplace makeConstraintArea et makeAutoScroll, et le défilement automatique fonctionne dans chaque conteneur défilable sans code.
• L'accessibilité est activée par défaut : attributs ARIA, un focus qui revient après le dépôt, et des annonces pour les lecteurs d'écran.

Mise à jour

npm i @vue-dnd-kit/core@^3

yarn add @vue-dnd-kit/core@^3

pnpm add @vue-dnd-kit/core@^3

bun add @vue-dnd-kit/core@^3

• Une application qui a "@vue-dnd-kit/core": "^2…" dans son package.json reste en v2 tant que la plage de versions n'indique pas ^3.
• Vue 3.5 ou plus récent. La v2 n'avait aucune dépendance ; la v3 en a une, @vueuse/core (14 ou 15).
• Navigateurs : Chrome et Edge 104+, Safari 15.4+, Firefox 104+.
• La v2 et la v3 partagent un nom de paquet, donc une application passe à la v3 d'un seul coup. Il n'y a pas de couche de compatibilité. La documentation de la v2 reste disponible depuis le menu des versions en haut de la page.

Un bon ordre de travail :

1. Mettez à jour les paquets et renommez les props du provider (plus bas).
2. Transformez chaque liste triable en makeSortableList et makeSortableItem, et supprimez son handler de dépôt.
3. Portez les éléments déplaçables simples et les zones de dépôt.
4. Portez les aperçus personnalisés vers des composants d'overlay ou le slot #overlay du provider.
5. Remplacez makeConstraintArea et makeAutoScroll par makeDragArea, ou par rien.
6. Supprimez les contournements de la v2 : tabindex et aria-grabbed sur les éléments déplaçables, touch-action: none sur des items entiers, <TransitionGroup> autour des lignes, markRaw autour des composants d'aperçu.

De l'ancien au nouveau

Pas d'équivalent dans un tableau signifie que la v3 n'a rien de ce nom ; la cellule indique quoi utiliser à la place.

En un coup d'œil

Le provider

Nouvelles props sans équivalent en v2 : activation, modifiers, sensors, animation, dropAnimation, animateChanges, haptics, copyModifier, overlayFit, overlayClass, overlayTransition, overlayPreviews, announcements, screenReaderInstructions et defaultStyles. Le provider émet aussi drag-start, drag-move, drag-over, drag-end, drag-cancel, drag-resume et drag-settle. Tout cela se trouve dans le guide du provider.

Lire l'état : useDnD

Les événements sont passés à useDnDMonitor : voir événements et décisions de dépôt. Les formes complètes sont dans l'API de useDnD.

makeDraggable

makeDroppable

L'événement de dépôt

Le tri

Le code avant et après se trouve plus bas. Tout sur les listes se trouve dans listes triables et listes qui partagent des items.

Les groupes

La v2 avait une seule option groups pour tout. La v3 la sépare en deux :

Une liste sans group forme un groupe à elle seule et n'échange avec aucune autre liste. En v2, une zone sans groupes acceptait tout. Voir les glissements qu'une cible accepte.

L'overlay

Plus de détails dans le guide de l'overlay.

Sélection et multi-drag

Plus de détails dans multi-drag et sélection.

Axes, limites et alignement

Plus de détails dans axes, limites et grilles.

Défilement automatique

Clavier et accessibilité

Plus de détails dans accessibilité.

Événements et décisions de dépôt

Un onDrop de la v2 pouvait renvoyer une valeur, ou une promesse de valeur, pour décider du dépôt. En v3, c'est le rôle d'onBeforeDrop, sur les listes, les arbres, les cibles de dépôt et les moniteurs :

Les moniteurs répondent d'abord, puis la cible. Ensuite l'onDrop de la cible s'exécute, une liste écrit ses nouveaux tableaux, et onDragEnd suit. Plus de détails dans décider d'un dépôt et dans l'API des événements.

Types

Nuxt

npm i @vue-dnd-kit/nuxt@^3 @vue-dnd-kit/core@^3

modules: ['@vue-dnd-kit/nuxt'] dans nuxt.config.ts reste tel quel. Voir installation.

Avant et après

Un élément déplaçable et une zone de dépôt

v2

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDraggable } from '@vue-dnd-kit/core';

const props = defineProps<{ card: Card }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragging } = makeDraggable(el, {
  groups: ['task'],
  dragHandle: '.handle',
  data: () => props.card,
});
</script>

<template>
  <div ref="el" tabindex="0" :class="{ dragging: isDragging }">
    <span class="handle">⋮⋮</span>
    {{ card.title }}
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDroppable } from '@vue-dnd-kit/core';

const emit = defineEmits<{ drop: [cards: Card[]] }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragOver, isAllowed } = makeDroppable(el, {
  groups: ['task'],
  events: {
    onDrop: (e) => emit('drop', e.draggedItems.map((item) => item.data as Card)),
  },
});
</script>

<template>
  <div ref="el" :class="{ over: isDragOver && isAllowed }"><slot /></div>
</template>

v3

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDraggable } from '@vue-dnd-kit/core';

const props = defineProps<{ card: Card }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragging } = makeDraggable(el, {
  id: () => props.card.id,   // read back as `active.id`
  type: 'task',              // matched by the targets' `accept`
  handle: '.handle',
  data: () => props.card,
});
</script>

<template>
  <div ref="el" :class="{ dragging: isDragging }">
    <button type="button" class="handle" :aria-label="`Move ${card.title}`">⋮⋮</button>
    {{ card.title }}
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDroppable } from '@vue-dnd-kit/core';

const emit = defineEmits<{ drop: [cards: Card[]] }>();
const el = useTemplateRef<HTMLElement>('el');

const { isOver, isAccepting } = makeDroppable(el, {
  accept: 'task',
  onDrop: (e) => emit('drop', e.active.items.map((item) => item.data as Card)),
});
</script>

<template>
  <div ref="el" :class="{ over: isOver && isAccepting }"><slot /></div>
</template>

• La carte reçoit tabindex, role et les attributs aria-* d'elle-même. Une poignée <button> peut recevoir le focus, et les glissements au clavier partent d'elle.
• groups est devenu type sur l'élément déplaçable et accept sur la cible. Les callbacks ont quitté l'objet events.
• isOver sans isAccepting, c'est une cible qui refuse le glissement : un dépôt à cet endroit revient à sa place.

Une liste triable

v2

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDroppable, type IDragEvent } from '@vue-dnd-kit/core';
import TaskItem from './TaskItem.vue';

const tasks = defineModel<Task[]>({ required: true });
const el = useTemplateRef<HTMLElement>('el');

makeDroppable(
  el,
  {
    events: {
      onDrop(e: IDragEvent) {
        const r = e.helpers.suggestSort('vertical');
        if (r) tasks.value = r.targetItems as Task[];
      },
    },
  },
  () => tasks.value,
);
</script>

<template>
  <div ref="el">
    <TransitionGroup name="list">
      <TaskItem v-for="(task, index) in tasks" :key="task.id" :task="task" :index="index" :tasks="tasks" />
    </TransitionGroup>
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDraggable } from '@vue-dnd-kit/core';

const props = defineProps<{ task: Task; index: number; tasks: Task[] }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragging } = makeDraggable(el, { id: props.task.id }, () => [props.index, props.tasks]);
</script>

<template>
  <div ref="el" :class="{ 'is-dragging': isDragging }">{{ task.title }}</div>
</template>

v3

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeSortableList } from '@vue-dnd-kit/core';
import TaskItem from './TaskItem.vue';

const tasks = defineModel<Task[]>({ required: true });
const el = useTemplateRef<HTMLElement>('el');

const { items } = makeSortableList(el, { items: tasks });
</script>

<template>
  <ul ref="el">
    <TaskItem v-for="task in items" :key="task.id" :task="task" />
  </ul>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeSortableItem } from '@vue-dnd-kit/core';

const props = defineProps<{ task: Task }>();
const el = useTemplateRef<HTMLElement>('el');

const { isPlaceholder } = makeSortableItem(el, { item: () => props.task });
</script>

<template>
  <li ref="el" :class="{ slot: isPlaceholder }">{{ task.title }}</li>
</template>

• Rendez items, le brouillon : il se réordonne pendant le glissement. tasks reçoit le nouvel ordre au dépôt, et defineModel émet update:modelValue.
• Pas d'index, pas de payload, pas d'onDrop, pas de <TransitionGroup> : les lignes glissent toutes seules.
• La ligne glissée reste dans la liste, comme l'emplacement où elle va atterrir. Stylez-la avec isPlaceholder ou [data-dnd-placeholder] au lieu de la masquer.

Listes qui partagent des items

v2

// Each column's makeDroppable calls this from its onDrop, with its array as the payload.
function applySort(e: IDragEvent) {
  const r = e.helpers.suggestSort('vertical');
  if (!r) return;

  const src = e.draggedItems[0]?.items;
  const tgt = e.hoveredDraggable?.items ?? e.dropZone?.items;

  if (src === todo.value) todo.value = r.sourceItems as Task[];
  else if (src === done.value) done.value = r.sourceItems as Task[];

  if (!r.sameList) {
    if (tgt === todo.value) todo.value = r.targetItems as Task[];
    else if (tgt === done.value) done.value = r.targetItems as Task[];
  }
}

v3

<script setup lang="ts">
import { toRef, useTemplateRef } from 'vue';
import { makeSortableList } from '@vue-dnd-kit/core';
import TaskItem from './TaskItem.vue';

const props = defineProps<{ column: { id: string; tasks: Task[] } }>();
const el = useTemplateRef<HTMLElement>('el');

const { items } = makeSortableList(el, {
  id: props.column.id,                   // `from.list` and `to.list` in drop events
  items: toRef(props.column, 'tasks'),   // writable: the parent passes a reactive column
  group: 'board',                        // same name: tasks move between these lists
});
</script>

<template>
  <ul ref="el">
    <TaskItem v-for="task in items" :key="task.id" :task="task" />
  </ul>
</template>

<script setup lang="ts">
import { reactive } from 'vue';
import Column from './Column.vue';

const columns = reactive([
  { id: 'todo', tasks: [{ id: 't1', title: 'Write the docs' }] },
  { id: 'done', tasks: [] },
]);
</script>

<template>
  <Column v-for="column in columns" :key="column.id" :column="column" />
</template>

Le dépôt écrit les deux tableaux, celui que la tâche a quitté et celui où elle est entrée. TaskItem.vue est celui de la liste triable ci-dessus. Une palette qui distribue des copies, c'était suggestCopy() et un drapeau copyOnly ; désormais, c'est une liste :

makeSortableList(el, {
  items: blocks,
  group: { name: 'board', pull: 'clone', put: false },  // copies go out, nothing comes in
  sort: false,                                          // its own order stays
  clone: (block) => ({ ...block, id: crypto.randomUUID() }),
});

Pour un store Pinia ou un autre état que vous n'écrivez pas directement, passez items en getter, appelez e.preventDefault() dans onDrop et appliquez e.result : voir les listes contrôlées.

Un overlay personnalisé

v2

makeDraggable(el, {
  render: markRaw(TaskOverlay),
  data: () => props.task,
});

<script setup lang="ts">
import { computed } from 'vue';
import { useDnDProvider } from '@vue-dnd-kit/core';

const { entities } = useDnDProvider();
const task = computed(() => {
  const [node] = entities.draggingMap.keys();
  return node ? (entities.draggableMap.get(node)?.data?.() as Task) : null;
});
</script>

<template>
  <div class="task-preview">{{ task?.title }}</div>
</template>

v3

makeDraggable(el, {
  id: () => props.task.id,
  overlay: TaskOverlay,
  data: () => props.task,
});

<script setup lang="ts">
import { computed } from 'vue';
import type { DragItem, Over } from '@vue-dnd-kit/core';

const props = defineProps<{ items: DragItem[]; over: Over | null; accepted: boolean }>();
const task = computed(() => props.items[0]!.data as Task);
</script>

<template>
  <!-- Fills the overlay box, which takes the size of the slot. -->
  <div class="task-preview" :class="{ refused: over && !accepted }">
    {{ task.title }}
    <span v-if="items.length > 1" class="count">{{ items.length }}</span>
  </div>
</template>

<style scoped>
.task-preview { width: 100%; height: 100%; }
</style>

• Le composant reçoit le glissement en props : items (chaque item glissé, en commençant par celui qui a été saisi), over, accepted, status, mode et to. Ne déclarez que celles que vous lisez. Pour les lignes d'une liste, l'item de la liste est items[0].item.
• Passez-le tel quel. Changez-le avec un shallowRef, jamais avec une ref profonde.

Le slot du provider change de la même façon, et votre composant ne se positionne plus lui-même :

v2

<DnDProvider>
  <RouterView />
  <template #preview>
    <MyOverlay />  <!-- moved itself with useDnDProvider().preview.position -->
  </template>
</DnDProvider>

v3

<DnDProvider>
  <RouterView />
  <template #overlay="{ items, over, accepted }">
    <MyOverlay :items="items" :over="over" :accepted="accepted" />
  </template>
</DnDProvider>

Une apparition qui enveloppait DragPreview dans une <Transition> devient overlay-class avec @starting-style : voir soulever, incliner, reposer.

Un dépôt que vous confirmez

v2

makeDroppable(el, {
  events: {
    onDrop: (e) =>
      new Promise<void | boolean>((resolve) => {
        if (!window.confirm('Drop here?')) return resolve(false); // keep dragging
        place(e.draggedItems);
        resolve();
      }),
  },
});

v3

makeDroppable(el, {
  onBeforeDrop: () => (window.confirm('Drop here?') ? 'accept' : 'continue'),
  onDrop: (e) => place(e.active.items),
});

Une liste demande de la même façon, et une promesse vous permet d'ouvrir votre propre boîte de dialogue. L'overlay attend là où il a été lâché jusqu'à ce que la promesse soit réglée :

makeSortableList(el, {
  items: toRef(props.column, 'tasks'),
  group: 'board',
  // `ask` opens a dialog and resolves 'accept', 'continue' or 'reject'.
  onBeforeDrop: (e) => (e.sameList ? 'accept' : ask(e)),
});

Une zone qui ne prenait que la partie correspondante d'une sélection mixte (groupMatch: 'some') :

v2

makeDroppable(el, {
  groups: ['frontend'],
  groupMatch: 'some',
  events: {
    onDrop: (e) => place(e.draggedItems), // only the items of the group arrive
  },
});

v3

import type { DragItem } from '@vue-dnd-kit/core';

const fits = (item: DragItem) => item.type.length === 0 || item.type.includes('frontend');

makeDroppable(el, {
  accept: 'frontend',
  acceptMode: 'some',
  onBeforeDrop: (e) => e.active.items.filter(fits).map((item) => item.id), // the others fly back
  onDrop: (e) => place(e.active.items.filter(fits)), // `active.items` still lists every dragged item
});

Les listes le font sans code : avec acceptMode: 'some', les items que leur group.put accepte atterrissent, et les autres reviennent à leur place.

Les pièges de la mise à jour

• Installez la v3 avec sa plage de versions. ^3 dans package.json : un npm update garde ^2 en v2.
• Rendez le brouillon. Une liste rend les items que renvoie makeSortableList, pas votre tableau. Si vous rendez votre tableau, rien ne bouge avant le dépôt.
• Ne triez pas deux fois. Supprimez le code suggestSort des listes : une liste écrit chaque dépôt dans une ref items modifiable après son onDrop. Pour l'appliquer vous-même, appelez e.preventDefault() et utilisez e.result.
• false refuse le dépôt. En v2, un onDrop qui résolvait false laissait le glissement continuer. En v3, renvoyez 'continue' depuis onBeforeDrop. Une promesse renvoyée par onDrop est ignorée.
• Les listes ne partagent qu'au sein d'un group. Une liste sans group n'échange avec aucune autre liste.
• Indexez les lignes par id. :key="index" anime les mauvaises lignes. Passez aussi des ids issus de vos données : un id par défaut change à chaque instance du composant.
• Pas de <TransitionGroup>, pas de transition sur transform. La bibliothèque déplace les lignes elle-même, et les déplacements seraient animés deux fois.
• Défaites le contournement tactile. touch-action: none sur un item entier empêche la page de défiler sous le doigt ; la v3 démarre plutôt les glissements tactiles par un appui long. Gardez-le sur une poignée qui doit glisser tout de suite, avec activation: { touch: { distance: 4 } }.
• Retirez les attributs périmés. La bibliothèque définit le tabindex, le role et les aria-* dont elle a besoin et n'écrase jamais les vôtres, donc un role ou un aria-grabbed restant reste tel que vous l'avez laissé.
• Refaites le style de l'overlay. .dnd-kit-preview n'existe plus : stylez ce qui se trouve dans [data-dnd-overlay='dragging'], jamais le transform de la boîte. Donnez width: 100%; height: 100% à la racine d'un composant d'overlay, et retirez <DragPreview /> de vos layouts.
• Le défilement automatique est activé. Passez :auto-scroll="false" là où la v2 ne défilait jamais.
• Un rectangle de sélection n'a pas besoin de touche. makeSelectionArea trace à partir d'un simple appui sur son espace vide. Ajoutez un modifier pour garder le Ctrl de la v2.
• Un provider, des zones à l'intérieur. Les items ne peuvent pas passer d'un provider à l'autre. Une page qui utilisait un provider par région pour séparer leurs règles a besoin d'un provider et d'un makeDragArea par région.
• Deux arguments. makeDraggable et makeDroppable prennent une ref et un objet d'options, pas de payload.