Documentation/API

makeDraggable

Rend un élément déplaçable — glissement libre, ou vers les cibles de dépôt qui l'acceptent.

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

function makeDraggable<TData = unknown>(  target: MaybeElementRef,  options?: DraggableOptions<TData>,): DraggableReturn;

Rend un élément déplaçable. Glissement libre par défaut ; les listes triables s'appuient dessus.

const el = useTemplateRef<HTMLElement>('el');
const { isDragging } = makeDraggable(el, { id: 'card', type: 'card', data: { title } });

Voir Glisser-déposer. Les items triables sont aussi des éléments déplaçables : makeSortableItem accepte les mêmes options, et d'autres encore.

Live Faites glisser chaque carte. Relâchez-la, et elle revient à sa place

Chargement de la démo…

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

<template>
  <!-- No drop target here: let go, and each card goes back where it was. -->
  <DnDProvider>
    <div class="cards">
      <DragCard title="Grab it anywhere" code="makeDraggable(el)" />
      <DragCard title="Grab the handle" code="{ handle: grip }" handle />
      <DragCard title="It moves itself" code="{ overlay: false }" self />
      <DragCard title="Not now" code="{ disabled: true }" disabled />
    </div>
  </DnDProvider>
</template>

<style scoped>
.cards {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 220px));
  gap: 14px;
}

@media (max-width: 480px) {
  .cards {
    grid-template-columns: minmax(0, 1fr);
  }
}
</style>

Options

Options de makeDraggable. Chaque option sauf canDrag accepte une valeur, une ref ou un getter (overlay, dropAnimation : une valeur ou une ref) et est lue au moment où elle est nécessaire : un changement s'applique donc au plus tard au glissement suivant.

id?

Keyvaleur · ref · getter

Id stable. Passez un getter dans les listes virtuelles, où les éléments sont recyclés. Par défaut : useId(), stable entre le rendu serveur et le rendu client, mais nouveau pour chaque instance du composant.

data?

TDatavaleur · ref · getter

Tout ce que le glissement doit transporter : les événements et les cibles de dépôt le lisent dans active.data.

label?

stringvaleur · ref · getter

Le nom que les gens lui donnent : les textes pour les lecteurs d'écran le disent à la place de l'id (Picked up Tomato). Les événements le transportent dans active.label et dans items.

type?

string | string[]valeur · ref · getter

Son type ou ses types, comparés aux règles accept des cibles de dépôt. Sans type, il convient à toute cible.

disabled?

booleanvaleur · ref · getter

true : il ne peut pas être glissé (il indique aria-disabled).

handle?

MaybeElement | stringvaleur · ref · getter

Élément ou sélecteur, à l'intérieur de l'élément déplaçable, qui lance le glissement (et reçoit les attributs).

activation?

ActivationOptionsvaleur · ref · getter

Remplace l'activation du provider. Lue au début d'un appui.

canDrag?

(event: PointerEvent | KeyboardEvent) => boolean

Filtre supplémentaire, par exemple ne faire glisser que pendant qu'une touche est maintenue.

overlay?

boolean | Componentvaleur · ref

true (par défaut) : un overlay suit le pointeur, rendu par le slot #overlay du provider ou sous forme de clone de l'élément. Un composant : l'overlay le rend avec OverlayProps, avant le slot. false : pas d'overlay, l'élément lui-même bouge via le transform renvoyé. Une valeur ou une ref (une fonction est un composant fonctionnel, donc (props) => <Card {...props} /> fonctionne). La présence d'un overlay est décidée au début du glissement ; une ref changée en plein glissement remplace aussitôt le composant (voir l'overlayTransition du provider). L'overOverlay d'une cible de dépôt l'emporte tant que le glissement la survole. Le clone laisse de côté les effets d'appui des kits UI (ondulations) et tout élément intérieur marqué data-dnd-no-clone.

dropAnimation?

DropAnimationvaleur · ref

Comment l'overlay atterrit quand un glissement de cet élément se termine, à la place de la dropAnimation du provider ; l'overDropAnimation d'une cible de dépôt l'emporte. Une valeur ou une ref (une fonction est l'animation), lue au dépôt.

modifiers?

Modifier[]valeur · ref · getter

Modificateurs des glissements qui commencent ici, appliqués après les modifiers du provider : par exemple [restrictToVerticalAxis] pour un élément sur une page où les autres glissements sont libres. Lus au début du glissement.

axis?

'x' | 'y'valeur · ref · getter

Verrouille sur un axe les glissements qui commencent ici : 'x' ne déplace qu'horizontalement, 'y' que verticalement. Le verrouillage vient après modifiers (restrictToHorizontalAxis / restrictToVerticalAxis en dernier) : il tient donc quoi qu'ils fassent. Lu au début du glissement.

keyboardMode?

'pixels' | 'droppables'valeur · ref · getter

Les flèches dans les glissements libres : déplacer de quelques pixels (par défaut) ou sauter d'une cible de dépôt qui accepte l'élément à l'autre. Lu à chaque appui sur une flèche.

attributes?

booleanvaleur · ref · getter

Définit les attributs role/tabindex/aria-* (true par défaut), sans jamais écraser ceux de l'utilisateur. L'id des instructions du provider rejoint un aria-describedby existant comme un jeton de plus (l'infobulle d'un kit UI sur le même élément garde le sien), et seul ce jeton est retiré le cas échéant. Réactif : le désactiver retire ce que la bibliothèque avait défini.

native?

boolean | NativeDragOptionsvaleur · ref · getter

Un glissement à la souris est le glissement propre au navigateur, qui peut quitter la page : vers le bureau, une autre application ou un autre onglet, une autre fenêtre de l'application. Sur la page, il fonctionne comme d'habitude (cibles, listes qui font de la place), mais le navigateur dessine l'image glissée à la place de l'overlay. Les glissements au toucher et au clavier restent ceux de la bibliothèque. true transporte le label comme texte. Lue au début d'un appui. canDrag est consulté à l'appui ; le navigateur décide de la distance que la souris doit parcourir avant que son glissement commence (activation ne s'y applique pas).

Valeur de retour

Ce que renvoie makeDraggable.

ComputedRef<Key>

L'id de l'élément déplaçable : l'option id, ou celui créé pour lui.

isDragging

ComputedRef<boolean>

Il est en cours de glissement (y compris comme autre item d'un multi-drag), ou son overlay est encore en train d'atterrir.

transform

ComputedRef<Coordinates | null>

Décalage à appliquer quand overlay: false : celui du glissement, moins la distance dont le contenu où se trouve l'élément s'est déplacé depuis le début (la page ou un conteneur a défilé), pour que l'élément reste sous le pointeur.

selected

WritableComputedRef<boolean>

Il fait partie de la sélection du provider : glisser un item sélectionné les emporte tous. Modifiez-le pour sélectionner ou désélectionner.

Hors de la page

Ce que transporte un glissement native hors de la page. Voir fichiers et autres applications.

Un élément déplaçable ou un item triable qu'une souris peut faire glisser hors de la page (native) : vers le bureau, une autre application, un autre onglet, une autre fenêtre de l'application.

data?

(active: Active) => Record<string, string>

Ce que reçoivent les autres applications et pages : du texte par type MIME, sous la forme { 'text/plain': title, 'text/uri-list': url }. Lu au début du glissement. Les items triables se transportent aussi eux-mêmes, pour les listes de leur groupe dans une autre fenêtre de l'application.

effect?

Ce que le glissement permet à l'endroit où il est déposé (effectAllowed). Par défaut 'copyMove' : un déplacement retire ici les items de leur liste, une copie les laisse.