vue-dnd-kit

Documentation/API

useDnD et moniteurs

L'état du glissement et ses événements, n'importe où sous le provider — et le provider lui-même, transmis à une autre application Vue.

Modifier cette page

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

Live

Chargement de la démo…

<script setup lang="ts">
import { DnDProvider } from '@vue-dnd-kit/core';
import TokenScene from './TokenScene.vue';
import StateInspector from './StateInspector.vue';
</script>

<template>
  <DnDProvider>
    <div class="demo">
      <TokenScene />
      <StateInspector />
    </div>
  </DnDProvider>
</template>

<style scoped>
.demo {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  justify-content: center;
  gap: 16px;
}
</style>

useDnD

function useDnD(): DnDState;

L'état du glissement en lecture seule, pour une UI personnalisée (mise en évidence des cibles valides, indicateurs de chargement, progression).

const { status, active, over, selection, cancel } = useDnD();
const dragging = computed(() => status.value === 'dragging');

L'état réactif du glissement du provider. active et over sont vidés dès que le dépôt est décidé, pendant que l'overlay atterrit encore.

L'état du glissement prend fin quand le dépôt est décidé : active, over et pointer valent null (et les droppables cessent d'accepter) pendant que l'overlay s'anime encore jusqu'à sa place. Une UI dérivée ne mélange jamais l'ancien glissement avec les nouvelles données. Pendant qu'un onBeforeDrop asynchrone décide, l'état est conservé tel qu'il était au relâchement, mais la page est sortie du mode glissement : son propre curseur et la sélection de texte sont revenus (une boîte de dialogue de confirmation fonctionne normalement), et l'overlay attend là où il a été déposé.

status vaut 'dragging' pendant qu'un glissement est en cours, sinon 'dropping' pendant qu'un dépôt se décide ou qu'un overlay atterrit encore, sinon 'idle' (hors 'activating' et 'selecting'). Un nouveau glissement n'attend pas les atterrissages : il démarre aussitôt, et ils se terminent autour de lui.

status
Readonly<Ref<DnDStatus>>

Ce que fait le provider (voir DnDStatus).

active
Readonly<Ref<Active | null>>

Le glissement en cours ; null s'il n'y en a pas, et dès que son dépôt est décidé.

over
Readonly<Ref<Over | null>>

La cible de dépôt sous le glissement ; null au-dessus de rien.

pointer
Readonly<Ref<Coordinates | null>>

Le pointeur en coordonnées du viewport, après les modificateurs ; null sans glissement.

position
Readonly<Ref<Coordinates | null>>

Où se trouve le coin supérieur gauche de la boîte glissée dans over, en direct : DnDEvent.position à chaque déplacement. null au-dessus de rien. Un composant d'overlay le lit pour montrer où il atterrirait (une heure sur un calendrier).

activation
{ progress: Readonly<Ref<number>> }

progress : où en est un appui par rapport à sa condition d'activation, de 0 à 1, tant que status vaut 'activating' : par exemple un anneau qui se remplit pendant un appui long.

isAutoScrolling
Readonly<Ref<boolean>>

Le défilement automatique fait défiler un conteneur.

selection
DnDSelection

Les éléments déplaçables sélectionnés (voir DnDSelection).

cancel
() => void

Annule le glissement (il revient à sa place), ou l'activation en attente.

Sélection

Les éléments déplaçables sélectionnés, par id : glisser l'un d'eux les emporte tous (multi-drag). Conservée par id, une sélection survit aux démontages (listes virtuelles).

ids
ReadonlySet<Key>

Les ids sélectionnés, réactifs.

has
(id: Key) => boolean

Si id est sélectionné.

add
(...ids: Key[]) => void

Sélectionne ces ids.

delete
(...ids: Key[]) => void

Désélectionne ces ids.

toggle
(id: Key, force?: boolean) => void

Sélectionne id ou le désélectionne ; force: true le sélectionne, false le désélectionne.

set
(ids: Iterable<Key>) => void

Sélectionne ces ids et aucun autre.

clear
() => void

Désélectionne tous les ids.

useDnDMonitor

function useDnDMonitor(monitor: DnDMonitor): void;

S'abonne aux événements de chaque glissement sous le provider, tant que le composant appelant (ou l'effect scope) existe.

useDnDMonitor({
  onDragEnd: (e) => (e.dropped ? save(e) : undefined),
  onBeforeDrop: async (e) => ((await confirm()) ? 'accept' : 'reject'),
});

Vos moniteurs sont consultés sur un dépôt (onBeforeDrop) avant la cible. Les payloads sont décrits sur la page des événements.

Des hooks pour chaque glissement sous le provider (useDnDMonitor).

onDragStart?
(event: DnDEvent) => void

Un glissement a commencé, après son activation.

onDragMove?
(event: DnDEvent) => void

Le glissement a bougé (au plus une fois par image).

onDragOver?
(event: DnDEvent) => void

La cible sous le glissement a changé.

onBeforeDrop?
(event: DnDEvent) => MaybePromise<BeforeDropResult>

S'exécute avant que le dépôt ne soit validé (voir BeforeDropResult) : 'reject' le refuse, des ids en acceptent un sous-ensemble.

onDragEnd?
(event: DnDEndEvent) => void

Une notification une fois le dépôt terminé : les listes triables ont exécuté leur onDrop et l'ont écrit.

onDragCancel?
(event: DnDEvent) => void

Le glissement a été annulé, ou son dépôt refusé : les items reviennent à leur place.

onDragResume?
(event: DnDEvent) => void

onBeforeDrop a répondu 'continue' : il n'y a pas eu de dépôt, et le glissement continue.

onDragSettle?
(event: DnDEvent | DnDEndEvent) => void

L'overlay d'un glissement terminé a atterri : après son animation de dépôt (ou le retour en vol d'une annulation), avec l'événement qu'a reçu onDragEnd (un DnDEndEvent) ou onDragCancel. Le glissement suivant a pu démarrer entre-temps : les glissements n'attendent pas les atterrissages.

getKeyboardCoordinates?
(event: KeyboardEvent, context: KeyboardMoveContext) => MaybePromise<Coordinates | undefined>

Glissements au clavier : prochaine position du pointeur pour une flèche (par exemple le prochain emplacement triable).

Ce avec quoi getKeyboardCoordinates est appelé, pour une touche fléchée.

active
Active

Le glissement.

pointer
Coordinates

Où se trouve le glissement maintenant, en coordonnées du viewport.

direction
Coordinates

Vecteur unitaire de la flèche pressée.

useDnDContext et provideDnDContext

function useDnDContext(): DnDContext;

Le provider au-dessus de ce composant, sous forme de handle opaque pour provideDnDContext : il fait passer le provider dans des shadow roots et des applications Vue séparées.

function provideDnDContext(app: App, context: DnDContext): void;

Partage un provider (obtenu par useDnDContext()) avec une autre application Vue, par exemple une application montée dans un shadow root.

// In a component under the provider:
const context = useDnDContext();
// A second Vue app (a widget mounted in a shadow root) joins the same drag:
const widget = createApp(Widget);
provideDnDContext(widget, context);

Un provider tel que le renvoie useDnDContext(), à transmettre à provideDnDContext() : une autre application Vue (par exemple montée dans un shadow root) fonctionne alors avec le même provider. Opaque : il n'a aucun membre public, et ne change donc jamais avec les rouages internes de la bibliothèque.