Documentation/API

Animations

Les options et les hooks des animations — le tri, le dépôt, et les changements qui ne viennent pas d'un glissement.

Cette page a été traduite par IA et peut contenir des inexactitudes. Lire l'original en anglais

Les props animation (déplacements de mise en page pendant le tri), dropAnimation (l'atterrissage de l'overlay) et animateChanges (changements de données qui ne viennent pas d'un glissement) du provider acceptent false, des options, ou votre propre fonction — pour GSAP ou motion. Les listes et les arbres peuvent redéfinir animation et animateChanges ; les éléments déplaçables, les items et les listes peuvent apporter leur propre dropAnimation, et les cibles de dépôt une overDropAnimation. Voir Animations.

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

Chaque couloir ci-dessous est un provider à part entière, qui donne à animation, dropAnimation et animateChanges le même type de valeur (animateChanges accepte une fonction dans move).

Live Mélangez, ou faites glisser une ligne dans chaque couloir

Chargement de la démo…

<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>

Options

Le timing d'une animation. Ce qui est omis garde la valeur par défaut de cette animation.

duration?

number

En ms. Par défaut 200 pour les déplacements de mise en page, 250 pour le dépôt ; 0 désactive l'animation.

easing?

string

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

Tri

Comment les items rejoignent leur nouvelle place : true (timing par défaut), des options, false (ils sautent directement), ou une fonction qui anime un item de from à to et renvoie son Animation, une promesse qui se résout à la fin, ou rien.

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

Ce que reçoit une fonction d'animation de mise en page, pour un item qui rejoint sa nouvelle place.

key

Key

Clé de l'item.

element

HTMLElement

L'élément de l'item, déjà à sa nouvelle place.

from

Rect

Rectangle visuel avant le changement (là où une animation en cours affichait l'item).

Rect

Rectangle de mise en page après le changement.

options

Required<AnimationOptions>

Le timing que donnent les options, valeurs par défaut comprises.

reason

'drag' | 'change'

Ce qui a déplacé l'item : un glissement ('drag' : le tri, le dépôt, une annulation), ou un changement de vos données qui ne vient pas d'un glissement ('change', avec l'option animateChanges de la liste activée).

signal

AbortSignal

Interrompu quand la bibliothèque arrête l'animation : l'item bouge de nouveau avant la fin (l'animation suivante part de l'endroit où il est affiché), ou les animations sont désactivées. Une Animation renvoyée est annulée pour vous. Arrêtez ici tout le reste et annulez immédiatement les styles appliqués : la mise en page est mesurée juste après.

reducedMotion

boolean

prefers-reduced-motion: reduce est actif. Les animations propres à la bibliothèque ne s'exécutent alors pas ; les fonctions que vous fournissez s'exécutent toujours, et décident d'après cette valeur (sauter le mouvement, ou garder un fondu).

Le dépôt

Comment l'overlay atterrit lors d'un dépôt et revient à sa place lors d'une annulation : true (timing par défaut), des options, false (pas de vol : il s'arrête là où il a été relâché), ou une fonction qui anime overlay de from à to et renvoie son Animation, une promesse qui se résout à la fin, ou rien.

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

Ce que reçoit une fonction d'animation de dépôt : l'overlay, où il se trouve et où il atterrit.

overlay

HTMLElement

La boîte de l'overlay ; elle atterrit sur l'emplacement de l'item actif. En multi-drag, les clones des autres items qu'elle transporte (ceux de l'overlay par défaut, les DragPreview d'un overlay personnalisé) atterrissent d'eux-mêmes sur leurs propres emplacements (avec le timing par défaut quand il s'agit d'une fonction personnalisée).

from

Rect

Là où se trouve l'overlay quand le glissement se termine.

Rect | null

Rectangle final de l'item déposé ; null quand il n'est pas rendu ou pas visible (l'overlay disparaît alors en fondu).

into

Rect | null

L'item n'est pas affiché après un dépôt sur une zone (pas une liste triable), par exemple s'il a été déposé dans un autre item (un dossier) ou dans une zone de corbeille : le rectangle visible de la zone. L'animation par défaut y réduit l'overlay pendant qu'il disparaît en fondu, au lieu d'un fondu sur place.

reason

'drop' | 'cancel'

'drop' : l'overlay atterrit là où le dépôt a placé l'item. 'cancel' : il revient là où était l'item.

active

Active

Le glissement qui s'est terminé.

over

Over | null

La cible sur laquelle le dépôt atterrit (une liste, une zone) ; null en cas d'annulation.

options

Required<AnimationOptions>

Le timing que donnent les options, valeurs par défaut comprises.

reducedMotion

boolean

Changements de données

Anime les changements des items d'une liste (ou d'un arbre) qui ne viennent pas d'un glissement : items ajoutés, retirés, déplacés (un tri, un mélange, un déplacement entre les listes d'un même groupe) ou filtrés. Désactivé par défaut (false) ; true anime les déplacements, les entrées et les sorties d'items avec le timing par défaut. Les glissements gardent leurs propres animations (animation, dropAnimation). Avec prefers-reduced-motion: reduce, les animations par défaut ne s'exécutent pas ; les fonctions que vous fournissez s'exécutent toujours (avec reducedMotion: true). Seuls les items proches de la zone visible sont animés (les lignes non montées d'une liste virtuelle sont ignorées).

type AutoAnimation = boolean | AutoAnimationOptions

animateChanges avec ses parties : duration et easing pour toutes, et, pour chaque type de changement, true, des options (par-dessus les options communes), false, ou votre propre fonction.

move?

LayoutAnimation

Les items qui ont changé de place (le FLIP par défaut, comme celui d'animation ; une fonction le remplace).

enter?

EnterAnimation

Les items apparus. Par défaut : ils s'affichent en fondu là où ils sont.

leave?

LeaveAnimation

Les items partis. Par défaut : une copie de l'item disparaît en fondu là où il était, en rétrécissant un peu.

true, des options, false (l'item apparaît simplement), ou une fonction qui anime son entrée.

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

Un item apparu dans une liste dont animateChanges est activé : ajouté, ou de nouveau affiché (un filtre, un nœud d'arbre déplié).

key

Key

Clé de l'item.

element

HTMLElement

L'élément de l'item, déjà à sa place.

Rect

Là où il est apparu (rectangle de mise en page).

options

Required<AnimationOptions>

Le timing que donnent les options, valeurs par défaut comprises.

reducedMotion

boolean

true, des options, false (l'item disparaît simplement), ou une fonction qui anime la sortie de la copie laissée à sa place : renvoyez son Animation ou une promesse, et la copie est retirée à la fin (immédiatement quand la fonction ne renvoie rien).

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

Un item qui a quitté une liste dont animateChanges est activé : retiré, ou masqué (un filtre, un nœud d'arbre replié).

key

Key

Clé de l'item.

element

HTMLElement

Une copie de l'élément de l'item, affichée là où était l'item (l'item lui-même a disparu) : positionnée en absolu dans son ancien parent, ignorant le pointeur, marquée data-dnd-leaving. La bibliothèque la retire quand votre animation se termine.

from

Rect

Là où était l'item.

options

Required<AnimationOptions>

Le timing que donnent les options, valeurs par défaut comprises.

reducedMotion

boolean