Documentación/API

Animaciones

Las opciones y los hooks de las animaciones — la ordenación, el drop y los cambios que no vienen de un arrastre.

Esta página la ha traducido una IA y puede contener imprecisiones. Leer el original en inglés

Las props animation (movimientos de layout al ordenar), dropAnimation (el aterrizaje del overlay) y animateChanges (cambios de datos que no vienen de un arrastre) del provider aceptan false, opciones o tu propia función — para GSAP o motion. Las listas y los árboles pueden sobrescribir animation y animateChanges; los elementos arrastrables, los ítems y las listas pueden traer su propia dropAnimation, y los destinos de drop una overDropAnimation. Consulta Animaciones.

<DnDProvider :animation="{ duration: 180, easing: 'ease-out' }" :drop-animation="false" />

Cada carril de abajo es un provider propio que da a animation, dropAnimation y animateChanges el mismo tipo de valor (animateChanges acepta una función en move).

Live Baraja, o arrastra una fila en cada carril

Cargando la 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>&lt;DnDProvider :animation="shape" :drop-animation="shape" :animate-changes="shape"&gt;</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>

Opciones

Los tiempos de una animación. Lo que se omite conserva el valor por defecto de esa animación.

duration?

number

En ms. Por defecto 200 para los movimientos de layout, 250 para el drop; 0 desactiva la animación.

easing?

string

Un easing de CSS ('ease-out', cubic-bezier(…)).

Ordenación

Cómo se mueven los ítems a su nuevo sitio: true (tiempos por defecto), opciones, false (saltan directamente) o una función que anima un ítem de from a to y devuelve su Animation, una promesa que se resuelve cuando termina, o nada.

type LayoutAnimation = | boolean | AnimationOptions | ((context: LayoutAnimationContext) => Animation | Promise<unknown> | void)

Lo que recibe una función de animación de layout, para un ítem que se mueve a su nuevo sitio.

key

Key

Clave del ítem.

element

HTMLElement

El elemento del ítem, ya en su nuevo sitio.

from

Rect

Rectángulo visual antes del cambio (donde una animación en curso mostraba el ítem).

Rect

Rectángulo de layout después del cambio.

options

Required<AnimationOptions>

Los tiempos que dan las opciones, con los valores por defecto ya puestos.

reason

'drag' | 'change'

Qué movió el ítem: un arrastre ('drag': la ordenación, el drop, una cancelación), o un cambio de tus datos que no vino de un arrastre ('change', con la opción animateChanges de la lista activada).

signal

AbortSignal

Se aborta cuando la biblioteca interrumpe la animación: el ítem se vuelve a mover antes de que termine (la siguiente animación empieza donde se muestra), o se desactivan las animaciones. Una Animation devuelta se cancela por ti. Detén aquí cualquier otra cosa y deshaz al instante los estilos que haya puesto: el layout se mide justo después.

reducedMotion

boolean

prefers-reduced-motion: reduce está activo. Las animaciones propias de la biblioteca no se ejecutan entonces; las funciones tuyas se ejecutan siempre, y deciden con este valor (omitir el movimiento o mantener un fundido).

El drop

Cómo aterriza el overlay al soltar y vuelve volando al cancelar: true (tiempos por defecto), opciones, false (sin vuelo: termina donde se soltó) o una función que anima overlay de from a to y devuelve su Animation, una promesa que se resuelve cuando termina, o nada.

type DropAnimation = | boolean | AnimationOptions | ((context: DropAnimationContext) => Animation | Promise<unknown> | void)

Lo que recibe una función de animación al soltar: el overlay, dónde está y dónde aterriza.

overlay

HTMLElement

La caja del overlay; aterriza en el hueco del ítem activo. En un multi-drag, los clones de los demás ítems que viajan dentro de ella (los del overlay por defecto, los DragPreview de uno personalizado) aterrizan por sí solos en sus propios huecos (con los tiempos por defecto cuando esta es una función personalizada).

