vue-dnd-kit

Documentación/API

useDnD y monitores

El estado del arrastre y sus eventos, en cualquier lugar bajo el provider — y el propio provider, pasado a otra app de Vue.

Editar esta página

Esta página la ha traducido una IA y puede contener imprecisiones. Leer el original en inglés

Live

Cargando la demo…

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

Estado del arrastre de solo lectura para UI propia (resaltar destinos válidos, spinners, progreso).

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

El estado del arrastre del provider, reactivo. active y over se vacían en cuanto se decide el drop, mientras el overlay todavía aterriza.

El estado del arrastre termina cuando se decide el drop: active, over y pointer pasan a valer null (y los droppables dejan de aceptar) mientras el overlay todavía se anima hasta su sitio. La UI derivada nunca mezcla el arrastre anterior con los datos nuevos. Mientras decide un onBeforeDrop asíncrono, el estado se conserva como estaba al soltar, pero la página sale del modo de arrastre: vuelven su propio cursor y la selección de texto (un diálogo de confirmación funciona con normalidad), y el overlay espera donde se soltó.

status vale 'dragging' mientras hay un arrastre en curso; si no, 'dropping' mientras se decide un drop o un overlay todavía aterriza; si no, 'idle' (aparte de 'activating' y 'selecting'). Un arrastre nuevo no espera a los aterrizajes: empieza enseguida, y ellos terminan a su alrededor.

status
Readonly<Ref<DnDStatus>>

Lo que está haciendo el provider (consulta DnDStatus).

active
Readonly<Ref<Active | null>>

El arrastre en curso; null si no hay ninguno, y en cuanto se decide su drop.

over
Readonly<Ref<Over | null>>

El destino de drop bajo el arrastre; null si no está sobre nada.

pointer
Readonly<Ref<Coordinates | null>>

El puntero en coordenadas del viewport, después de los modificadores; null sin arrastre.

position
Readonly<Ref<Coordinates | null>>

Dónde está la esquina superior izquierda de la caja arrastrada dentro de over, en vivo: DnDEvent.position en cada movimiento. null si no hay nada debajo. Un componente de overlay lo lee para mostrar dónde aterrizaría (una hora en un calendario).

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

progress: cuánto ha avanzado una pulsación hacia su condición de activación, de 0 a 1, mientras status es 'activating': p. ej., un anillo que se llena durante una pulsación larga.

isAutoScrolling
Readonly<Ref<boolean>>

El desplazamiento automático está moviendo un contenedor.

selection
DnDSelection

Los elementos arrastrables seleccionados (consulta DnDSelection).

cancel
() => void

Cancela el arrastre (vuelve a su sitio) o la activación pendiente.

Selección

Los elementos arrastrables seleccionados, por id: arrastrar uno de ellos los lleva todos (multi-drag). Guardada por id, una selección sobrevive a los desmontajes (listas virtuales).

ids
ReadonlySet<Key>

Los ids seleccionados, reactivos.

has
(id: Key) => boolean

Si id está seleccionado.

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

Selecciona estos ids.

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

Deselecciona estos ids.

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

Selecciona id o lo deselecciona; force: true lo selecciona, false lo deselecciona.

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

Selecciona estos ids y ningún otro.

clear
() => void

Deselecciona todos los ids.

useDnDMonitor

function useDnDMonitor(monitor: DnDMonitor): void;

Se suscribe a los eventos de cada arrastre bajo el provider, mientras viva el componente que lo llama (o el effect scope).

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

A tus monitores se les consulta sobre un drop (onBeforeDrop) antes que al destino. Los payloads están en la página de eventos.

Hooks para cada arrastre bajo el provider (useDnDMonitor).

onDragStart?
(event: DnDEvent) => void

Empezó un arrastre, después de su activación.

onDragMove?
(event: DnDEvent) => void

El arrastre se movió (como mucho una vez por fotograma).

onDragOver?
(event: DnDEvent) => void

Cambió el destino bajo el arrastre.

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

Se ejecuta antes de confirmar el drop (consulta BeforeDropResult): 'reject' lo rechaza, unos ids aceptan un subconjunto.

onDragEnd?
(event: DnDEndEvent) => void

Una notificación una vez terminado el drop: las listas ordenables ya han ejecutado su onDrop y lo han escrito.

onDragCancel?
(event: DnDEvent) => void

El arrastre se canceló o su drop se rechazó: los ítems vuelven a su sitio.

onDragResume?
(event: DnDEvent) => void

onBeforeDrop respondió 'continue': no hubo drop y el arrastre continúa.

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

El overlay de un arrastre terminado ha aterrizado: tras su animación al soltar (o la vuelta a su sitio de una cancelación), con el evento que recibió onDragEnd (un DnDEndEvent) u onDragCancel. Mientras tanto puede haber empezado el siguiente arrastre: los arrastres no esperan a los aterrizajes.

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

Arrastres con teclado: la siguiente posición del puntero para una flecha (por ejemplo, el siguiente hueco ordenable).

Con qué se llama a getKeyboardCoordinates para una tecla de flecha.

active
Active

El arrastre.

pointer
Coordinates

Dónde está ahora el arrastre, en coordenadas del viewport.

direction
Coordinates

Vector unitario de la flecha pulsada.

useDnDContext y provideDnDContext

function useDnDContext(): DnDContext;

El provider por encima de este componente, como un handle opaco para provideDnDContext: lleva el provider a shadow roots y a apps de Vue separadas.

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

Comparte un provider (de useDnDContext()) con otra app de Vue, p. ej., una montada dentro de 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 tal como lo devuelve useDnDContext(), para pasarlo a provideDnDContext(): otra app de Vue (por ejemplo, una montada en un shadow root) funciona entonces con el mismo provider. Opaco: no tiene miembros públicos, así que nunca cambia con los detalles internos de la biblioteca.