Migration von v2

v3 ist eine Neufassung von v2. Das Modell bleibt: ein Provider und Composables, die du auf deinen eigenen Elementen aufrufst. Aber die meisten Namen und Optionen haben sich geändert, das Sortieren ist in die Bibliothek gewandert, und der Drop-Handler, den du für jede Liste geschrieben hast, fällt weg. Diese Seite ordnet jeden Teil von v2 seinem Gegenstück in v3 zu und zeigt dann die häufigen Fälle vorher und nachher.

Was sich geändert hat

• Sortieren ist eingebaut. In v2 war eine Liste eine Drop-Zone, ihre Zeilen waren ziehbare Elemente mit einem Payload [index, items], und du hast in onDrop mit e.helpers.suggestSort() sortiert. In v3 erledigen das makeSortableList und makeSortableItem: Die Liste rendert einen Entwurf deines Arrays, der sich während des Ziehens neu ordnet, und der Drop schreibt das neue Array in dein Ref. Die meisten v2-Drop-Handler werden gelöscht, nicht portiert.
• Dinge bewegen sich von selbst. Zeilen gleiten an ihre neuen Plätze (FLIP), das Overlay landet beim Drop in seinem Slot und fliegt beim Abbrechen zurück. <TransitionGroup> fällt weg.
• Weiterhin ein Paket. @vue-dnd-kit/core enthält Listen, Bäume, Multi-Drag, Modifier, Sensoren und die Kollisionsfunktionen. Das Nuxt-Modul bleibt; @vue-dnd-kit/actions (programmatisches Ziehen) und @vue-dnd-kit/devtools sind neu und optional.
• Ein echtes Overlay. Es wird nach body teleportiert und zeigt einen tiefen Klon, so groß wie der Slot, in dem es landen wird. Overlay-Komponenten bekommen den Drag als Props, statt die Interna des Providers zu lesen.
• IDs statt Elemente. Die Auswahl, die Events und der Zustand des Drags sind nach IDs aus deinen Daten geschlüsselt. Es gibt keine Maps von DOM-Elementen mehr zu lesen.
• Typen und Annahmeregeln ersetzen groups für einfache ziehbare Elemente und Ziele. Listen tauschen Elemente über den Namen ihrer group aus.
• Entscheidungen vor dem Drop. onBeforeDrop nimmt an, lehnt ab, lässt den Drag weiterlaufen oder nimmt nur einen Teil der Elemente. onDrop wendet nur noch an.
• Sensoren. Zeiger- und Tastatureingaben sind Sensoren. Die Aktivierung wird pro Zeigerart festgelegt, und Touch-Drags beginnen mit langem Drücken, sodass Listen unter dem Finger weiter scrollen.
• Bereiche. makeDragArea ersetzt makeConstraintArea und makeAutoScroll, und Auto-Scroll funktioniert ohne Code in jedem Scroll-Container.
• Barrierefreiheit ist standardmäßig an: ARIA-Attribute, ein Fokus, der nach dem Drop zurückkehrt, und Ansagen für Screenreader.

Upgrade

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

• Eine App, die "@vue-dnd-kit/core": "^2…" in ihrer package.json hat, bleibt auf v2, bis der Versionsbereich ^3 sagt.
• Vue 3.5 oder neuer. v2 hatte keine Abhängigkeiten; v3 hat eine, @vueuse/core (14 oder 15).
• Browser: Chrome und Edge 104+, Safari 15.4+, Firefox 104+.
• v2 und v3 teilen sich einen Paketnamen, also wechselt eine App in einem Schritt auf v3. Es gibt keine Kompatibilitätsschicht. Die v2-Dokumentation bleibt über das Versionsmenü oben auf der Seite erreichbar.

Eine gute Reihenfolge:

1. Aktualisiere die Pakete und benenne die Props des Providers um (unten).
2. Mach aus jeder sortierbaren Liste makeSortableList und makeSortableItem, und lösche ihren Drop-Handler.
3. Portiere die einfachen ziehbaren Elemente und Drop-Zonen.
4. Portiere eigene Vorschauen auf Overlay-Komponenten oder den Slot #overlay des Providers.
5. Ersetze makeConstraintArea und makeAutoScroll durch makeDragArea oder durch nichts.
6. Lösche die v2-Workarounds: tabindex und aria-grabbed auf ziehbaren Elementen, touch-action: none auf ganzen Elementen, <TransitionGroup> um Zeilen, markRaw um Vorschau-Komponenten.

