Documentation/API

Événements

Ce que transportent les événements de glissement — le glissement actif, la cible, le pointeur, la position de l'item — et ce que répond onBeforeDrop.

Modifier cette page

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

Les moniteurs (useDnDMonitor), les événements du provider et les hooks des droppables reçoivent un DnDEvent ; onDragEnd reçoit un DnDEndEvent. Les listes et les arbres triables passent leurs propres événements de dépôt (SortableDropEvent, SortableTreeDropEvent) à leurs onBeforeDrop et onDrop.

Live Faites glisser une tâche, puis choisissez un événement pour le lire

Chargement de la démo…

<script setup lang="ts">
import { ref } from 'vue';
import { DnDProvider } from '@vue-dnd-kit/core';
import { describe, type LoggedEvent } from './describe';
import TaskColumn from './TaskColumn.vue';
import EventInspector from './EventInspector.vue';

const todo = ref([
  { id: 'docs', title: 'Write docs' },
  { id: 'bug', title: 'Fix #42' },
]);
const done = ref([{ id: 'ship', title: 'Ship v3' }]);

// Every event of the drag, described when it fires. A new drag starts a new log;
// moves fire every frame, so they share one entry, which keeps the latest.
const events = ref<LoggedEvent[]>([]);
let count = 0;
const record = (name: string, type: string, payload: unknown) => {
  if (name === 'onDragStart') events.value = [];
  const lines = describe(type, payload);
  const move = name === 'onDragMove' && events.value.find((event) => event.name === name);
  if (move) Object.assign(move, { lines, count: move.count + 1 });
  else events.value.push({ id: ++count, name, type, lines, count: 1 });
};
</script>

<template>
  <DnDProvider>
    <div class="demo">
      <div class="columns">
        <TaskColumn id="todo" v-model="todo" :record="record" />
        <TaskColumn id="done" v-model="done" :record="record" />
      </div>
      <EventInspector :events="events" :record="record" />
    </div>
  </DnDProvider>
</template>

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

.columns {
  display: flex;
  flex-direction: column;
  gap: 10px;
  width: 168px;
}
</style>

DnDEvent

Ce que transportent les événements de glissement : les moniteurs, les événements du provider et les hooks des cibles de dépôt le reçoivent.

active

Active<T>

Le glissement.

over

Over | null

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

pointer

Coordinates

Pointeur en coordonnées du viewport, après les modificateurs.

delta

Coordinates

Décalage depuis le début du glissement, après les modificateurs.

position

Coordinates | null

Où se trouve le coin supérieur gauche de la boîte glissée dans over, depuis le bord de son padding et défilement compris : le left/top qui place un item positionné en absolu là où il a été déposé (une note sur un tableau). null au-dessus de rien. Celui de la boîte de l'overlay, ou de l'élément lui-même avec overlay: false.

mode

DragMode

Ce que ferait un dépôt : 'move', 'copy' (le pull: 'clone' d'une liste, ou la touche de copie maintenue au-dessus d'items dont la liste peut faire clone), 'swap' ou 'insert'. Une simple cible de dépôt le lit pour copier au lieu de déplacer.

source?

DragSource

Présent quand les items glissés viennent d'une liste triable.

external?

ExternalData

Un glissement venu de l'extérieur de la page : ce qu'il transporte (active.external). Ses données arrivent au dépôt.

DnDEndEvent

Ce que reçoit onDragEnd (et le onDrop de la cible) : l'événement du dépôt, et comment il s'est passé.

dropped

boolean

Faux quand le glissement s'est terminé hors de toute cible de dépôt.

accepted

Key[]

Ids acceptés par onBeforeDrop (tous les ids glissés, sauf si un sous-ensemble a été renvoyé).

rejected

Key[]

Les autres ids glissés : onBeforeDrop les a écartés, et ils reviennent à leur place. Vide quand il les a tous acceptés.

droppedOutside?

'move' | 'copy' | 'link'

Un glissement hors de la page (native) déposé ailleurs : ce que cet endroit en a fait. 'move' retire ici les items de leur liste triable ; 'copy' et 'link' les laissent.

Réponses d'onBeforeDrop

Ce que décide onBeforeDrop :

'accept' (ou true, ou rien) : le dépôt a lieu ;
'reject' (ou false) : pas de dépôt, les items reviennent à leur place ;
une liste d'ids : seuls ces items sont acceptés, les autres reviennent à leur place ;
'continue' : pas de dépôt, et le glissement continue. Avec un pointeur, l'item le suit de nouveau (sans bouton maintenu) et le relâchement suivant le dépose, un clic suffit ; au toucher, il est repris ; le clavier le déplace comme avant. Escape l'annule. Le dépôt consulte de nouveau onBeforeDrop.

type BeforeDropResult = boolean | void | Key[] | 'accept' | 'reject' | 'continue'

Voir Décider d'un dépôt.

Le glissement actif

Le glissement en cours : l'item depuis lequel il a commencé, et tous les items qu'il transporte.

Key

Id de l'item depuis lequel le glissement a commencé.

ids

Key[]

Tous les ids glissés, en commençant par l'id principal (multi-drag).

items

DragItem<T>[]

Tous les items glissés, le principal en premier.

data

unknown

Le data de l'item depuis lequel le glissement a commencé.

label?

string

Le label de l'item d'où le glissement est parti, le nom que les gens lui donnent.

type

string[]

Le type normalisé de l'item depuis lequel le glissement a commencé ; vide, il convient à toute cible de dépôt.

element

HTMLElement

Élément depuis lequel le glissement a commencé. Il peut être détaché du DOM (listes virtuelles, déplacements entre listes).

rect

Rect

Rectangle de mise en page d'element au début du glissement.

sensor

SensorType

Comment le glissement se déplace : 'pointer' suit des points, 'keyboard' avance d'item en item (SensorActivation.type).

external?

ExternalData

Un glissement venu de l'extérieur de la page (des fichiers, un lien, du texte, ou des items d'une autre fenêtre de l'application) : ce qu'il transporte. Ses items sont créés pour lui (element est un substitut).

native?

boolean

Le glissement propre au navigateur (native, ou un glissement venu de l'extérieur) : le navigateur dessine l'image glissée, et il n'y a pas d'overlay.

Un item glissé : celui depuis lequel le glissement a commencé, ou un autre d'un multi-drag.

Key

Id de son élément déplaçable (la clé d'un item triable).

item?

T

L'objet item, quand le glissement vient d'une liste triable.

data

unknown

Son option data.

label?

string

Son label, le nom que les gens lui donnent.

type

string[]

type normalisé de l'élément déplaçable ; vide signifie qu'il convient à n'importe quelle cible de dépôt.

La cible

La cible de dépôt sous le glissement.

Key

Id de la cible de dépôt.

data

unknown

L'option data de la cible.

label?

string

Le label de la cible, le nom que les gens lui donnent.

element

HTMLElement

L'élément de la cible.

rect

Rect

Le rectangle d'element, mesuré pendant le glissement.

accepted

boolean

Si la règle accept de la cible accepte les items glissés.

La source

D'où viennent les items glissés, quand il s'agit d'une liste triable.

list

Key

Liste triable d'où viennent les items glissés.

remove

() => void

Retire les items glissés de leur liste (zones de corbeille).

Ce que fait un dépôt : 'move', 'copy' (les items restent, des copies sont insérées), 'swap' (behavior: 'swap' : deux items échangent leurs places) ou 'insert' (un simple élément déplaçable entre dans une liste sous la forme de l'item créé par son createItem).

type DragMode = 'move' | 'copy' | 'swap' | 'insert'