Migrando da v2

A v3 é uma reescrita da v2. O modelo continua: um provider, e composables que você chama nos seus próprios elementos. Mas a maioria dos nomes e das opções mudou, a ordenação passou para dentro da biblioteca, e o handler de drop que você escrevia para cada lista vai embora. Esta página mapeia cada parte da v2 para a v3 e depois mostra os casos comuns antes e depois.

O que mudou

• A ordenação vem embutida. Na v2, uma lista era uma zona de drop, as linhas dela eram draggables com um payload [index, items], e você ordenava no onDrop com e.helpers.suggestSort(). Na v3, makeSortableList e makeSortableItem fazem isso: a lista renderiza um rascunho do seu array que se reordena enquanto você arrasta, e o drop grava o novo array no seu ref. A maioria dos handlers de drop da v2 é apagada, não portada.
• As coisas se movem sozinhas. As linhas deslizam para os novos lugares (FLIP), o overlay pousa na sua posição no drop e volta ao lugar no cancelamento. O <TransitionGroup> vai embora.
• Continua um pacote só. @vue-dnd-kit/core contém listas, árvores, multi-drag, modificadores, sensores e as funções de colisão. O módulo do Nuxt continua; @vue-dnd-kit/actions (arrastes programáticos) e @vue-dnd-kit/devtools são novos e opcionais.
• Um overlay de verdade. Ele é teleportado para o body e mostra um clone profundo, do tamanho da posição onde vai pousar. Componentes de overlay recebem o arraste como props em vez de ler o funcionamento interno do provider.
• Ids, não elementos. A seleção, os eventos e o estado do arraste usam como chave ids dos seus dados. Não há mapas de elementos do DOM para ler.
• Tipos e regras de aceitação substituem groups para draggables simples e alvos. As listas trocam itens pelo nome do group.
• Decisões antes do drop. onBeforeDrop aceita, recusa, mantém o arraste em andamento ou fica com parte dos itens. onDrop só aplica.
• Sensores. A entrada de ponteiro e a de teclado são sensores. A ativação é definida por tipo de ponteiro, e os arrastes por toque começam com um toque longo, então as listas continuam rolando sob o dedo.
• Áreas. makeDragArea substitui makeConstraintArea e makeAutoScroll, e a rolagem automática funciona em todo contêiner com rolagem, sem código.
• A acessibilidade vem ligada por padrão: atributos ARIA, o foco que volta depois do drop e anúncios para leitores de tela.

Atualização

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

• Um app que tem "@vue-dnd-kit/core": "^2…" no package.json fica na v2 até a faixa de versões dizer ^3.
• Vue 3.5 ou mais novo. A v2 não tinha dependências; a v3 tem uma, @vueuse/core (14 ou 15).
• Navegadores: Chrome e Edge 104+, Safari 15.4+, Firefox 104+.
• A v2 e a v3 compartilham o nome do pacote, então um app passa para a v3 de uma vez. Não há camada de compatibilidade. A documentação da v2 continua disponível no menu de versões no topo da página.

Uma boa ordem de trabalho:

1. Atualize os pacotes e renomeie as props do provider (abaixo).
2. Transforme cada lista ordenável em makeSortableList e makeSortableItem, e apague o handler de drop dela.
3. Porte os draggables simples e as zonas de drop.
4. Porte as prévias personalizadas para componentes de overlay ou para o slot #overlay do provider.
5. Substitua makeConstraintArea e makeAutoScroll por makeDragArea, ou por nada.
6. Apague os contornos da v2: tabindex e aria-grabbed nos draggables, touch-action: none em itens inteiros, <TransitionGroup> em volta das linhas, markRaw em volta dos componentes de prévia.

Do antigo para o novo

Sem equivalente em uma tabela quer dizer que a v3 não tem nada com aquele nome; a célula diz o que usar no lugar.

Visão geral

O provider

Props novas sem correspondente na v2: activation, modifiers, sensors, animation, dropAnimation, animateChanges, haptics, copyModifier, overlayFit, overlayClass, overlayTransition, overlayPreviews, announcements, screenReaderInstructions e defaultStyles. O provider também emite drag-start, drag-move, drag-over, drag-end, drag-cancel, drag-resume e drag-settle. Tudo isso está no guia do provider.

Lendo o estado: useDnD

Os eventos foram para o useDnDMonitor: veja eventos e decisões de drop. As formas completas estão na API do useDnD.

makeDraggable

makeDroppable

O evento de drop

Ordenação

O código antes e depois está abaixo. Tudo sobre listas está em listas ordenáveis e listas que compartilham itens.

Grupos

A v2 tinha uma opção groups para tudo. A v3 a divide em duas:

Uma lista sem group é um grupo próprio e não troca itens com nenhuma outra lista. Na v2, uma zona sem grupos aceitava tudo. Veja quais arrastes um alvo aceita.

O overlay

Mais no guia do overlay.

Seleção e multi-drag

Mais em multi-drag e seleção.

Eixos, limites e encaixe

Mais em eixos, limites e grades.

Rolagem automática

Teclado e acessibilidade

Mais em acessibilidade.

Eventos e decisões de drop

