Documentación/API
Sensores
Lo que convierte la entrada en arrastres — los sensores integrados de puntero y de teclado, y la API para escribir los tuyos.
Esta página la ha traducido una IA y puede contener imprecisiones. Leer el original en inglés
import { defineSensor, useSensor, pointerSensor, keyboardSensor } from '@vue-dnd-kit/core';
SensorRatón, táctil y lápiz mediante Pointer Events. En sensors por defecto.
SensorEspacio/Enter, flechas y Escape (reasignables con la opción keyboard del provider). En sensors por defecto; también cancela con Escape los arrastres de puntero y los personalizados, incluso con keyboard: false.
(sensor: Sensor) => SensorDefine un sensor (consulta Sensor): solo ayuda con los tipos y devuelve su argumento.
(sensor: Sensor) => voidEjecuta un sensor en el provider de arriba mientras viva el componente que lo llama (o el effect scope), junto a los sensors del provider. Su arrastre se cancela al desmontarse.
Un sensor solo dice «arrastra este ítem desde aquí», luego adónde se ha movido y que se ha soltado o se ha cancelado; el provider comprueba el resto (qué se puede arrastrar, la activación, un arrastre a la vez). Consulta Sensores y arrastres programáticos.
Abajo, un pequeño sensor propio (ejecutado con useSensor) arrastra las piezas del tablero desde
su minimapa, junto a los sensores del propio provider.
Cargando la demo…
<script setup lang="ts">
import { DnDProvider } from '@vue-dnd-kit/core';
import SensorDesk from './SensorDesk.vue';
</script>
<template>
<DnDProvider>
<SensorDesk />
</DnDProvider>
</template>Sensor
Entrada que inicia arrastres: puntero, teclado o la tuya propia (un mando, un joystick en pantalla, la voz, arrastres programados). setup se ejecuta una vez por provider, solo en el navegador, dentro de un effect scope que termina con el provider (o cuando el sensor sale de sensors, o se desmonta el componente que llamó a useSensor). Registra los listeners con useEventListener o devuelve una función de limpieza; un arrastre que siga en curso en ese momento se cancela.
Para envolver un sensor, ejecuta su setup con un contexto propio. Object.create(context, { activate: { value: … } }) conserva los getters vivos (status, drag, props): un spread los congelaría.
Lo que recibe un sensor del provider en el que se ejecuta.
Readonly<DnDProviderProps>Las props del provider (por ejemplo activation, keyboard). Léelas cuando las necesites: pueden cambiar.
DnDStatusEl estado de arrastre del provider, sea cual sea el sensor que lleve el arrastre.
SensorDrag | nullEl arrastre del provider, pendiente o en curso, sea cual sea el sensor que lo inició; null cuando no hay ninguno. Los sensores pueden dirigir los arrastres de otros: el sensor de teclado mueve y suelta cualquier arrastre con teclado, por ejemplo uno que agarró un botón «Move» (@vue-dnd-kit/actions).
(activation: SensorActivation) => SensorDrag | nullPide arrastrar un ítem. El provider comprueba que está en reposo (un arrastre a la vez, ninguno mientras aterriza un drop), que el destino es un elemento arrastrable suyo que no está desactivado, dónde cayó la entrada (consulta target) y el canDrag del elemento arrastrable; luego espera la restricción de activación e inicia el arrastre. Devuelve el arrastre (pendiente, o ya en curso cuando no hay nada que esperar), o null cuando no puede empezar ningún arrastre.
() => voidCancela el arrastre o la activación pendiente del provider, sea cual sea el sensor que lo lleve (Escape, una pestaña oculta).
Activación
Lo que pide un sensor cuando su entrada quiere arrastrar (SensorContext.activate()).
Element | KeyDónde cayó la entrada: un elemento dentro de un elemento arrastrable, o el id de un elemento arrastrable. Un elemento debe pertenecer a este provider; en los arrastres 'pointer' debe estar sobre el asa, si la hay, y no sobre un hijo interactivo (un botón, un input); en los arrastres 'keyboard' debe ser el destino del foco del elemento arrastrable (el asa, o si no el propio elemento arrastrable) y no un campo editable. Un id se salta estas comprobaciones: el arrastre empieza desde el ítem, estuviera donde estuviera la entrada.
SensorTypeCómo se mueve el arrastre. 'pointer' (por defecto): sigue los puntos que se pasan a move(), los destinos se buscan ahí con la prueba de colisión, los contenedores se desplazan automáticamente en sus bordes y la página muestra el cursor de agarrar. 'keyboard': se mueve de ítem en ítem con step() y place(), como hacen las flechas, los destinos se hacen visibles en lugar de usar el desplazamiento automático, y el foco vuelve al ítem cuando termina. Active.sensor indica cuál.
CoordinatesDónde empieza el arrastre, en coordenadas del viewport. Por defecto: el centro del elemento arrastrable.
PointerEvent | KeyboardEventEl evento de entrada. Se pasa al canDrag del elemento arrastrable: sin él (un mando, un arrastre programático), no se consulta canDrag. Un pointerType 'touch' convierte el arrastre en uno táctil (haptics).
PointerKind | ActivationConstraintLo que espera el arrastre antes de empezar (useDnD().status es 'activating' hasta entonces, con su progreso). Un tipo de puntero lee para él la opción activation del elemento arrastrable, luego la del provider y luego los valores por defecto (ratón 4 px, al instante sobre un asa; lápiz 4 px; táctil, una pulsación larga de 200 ms con 5 px de tolerancia). Una restricción se usa tal cual. Por defecto: ninguna, el arrastre empieza al instante.
(drag: SensorDrag) => voidEl arrastre empezó, tras su activación: por ejemplo, captura el puntero.
(drag: SensorDrag) => voidEl arrastre ha terminado: su activación se abortó, o se soltó o se canceló (por quien fuera).
(drag: SensorDrag) => voidEl drop que pidió el sensor no se produjo y el arrastre continúa (onBeforeDrop respondió 'continue'): move, drop y cancel vuelven a aplicarse. Un sensor de puntero deja que el ítem siga al puntero hasta la siguiente liberación.
Según el tipo de puntero. Por defecto: ratón { distance: 4 } (al instante sobre un asa), lápiz { distance: 4 }, táctil { delay: 200, tolerance: 5 }.
type ActivationOptions = Partial< Record<PointerKind, ActivationConstraint> >Lo que debe hacer una pulsación antes de convertirse en arrastre: recorrer distance o mantenerse durante delay, lo que ocurra primero. Sin nada configurado: el arrastre empieza al instante.
El arrastre
Un arrastre de un sensor, desde activate() hasta que termina. Cada llamada se ignora en cuanto deja de aplicar: movimientos antes del inicio o después del final, un segundo drop().
KeyId del ítem arrastrado.
SensorTypeCómo se mueve el arrastre, según lo pidió activate() (SensorActivation.type).
SensorDragStateEn qué punto está el arrastre: esperando su activación, arrastrando o terminado.
booleanEl arrastre empezó, aunque ya haya terminado (el sensor de puntero se traga el clic que lo sigue).
(point: Coordinates) => voidLa entrada se ha movido. Mientras está pendiente, se comprueba la restricción de activación (pasarse de su tolerancia la aborta); durante el arrastre, el arrastre va ahí. Los arrastres de puntero toman una posición por frame; los arrastres con teclado se mueven al instante, después de los pasos anteriores.
(direction: SensorDirection, options?: SensorStepOptions) => Promise<void>Arrastres con teclado: un paso de flecha, como hacen las flechas del sensor de teclado (el siguiente ítem de una lista, el siguiente destino que lo acepta en modo 'droppables', o keyboard.step píxeles). Los pasos se encolan: cada uno se ejecuta cuando el anterior se ha renderizado, y una tecla repetida (event.repeat) se omite mientras otro todavía se resuelve. Los arrastres de puntero lo ignoran.
(position: SortablePosition) => Promise<boolean>Coloca el ítem en una posición de una lista ordenable, como hacen los movimientos con teclado (otras listas solo lo toman si lo aceptan), y mueve el arrastre a su nuevo sitio. Se resuelve con false cuando ninguna lista lo acepta ahí. Se encola como step() en los arrastres con teclado.
() => Promise<boolean>Suelta; si la activación está pendiente, en cambio, la aborta. Se resuelve cuando el arrastre ha terminado y ha aterrizado: true cuando el drop se completó, false cuando se rechazó (un destino, onBeforeDrop) o no había nada que soltar.
() => voidCancela el arrastre (vuelve a su sitio), o aborta una activación pendiente.
'pending': esperando la restricción de activación;'dragging': desde el inicio hasta que se decide el drop o se cancela el arrastre;'ended': la activación se abortó, o el arrastre se soltó o se canceló, por el sensor o por cualquier otra cosa (Escape, una pestaña oculta,useDnD().cancel(), el desmontaje del provider).
type SensorDragState = 'pending' | 'dragging' | 'ended'Opciones de SensorDrag.step().
La flecha de un paso con teclado.
type SensorDirection = 'up' | 'down' | 'left' | 'right'Una posición en una lista ordenable, para SensorDrag.place() (y moveItem de @vue-dnd-kit/actions). Solo listas: los árboles colocan los ítems con sus propias claves.