Alt zu neu

Keine Entsprechung in einer Tabelle heißt, dass v3 nichts unter diesem Namen hat; die Zelle sagt, was du stattdessen verwendest.

Auf einen Blick

Der Provider

Neue Props ohne Gegenstück in v2: activation, modifiers, sensors, animation, dropAnimation, animateChanges, haptics, copyModifier, overlayFit, overlayClass, overlayTransition, overlayPreviews, announcements, screenReaderInstructions und defaultStyles. Der Provider emittiert außerdem drag-start, drag-move, drag-over, drag-end, drag-cancel, drag-resume und drag-settle. Alles davon steht im Leitfaden Der Provider.

Den Zustand lesen: useDnD

Die Events sind zu useDnDMonitor gewandert: siehe Events und Drop-Entscheidungen. Die vollständigen Formen stehen in der useDnD-API.

makeDraggable

makeDroppable

Das Drop-Event

Sortieren

Der Code vorher und nachher steht unten. Alles über Listen steht in Sortierbare Listen und Listen mit gemeinsamen Elementen.

Gruppen

v2 hatte eine Option groups für alles. v3 teilt sie in zwei:

Eine Liste ohne group ist eine eigene Gruppe und tauscht mit keiner anderen Liste. In v2 nahm eine Zone ohne Gruppen alles an. Siehe Welche Drags ein Ziel annimmt.

Das Overlay

Mehr im Leitfaden Das Overlay.

Auswahl und Multi-Drag

Mehr in Multi-Drag und Auswahl.

Achsen, Grenzen und Einrasten

Mehr in Achsen, Grenzen und Raster.

Auto-Scroll

Tastatur und Barrierefreiheit

Mehr in Barrierefreiheit.

Events und Drop-Entscheidungen

Ein v2-onDrop konnte einen Wert oder ein Promise darauf zurückgeben, um über den Drop zu entscheiden. In v3 ist das die Aufgabe von onBeforeDrop, auf Listen, Bäumen, Drop-Zielen und Monitoren:

Die Monitore antworten zuerst, dann das Ziel. Danach läuft das onDrop des Ziels, eine Liste schreibt ihre neuen Arrays, und onDragEnd folgt. Mehr in Über einen Drop entscheiden und in der Events-API.

Typen

Nuxt

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

modules: ['@vue-dnd-kit/nuxt'] in nuxt.config.ts bleibt, wie es war. Siehe Installation.

Vorher und nachher

Ein ziehbares Element und eine Drop-Zone

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>

• Die Karte bekommt tabindex, role und die aria-*-Attribute von selbst. Ein <button> als Handle ist fokussierbar, und Drags per Tastatur starten von ihm aus.
• Aus groups wurde type auf dem ziehbaren Element und accept auf dem Ziel. Die Callbacks haben das events-Objekt verlassen.
• isOver ohne isAccepting ist ein Ziel, das den Drag ablehnt: Ein Drop dort fliegt zurück.

Eine sortierbare Liste

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>

• Rendere items, den Entwurf: Er ordnet sich während des Ziehens neu. tasks bekommt beim Drop die neue Reihenfolge, und defineModel emittiert update:modelValue.
• Kein Index, kein Payload, kein onDrop, kein <TransitionGroup>: Die Zeilen gleiten von selbst.
• Die gezogene Zeile bleibt als der Slot, in dem sie landen wird, in der Liste. Style sie mit isPlaceholder oder [data-dnd-placeholder], statt sie zu verstecken.

Listen mit gemeinsamen Elementen

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>

Der Drop schreibt beide Arrays, das, das die Aufgabe verlassen hat, und das, in das sie gekommen ist. TaskItem.vue ist das aus der sortierbaren Liste oben. Eine Palette, die Kopien austeilt, war suggestCopy() und ein Flag copyOnly; jetzt ist sie eine 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() }),
});

Für einen Pinia-Store oder anderen Zustand, den du nicht direkt schreibst, übergib items als Getter, rufe e.preventDefault() in onDrop auf und wende e.result an: siehe Kontrollierte Listen.