Um onDrop da v2 podia retornar um valor, ou uma promise de um valor, para decidir o drop. Na v3 esse é o papel do onBeforeDrop, em listas, árvores, alvos de drop e monitores:

Os monitores respondem primeiro, depois o alvo. Então o onDrop do alvo roda, uma lista grava os novos arrays, e o onDragEnd vem em seguida. Mais em decidindo um drop e na API de eventos.

Tipos

Nuxt

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

modules: ['@vue-dnd-kit/nuxt'] no nuxt.config.ts continua como estava. Veja instalação.

Antes e depois

Um draggable e uma zona de drop

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>

• O card recebe tabindex, role e os atributos aria-* sozinho. Um handle <button> pode receber foco, e os arrastes por teclado começam a partir dele.
• groups virou type no draggable e accept no alvo. Os callbacks saíram do objeto events.
• isOver sem isAccepting é um alvo que recusa o arraste: um drop ali volta ao lugar.

Uma lista ordenável

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>

• Renderize items, o rascunho: ele se reordena enquanto você arrasta. tasks recebe a nova ordem no drop, e defineModel emite update:modelValue.
• Sem índice, sem payload, sem onDrop, sem <TransitionGroup>: as linhas deslizam sozinhas.
• A linha arrastada fica na lista como a posição onde vai pousar. Estilize-a com isPlaceholder ou [data-dnd-placeholder] em vez de escondê-la.

Listas que compartilham itens

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>

O drop grava os dois arrays, o que a tarefa deixou e o em que ela entrou. TaskItem.vue é o da lista ordenável acima. Uma paleta que distribui cópias era suggestCopy() e uma flag copyOnly; agora é uma lista:

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

Para um store Pinia ou outro estado que você não grava diretamente, passe items como getter, chame e.preventDefault() no onDrop e aplique e.result: veja listas controladas.

Um overlay personalizado

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>

• O componente recebe o arraste como props: items (cada item arrastado, começando pelo que foi pego), over, accepted, status, mode e to. Declare só as que você lê. Para as linhas de uma lista, o item da lista é items[0].item.
• Passe-o como está. Troque-o com um shallowRef, nunca com um ref profundo.

O slot do provider muda do mesmo jeito, e o seu componente não se posiciona mais sozinho:

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>

Uma entrada animada que envolvia o DragPreview em um <Transition> vira overlay-class com @starting-style: veja erguer, inclinar, assentar.

Um drop que você confirma

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

Uma lista pergunta do mesmo jeito, e uma promise permite abrir um diálogo seu. O overlay espera onde foi solto até a promise terminar:

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

Uma zona que aceitava só a parte correspondente de uma seleção mista (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
});

As listas fazem isso sem código: com acceptMode: 'some', os itens que o group.put delas aceita pousam, e os outros voltam ao lugar.

Armadilhas ao atualizar

• Instale a v3 com a faixa dela. ^3 no package.json: um npm update mantém ^2 na v2.
• Renderize o rascunho. Uma lista renderiza os items que makeSortableList retorna, não o seu array. Renderizando o seu array, nada se move até o drop.
• Não ordene duas vezes. Apague o código de suggestSort das listas: uma lista grava cada drop em um ref items gravável depois do onDrop dela. Para aplicá-lo você mesmo, chame e.preventDefault() e use e.result.
• false recusa o drop. Na v2, um onDrop que resolvia false mantinha o arraste em andamento. Na v3, retorne 'continue' do onBeforeDrop. Uma promise retornada do onDrop é ignorada.
• Listas só compartilham dentro de um group. Uma lista sem um não troca itens com nenhuma outra lista.
• Use ids como key das linhas. :key="index" anima as linhas erradas. Passe ids a partir dos seus dados também: um id padrão é novo a cada instância do componente.
• Nada de <TransitionGroup>, nada de transition em transform. A biblioteca move as linhas ela mesma, e os movimentos seriam animados duas vezes.
• Desfaça o contorno para toque. touch-action: none em um item inteiro impede a página de rolar sob o dedo; a v3 começa os arrastes por toque com um toque longo. Mantenha-o em um handle que deve arrastar na hora, com activation: { touch: { distance: 4 } }.
• Remova atributos obsoletos. A biblioteca define o tabindex, o role e os aria-* de que precisa e nunca sobrescreve os seus, então um role ou um aria-grabbed que sobrou fica como você o deixou.
• Refaça o estilo do overlay. .dnd-kit-preview não existe mais: estilize o que está dentro de [data-dnd-overlay='dragging'], nunca o transform da caixa. Dê width: 100%; height: 100% à raiz de um componente de overlay, e tire <DragPreview /> dos seus layouts.
• A rolagem automática está ligada. Passe :auto-scroll="false" onde a v2 nunca rolava.
• Um retângulo de seleção não precisa de tecla. makeSelectionArea desenha a partir de um simples pressionar no espaço vazio dela. Adicione um modifier para manter o Ctrl da v2.
• Um provider, áreas dentro dele. Itens não podem passar de um provider para outro. Uma página que usava um provider por região para manter as regras separadas precisa de um provider e de um makeDragArea por região.
• Dois argumentos. makeDraggable e makeDroppable recebem um ref e um objeto de opções, sem payload.