from

Rect

Dónde está el overlay cuando termina el arrastre.

Rect | null

Rectángulo final del ítem soltado; null cuando no está renderizado o no es visible (el overlay se desvanece).

into

Rect | null

El ítem no se muestra después de un drop sobre una zona (no una lista ordenable), por ejemplo porque se soltó dentro de otro ítem (una carpeta) o en una zona de papelera: el rectángulo visible de la zona. La animación por defecto encoge el overlay dentro de ella mientras se desvanece, en lugar de desvanecerse en el sitio.

reason

'drop' | 'cancel'

'drop': el overlay aterriza donde el drop puso el ítem. 'cancel': vuelve volando a donde estaba el ítem.

active

Active

El arrastre que terminó.

over

Over | null

El destino en el que aterriza el drop (una lista, una zona); null al cancelar.

options

Required<AnimationOptions>

Los tiempos que dan las opciones, con los valores por defecto ya puestos.

reducedMotion

boolean

Cambios de datos

Anima los cambios de los ítems de una lista (o de un árbol) que no vienen de un arrastre: ítems añadidos, quitados, movidos (una ordenación, un barajado, un movimiento entre listas de un mismo grupo) o filtrados. Desactivado por defecto (false); true anima los movimientos, las entradas y las salidas de ítems con los tiempos por defecto. Los arrastres mantienen sus propias animaciones (animation, dropAnimation). Con prefers-reduced-motion: reduce las animaciones por defecto no se ejecutan; las funciones tuyas sí (con reducedMotion: true). Solo se animan los ítems cercanos al área visible (se omiten las filas no montadas de una lista virtual).

type AutoAnimation = boolean | AutoAnimationOptions

animateChanges con sus partes: duration y easing para todas, y por cada tipo de cambio true, opciones (sobre las compartidas), false o una función propia.

move?

LayoutAnimation

Los ítems que cambiaron de sitio (el FLIP por defecto, como el de animation; una función lo sustituye).

enter?

EnterAnimation

Los ítems que aparecieron. Por defecto: surgen con un fundido donde están.

leave?

LeaveAnimation

Los ítems que se fueron. Por defecto: una copia del ítem se desvanece donde estaba, encogiéndose un poco.

true, opciones, false (el ítem simplemente aparece) o una función que anima su entrada.

type EnterAnimation = | boolean | AnimationOptions | ((context: EnterAnimationContext) => Animation | Promise<unknown> | void)

Un ítem que apareció en una lista con animateChanges activado: añadido, o mostrado de nuevo (un filtro, un nodo de árbol expandido).

key

Key

Clave del ítem.

element

HTMLElement

El elemento del ítem, ya en su sitio.

Rect

Dónde apareció (rectángulo de layout).

options

Required<AnimationOptions>

Los tiempos que dan las opciones, con los valores por defecto ya puestos.

reducedMotion

boolean

true, opciones, false (el ítem simplemente desaparece) o una función que anima la salida de la copia que queda en su lugar: devuelve su Animation o una promesa, y la copia se elimina cuando termina (al instante si la función no devuelve nada).

type LeaveAnimation = | boolean | AnimationOptions | ((context: LeaveAnimationContext) => Animation | Promise<unknown> | void)

Un ítem que salió de una lista con animateChanges activado: quitado, u ocultado (un filtro, un nodo de árbol plegado).

key

Key

Clave del ítem.

element

HTMLElement

Una copia del elemento del ítem, mostrada donde estaba el ítem (el ítem en sí ya no está): con posición absoluta en su antiguo padre, ignorando el puntero, marcada con data-dnd-leaving. La biblioteca la elimina cuando termina tu animación.

from

Rect

Dónde estaba el ítem.

options

Required<AnimationOptions>

Los tiempos que dan las opciones, con los valores por defecto ya puestos.

reducedMotion

boolean