Documentation/API
Capteurs
Ce qui transforme les entrées en glissements — les capteurs pointeur et clavier intégrés, et l'API pour écrire les vôtres.
Cette page a été traduite par IA et peut contenir des inexactitudes. Lire l'original en anglais
import { defineSensor, useSensor, pointerSensor, keyboardSensor } from '@vue-dnd-kit/core';
SensorSouris, tactile et stylet via les Pointer Events. Présent dans sensors par défaut.
SensorEspace/Entrée, flèches et Échap (réassignables avec l'option keyboard du provider). Présent dans sensors par défaut ; il annule aussi avec Échap les glissements au pointeur et personnalisés, même avec keyboard: false.
(sensor: Sensor) => SensorDéfinit un capteur (voir Sensor) : il aide seulement pour les types et renvoie son argument.
(sensor: Sensor) => voidExécute un capteur dans le provider au-dessus, tant que le composant appelant (ou l'effect scope) existe, à côté des sensors du provider. Son glissement est annulé au démontage.
Un capteur dit seulement « fais glisser cet item depuis ici », puis où il s'est déplacé et qu'il a déposé ou a été annulé ; le provider vérifie le reste (ce qui peut être glissé, l'activation, un glissement à la fois). Voir Capteurs et glissements programmatiques.
Ci-dessous, un petit capteur personnalisé (lancé avec useSensor) fait glisser les pièces du
plateau depuis sa mini-carte, à côté des capteurs propres au provider.
Chargement de la démo…
<script setup lang="ts">
import { DnDProvider } from '@vue-dnd-kit/core';
import SensorDesk from './SensorDesk.vue';
</script>
<template>
<DnDProvider>
<SensorDesk />
</DnDProvider>
</template>Capteur
Une entrée qui lance des glissements : pointeur, clavier, ou la vôtre (une manette, un joystick à l'écran, la voix, des glissements scriptés). setup s'exécute une fois par provider, dans le navigateur uniquement, à l'intérieur d'un effect scope qui se termine avec le provider (ou quand le capteur sort de sensors, ou que le composant qui a appelé useSensor est démonté). Enregistrez les écouteurs avec useEventListener ou renvoyez une fonction de nettoyage ; un glissement encore en cours à ce moment-là est annulé.
Pour envelopper un capteur, exécutez son setup avec votre propre contexte. Object.create(context, { activate: { value: … } }) conserve les getters dynamiques (status, drag, props) : une décomposition les figerait.
Ce qu'un capteur reçoit du provider dans lequel il tourne.
Readonly<DnDProviderProps>Les props du provider (par exemple activation, keyboard). Lisez-les au moment où vous en avez besoin : elles peuvent changer.
DnDStatusLe statut de glissement du provider, quel que soit le capteur qui mène le glissement.
SensorDrag | nullLe glissement du provider, en attente ou en cours, quel que soit le capteur qui l'a lancé ; null quand il n'y en a pas. Les capteurs peuvent piloter les glissements les uns des autres : le capteur clavier déplace et dépose chaque glissement au clavier, par exemple celui qu'a lancé un bouton « Move » (@vue-dnd-kit/actions).
(activation: SensorActivation) => SensorDrag | nullDemande à faire glisser un item. Le provider vérifie qu'il est au repos (un glissement à la fois, aucun pendant l'atterrissage d'un dépôt), que la cible est l'un de ses éléments déplaçables et qu'elle n'est pas désactivée, où l'entrée est arrivée (voir target) et le canDrag de l'élément déplaçable, puis attend la contrainte d'activation et lance le glissement. Renvoie le glissement (en attente, ou déjà en cours quand il n'y a rien à attendre), ou null quand aucun glissement ne peut commencer.
() => voidAnnule le glissement ou l'activation en attente du provider, quel que soit le capteur qui le mène (Escape, un onglet masqué).
Activation
Ce que demande un capteur quand son entrée veut lancer un glissement (SensorContext.activate()).
Element | KeyL'endroit où l'entrée est arrivée : un élément à l'intérieur d'un élément déplaçable, ou l'id d'un élément déplaçable. Un élément doit appartenir à ce provider ; pour les glissements 'pointer', il doit se trouver sur la poignée s'il y en a une et pas sur un enfant interactif (un bouton, un champ) ; pour les glissements 'keyboard', il doit être la cible du focus de l'élément déplaçable (la poignée, sinon l'élément déplaçable lui-même) et pas un champ éditable. Un id saute ces vérifications : le glissement part de l'item, où que se trouvait l'entrée.
SensorTypeComment le glissement se déplace. 'pointer' (par défaut) : il suit les points passés à move(), les collisions avec les cibles y sont testées, les conteneurs défilent automatiquement à leurs bords et la page affiche le curseur de saisie. 'keyboard' : il se déplace d'item en item avec step() et place(), comme le font les flèches, les cibles sont rendues visibles au lieu du défilement automatique, et le focus revient sur l'item à la fin. Active.sensor indique lequel.
CoordinatesOù commence le glissement, en coordonnées du viewport. Par défaut : le centre de l'élément déplaçable.
PointerEvent | KeyboardEventL'événement d'entrée. Il est transmis au canDrag de l'élément déplaçable : sans événement (une manette, un glissement programmatique), canDrag n'est pas consulté. Un pointerType valant 'touch' fait du glissement un glissement tactile (haptics).
PointerKind | ActivationConstraintCe que le glissement attend avant de commencer (useDnD().status vaut 'activating' jusque-là, avec sa progression). Un type de pointeur lit pour lui l'option activation de l'élément déplaçable, puis celle du provider, puis les valeurs par défaut (souris 4 px, immédiat sur une poignée ; stylet 4 px ; toucher : un appui long de 200 ms avec une tolérance de 5 px). Une contrainte est utilisée telle quelle. Par défaut : aucune, le glissement commence immédiatement.
(drag: SensorDrag) => voidLe glissement a commencé, après son activation : par exemple, capturez le pointeur.
(drag: SensorDrag) => voidLe glissement est terminé : son activation a été interrompue, ou il a été déposé ou annulé (par qui que ce soit).
(drag: SensorDrag) => voidLe dépôt demandé par le capteur n'a pas eu lieu et le glissement continue (onBeforeDrop a répondu 'continue') : move, drop et cancel s'appliquent de nouveau. Un capteur de pointeur laisse l'item suivre le pointeur jusqu'au relâchement suivant.
Par type de pointeur. Par défaut : souris { distance: 4 } (immédiat sur une poignée), stylet { distance: 4 }, toucher { delay: 200, tolerance: 5 }.
type ActivationOptions = Partial< Record<PointerKind, ActivationConstraint> >Ce qu'un appui doit faire avant de devenir un glissement : parcourir distance, ou être maintenu pendant delay, selon ce qui arrive en premier. Rien de défini : le glissement commence tout de suite.
numberPixels que le pointeur doit parcourir avant que le glissement ne commence.
numberMillisecondes pendant lesquelles le pointeur doit être maintenu avant que le glissement ne commence.
numberAvec delay : le mouvement en px qui interrompt l'activation, pour que la page puisse défiler.
Le glissement
Un glissement d'un capteur, de activate() jusqu'à sa fin. Chaque appel est ignoré dès qu'il ne s'applique plus : déplacements avant le début ou après la fin, second drop().
KeyId de l'item glissé.
SensorTypeComment le glissement se déplace, tel que activate() l'a demandé (SensorActivation.type).
SensorDragStateOù en est le glissement : en attente de son activation, en cours, ou terminé.
booleanLe glissement a commencé, même s'il s'est terminé depuis (le capteur de pointeur avale le clic qui le suit).
(point: Coordinates) => voidL'entrée s'est déplacée. En attente, la contrainte d'activation est vérifiée (dépasser sa tolérance l'interrompt) ; pendant le glissement, le glissement va à cet endroit. Les glissements au pointeur prennent une position par frame ; les glissements au clavier se déplacent immédiatement, après les pas qui les précèdent.
(direction: SensorDirection, options?: SensorStepOptions) => Promise<void>Glissements au clavier : un pas de flèche, comme le font les flèches du capteur clavier (l'item suivant d'une liste, la cible suivante qui accepte l'item en mode 'droppables', ou keyboard.step pixels). Les pas sont mis en file d'attente : chacun s'exécute une fois le précédent rendu, et une touche répétée (event.repeat) est ignorée tant qu'un pas est encore en cours. Les glissements au pointeur l'ignorent.
(position: SortablePosition) => Promise<boolean>Place l'item à une position d'une liste triable, comme le font les déplacements au clavier (les autres listes ne le prennent que si elles l'acceptent), et déplace le glissement à sa nouvelle place. Se résout à false quand aucune liste ne l'accepte à cet endroit. Mis en file d'attente comme step() dans les glissements au clavier.
() => Promise<boolean>Dépose ; une activation en attente est interrompue à la place. Se résout une fois que le glissement s'est terminé et a atterri : true quand le dépôt a abouti, false quand il a été refusé (une cible, onBeforeDrop) ou qu'il n'y avait rien à déposer.
() => voidAnnule le glissement (il revient à sa place), ou interrompt une activation en attente.
'pending': en attente de la contrainte d'activation ;'dragging': depuis le début jusqu'à ce que le dépôt soit décidé ou que le glissement soit annulé ;'ended': l'activation a été interrompue, ou le glissement a été déposé ou annulé, par le capteur ou par autre chose (Escape, un onglet masqué,useDnD().cancel(), le démontage du provider).
type SensorDragState = 'pending' | 'dragging' | 'ended'Options de SensorDrag.step().
La flèche d'un pas au clavier.
type SensorDirection = 'up' | 'down' | 'left' | 'right'Une position dans une liste triable, pour SensorDrag.place() (et moveItem de @vue-dnd-kit/actions). Listes uniquement : les arbres placent les items selon leurs propres clés.