Documentação/API
Animações
As opções e os hooks das animações — a ordenação, o drop e as mudanças que nenhum arraste fez.
Esta página foi traduzida por IA e pode conter imprecisões. Ler o original em inglês
animation (movimentos de layout durante a ordenação), dropAnimation (o overlay pousando) e
animateChanges (mudanças de dados que nenhum arraste fez) do provider aceitam false, opções ou uma
função sua — para GSAP ou motion. Listas e árvores podem sobrescrever animation e animateChanges;
draggables, itens e listas podem trazer o seu próprio dropAnimation, e alvos de drop, um
overDropAnimation. Veja
Animações.
<DnDProvider :animation="{ duration: 180, easing: 'ease-out' }" :drop-animation="false" />
Cada faixa abaixo é um provider próprio que dá a animation, dropAnimation e
animateChanges o mesmo tipo de valor (animateChanges recebe uma função em move).
Carregando a demo…
<script setup lang="ts">
import { ref } from 'vue';
import { DnDProvider, type AutoAnimation, type DropAnimation, type LayoutAnimation } from '@vue-dnd-kit/core';
import AnimLane from './AnimLane.vue';
import { tiltDrop, tiltMove } from './tilt';
const SLOW = { duration: 700, easing: 'ease-in-out' };
// One shape per lane, for all three options: sorting, the drop, and changes no drag made.
const lanes: { label: string; animation: LayoutAnimation; dropAnimation: DropAnimation; animateChanges: AutoAnimation }[] = [
{ label: 'true', animation: true, dropAnimation: true, animateChanges: true },
{ label: 'false', animation: false, dropAnimation: false, animateChanges: false },
{ label: '{ duration: 700 }', animation: SLOW, dropAnimation: SLOW, animateChanges: SLOW },
// `animateChanges` takes no function itself: its parts (`move`, `enter`, `leave`) do.
{ label: 'ƒ tilt', animation: tiltMove, dropAnimation: tiltDrop, animateChanges: { move: tiltMove } },
];
const letters = ['A', 'B', 'C', 'D'];
const rows = ref(lanes.map(() => letters.map((id, i) => ({ id, hue: 150 + i * 40 }))));
/** The same new order in every lane (Fisher–Yates: every order as likely): `animateChanges` plays it four ways. */
const shuffle = () => {
const order = [...letters];
for (let i = order.length - 1; i > 0; i--) {
const j = Math.floor(Math.random() * (i + 1));
[order[i], order[j]] = [order[j]!, order[i]!];
}
rows.value = rows.value.map((lane) => order.map((id) => lane.find((row) => row.id === id)!));
};
</script>
<template>
<div class="demo">
<code><DnDProvider :animation="shape" :drop-animation="shape" :animate-changes="shape"></code>
<div class="lanes">
<!-- A provider per lane: each one has its own animations. -->
<DnDProvider
v-for="(lane, index) in lanes"
:key="lane.label"
:animation="lane.animation"
:drop-animation="lane.dropAnimation"
:animate-changes="lane.animateChanges"
>
<AnimLane v-model="rows[index]!" :label="lane.label" />
</DnDProvider>
</div>
<button type="button" @click="shuffle">Shuffle all</button>
</div>
</template>
<style scoped>
.demo {
display: flex;
flex-direction: column;
align-items: center;
gap: 14px;
}
code {
max-width: 100%;
font: 11px/1.4 ui-monospace, Menlo, Consolas, monospace;
text-align: center;
opacity: 0.7;
}
button {
padding: 6px 12px;
border: 0;
border-radius: 8px;
background: #42b883;
color: #fff;
font: 600 12px/1 system-ui, sans-serif;
cursor: pointer;
}
button:focus-visible {
outline: 2px solid currentColor;
outline-offset: 2px;
}
.lanes {
display: grid;
grid-template-columns: repeat(4, 128px);
gap: 8px;
}
@media (max-width: 560px) {
.lanes {
grid-template-columns: repeat(2, 128px);
}
}
</style>Opções
O tempo de uma animação. O que ficar de fora mantém o padrão daquela animação.
Ordenação
Como os itens se movem para os novos lugares: true (tempo padrão), opções, false (eles saltam), ou uma função que anima um item de from até to e retorna a Animation dele, uma promise que é resolvida quando ela termina, ou nada.
type LayoutAnimation = | boolean | AnimationOptions | ((context: LayoutAnimationContext) => Animation | Promise<unknown> | void)O que uma função de animação de layout recebe, para um item que se move para o seu novo lugar.
KeyA key do item.
HTMLElementO elemento do item, já no seu novo lugar.
RectRetângulo visual antes da mudança (onde uma animação em andamento mostrava o item).
RectRetângulo de layout depois da mudança.
Required<AnimationOptions>O tempo dado pelas opções, com os padrões preenchidos.
'drag' | 'change'O que moveu o item: um arraste ('drag': a ordenação, o drop, um cancelamento), ou uma mudança nos seus dados que nenhum arraste fez ('change', com o animateChanges da lista ligado).
AbortSignalAbortado quando a biblioteca interrompe a animação: o item se move de novo antes de ela terminar (a próxima animação começa de onde ele está sendo mostrado), ou as animações são desligadas. Uma Animation retornada é cancelada automaticamente. Pare qualquer outra coisa aqui e desfaça os estilos que ela definiu, na hora: o layout é medido logo em seguida.
booleanprefers-reduced-motion: reduce está ativo. Nesse caso, as animações da própria biblioteca não rodam; as suas funções sempre rodam, e decidem com isto (pular, ou manter um fade).
O drop
Como o overlay pousa em um drop e volta ao lugar em um cancelamento: true (tempo padrão), opções, false (sem voo: ele termina onde foi solto), ou uma função que anima overlay de from até to e retorna a Animation dele, uma promise que é resolvida quando ela termina, ou nada.
type DropAnimation = | boolean | AnimationOptions | ((context: DropAnimationContext) => Animation | Promise<unknown> | void)O que uma função de animação de drop recebe: o overlay, onde ele está e onde ele pousa.
HTMLElementA caixa do overlay; ela pousa na posição do item ativo. Em um multi-drag, os clones dos outros itens que viajam dentro dela (os do overlay padrão, os DragPreviews de um personalizado) pousam sozinhos nas suas próprias posições (com o tempo padrão quando isto é uma função personalizada).
RectOnde o overlay está quando o arraste termina.
Rect | nullRetângulo final do item solto; null quando ele não está renderizado ou visível (o overlay desaparece aos poucos).
Rect | nullO item não é mostrado depois de um drop em uma zona (não uma lista ordenável), por exemplo, ele foi solto dentro de outro item (uma pasta) ou de uma zona de lixeira: o retângulo visível da zona. A animação padrão encolhe o overlay para dentro dela enquanto ele desaparece, em vez de desaparecer no lugar.
'drop' | 'cancel''drop': o overlay pousa onde o drop colocou o item. 'cancel': ele volta ao lugar onde o item estava.
ActiveO arraste que terminou.
Over | nullO alvo em que o drop pousa (uma lista, uma zona); null no cancelamento.
Required<AnimationOptions>O tempo dado pelas opções, com os padrões preenchidos.
booleanprefers-reduced-motion: reduce está ativo. Nesse caso, as animações da própria biblioteca não rodam; as suas funções sempre rodam, e decidem com isto (pular, ou manter um fade).
Mudanças de dados
Anima as mudanças nos itens de uma lista (ou árvore) que nenhum arraste fez: itens adicionados, removidos, movidos (uma ordenação, um embaralhamento, um movimento entre listas de um mesmo grupo) ou filtrados. Desligado por padrão (false); true anima movimentos, itens que entram e itens que saem com o tempo padrão. Os arrastes mantêm as próprias animações (animation, dropAnimation). Com prefers-reduced-motion: reduce, as animações padrão não rodam; as suas funções ainda rodam (com reducedMotion: true). Só os itens perto da área visível são animados (as linhas desmontadas de uma lista virtual são ignoradas).
type AutoAnimation = boolean | AutoAnimationOptionsanimateChanges com as suas partes: duration e easing para todas elas, e, por tipo de mudança, true, opções (sobre as compartilhadas), false ou uma função sua.
LayoutAnimationItens que trocaram de lugar (o FLIP padrão, como o de animation; uma função o substitui).
EnterAnimationItens que apareceram. Padrão: eles surgem aos poucos onde estão.
LeaveAnimationItens que saíram. Padrão: uma cópia do item desaparece aos poucos onde ele estava, encolhendo um pouco.
true, opções, false (o item simplesmente aparece), ou uma função que anima a entrada dele.
type EnterAnimation = | boolean | AnimationOptions | ((context: EnterAnimationContext) => Animation | Promise<unknown> | void)Um item que apareceu em uma lista com animateChanges ligado: adicionado, ou mostrado de novo (um filtro, um nó de árvore expandido).
KeyA key do item.
HTMLElementO elemento do item, já no lugar dele.
RectOnde ele apareceu (retângulo de layout).
Required<AnimationOptions>O tempo dado pelas opções, com os padrões preenchidos.
booleanprefers-reduced-motion: reduce está ativo. Nesse caso, as animações da própria biblioteca não rodam; as suas funções sempre rodam, e decidem com isto (pular, ou manter um fade).
true, opções, false (o item simplesmente desaparece), ou uma função que anima a saída da cópia deixada no lugar dele: retorne a Animation dela ou uma promise, e a cópia é removida quando ela terminar (na hora, quando a função não retorna nada).
type LeaveAnimation = | boolean | AnimationOptions | ((context: LeaveAnimationContext) => Animation | Promise<unknown> | void)Um item que saiu de uma lista com animateChanges ligado: removido, ou ocultado (um filtro, um nó de árvore recolhido).
KeyA key do item.
HTMLElementUma cópia do elemento do item, mostrada onde o item estava (o próprio item já se foi): posicionada de forma absoluta no pai antigo, ignorando o ponteiro, marcada com data-dnd-leaving. A biblioteca a remove quando a sua animação termina.
RectOnde o item estava.
Required<AnimationOptions>O tempo dado pelas opções, com os padrões preenchidos.
booleanprefers-reduced-motion: reduce está ativo. Nesse caso, as animações da própria biblioteca não rodam; as suas funções sempre rodam, e decidem com isto (pular, ou manter um fade).