Ein eigenes Overlay

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>

• Die Komponente bekommt den Drag als Props: items (jedes gezogene Element, das gegriffene zuerst), over, accepted, status, mode und to. Deklariere nur die, die du liest. Bei den Zeilen einer Liste ist das Listenelement items[0].item.
• Übergib sie, wie sie ist. Wechsle sie mit einem shallowRef, nie mit einem tiefen ref.

Der Slot des Providers ändert sich genauso, und deine Komponente positioniert sich nicht mehr selbst:

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>

Ein Einblenden, das DragPreview in ein <Transition> gepackt hat, wird zu overlay-class mit @starting-style: siehe Das Overlay: anheben, neigen, ablegen.

Ein Drop, den du bestätigst

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),
});

Eine Liste fragt genauso, und mit einem Promise kannst du einen eigenen Dialog öffnen. Das Overlay wartet dort, wo es losgelassen wurde, bis das Promise erledigt ist:

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)),
});

Eine Zone, die nur den passenden Teil einer gemischten Auswahl angenommen hat (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
});

Listen tun das ohne Code: Mit acceptMode: 'some' landen die Elemente, die ihr group.put annimmt, und die anderen fliegen zurück.

Stolperfallen beim Upgrade

• Installiere v3 mit ihrem Versionsbereich. ^3 in package.json: Ein npm update hält ^2 auf v2.
• Rendere den Entwurf. Eine Liste rendert die items, die makeSortableList zurückgibt, nicht dein Array. Renderst du dein Array, bewegt sich bis zum Drop nichts.
• Sortiere nicht doppelt. Lösche den suggestSort-Code aus Listen: Eine Liste schreibt jeden Drop nach ihrem onDrop in ein beschreibbares items-Ref. Um ihn selbst anzuwenden, rufe e.preventDefault() auf und verwende e.result.
• false lehnt den Drop ab. In v2 hielt ein onDrop, das false auflöste, den Drag am Laufen. In v3 gibst du 'continue' aus onBeforeDrop zurück. Ein Promise, das onDrop zurückgibt, wird ignoriert.
• Listen teilen nur innerhalb einer group. Eine Liste ohne group tauscht mit keiner anderen Liste.
• Schlüssle Zeilen nach ID. :key="index" animiert die falschen Zeilen. Übergib auch IDs aus deinen Daten: Eine Standard-ID ist für jede Komponenteninstanz neu.
• Kein <TransitionGroup>, kein transition auf transform. Die Bibliothek bewegt die Zeilen selbst, und Bewegungen würden doppelt animiert.
• Mach den Touch-Workaround rückgängig. touch-action: none auf einem ganzen Element verhindert, dass die Seite unter dem Finger scrollt; v3 startet Touch-Drags stattdessen mit langem Drücken. Behalte es auf einem Handle, das sofort ziehen soll, mit activation: { touch: { distance: 4 } }.
• Entferne veraltete Attribute. Die Bibliothek setzt tabindex, role und die aria-*, die sie braucht, und überschreibt deine nie, also bleibt ein übrig gebliebenes role oder aria-grabbed so, wie du es hinterlassen hast.
• Style das Overlay neu. .dnd-kit-preview gibt es nicht mehr: Style, was in [data-dnd-overlay='dragging'] steckt, nie das transform der Box. Gib der Wurzel einer Overlay-Komponente width: 100%; height: 100%, und nimm <DragPreview /> aus deinen Layouts.
• Auto-Scroll ist an. Übergib :auto-scroll="false", wo v2 nie gescrollt hat.
• Ein Auswahlrahmen braucht keine Taste. makeSelectionArea zeichnet bei einem einfachen Druck auf seine leere Fläche. Füge einen modifier hinzu, um das Strg von v2 zu behalten.
• Ein Provider, Bereiche darin. Elemente können nicht zwischen Providern wechseln. Eine Seite, die einen Provider pro Region verwendet hat, um deren Regeln zu trennen, braucht einen Provider und ein makeDragArea pro Region.
• Zwei Argumente. makeDraggable und makeDroppable nehmen ein Ref und ein Optionsobjekt, kein Payload.