Documentación/API

makeDraggable

Hace que un elemento se pueda arrastrar — arrastre libre, o hacia los destinos de drop que lo aceptan.

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

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

Hace arrastrable un elemento. Arrastre libre por defecto; las listas ordenables se construyen sobre él.

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

Consulta Arrastrar y soltar. Los ítems ordenables también son elementos arrastrables: makeSortableItem acepta las mismas opciones y alguna más.

Live Arrastra cada tarjeta. Suéltala y volverá a su sitio

Cargando la demo…

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

Opciones

Opciones de makeDraggable. Todas las opciones salvo canDrag aceptan un valor, una ref o un getter (overlay, dropAnimation: un valor o una ref) y se leen cuando hacen falta, así que un cambio se aplica, como muy tarde, en el siguiente arrastre.

id?

Keyvalor · ref · getter

Id estable. Pasa un getter en las listas virtuales, donde los elementos se reciclan. Por defecto: useId(), estable entre el renderizado en el servidor y en el cliente, pero nuevo en cada instancia del componente.

data?

TDatavalor · ref · getter

Cualquier cosa que deba llevar el arrastre: los eventos y los destinos de drop lo leen como active.data.

label?

stringvalor · ref · getter

El nombre que le da la gente: los textos para lectores de pantalla lo dicen en lugar del id (Picked up Tomato). Los eventos lo llevan en active.label y en items.

type?

string | string[]valor · ref · getter

Su tipo o tipos, que se comparan con las reglas accept de los destinos de drop. Sin tipo encaja en cualquier destino.

disabled?

booleanvalor · ref · getter

true: no se puede arrastrar (indica aria-disabled).

handle?

MaybeElement | stringvalor · ref · getter

Elemento o selector dentro del elemento arrastrable que inicia el arrastre (y recibe los atributos).

activation?

ActivationOptionsvalor · ref · getter

Sustituye la activation del provider. Se lee cuando empieza una pulsación.

canDrag?

(event: PointerEvent | KeyboardEvent) => boolean

Filtro adicional, por ejemplo arrastrar solo mientras se mantiene una tecla.

overlay?

boolean | Componentvalor · ref

true (por defecto): un overlay sigue al puntero, renderizado por el slot #overlay del provider o como un clon del elemento. Un componente: el overlay lo renderiza con OverlayProps, antes que el slot. false: sin overlay, el propio elemento se mueve mediante el transform devuelto. Un valor o una ref (una función es un componente funcional, así que (props) => <Card {...props} /> funciona). Si hay overlay o no se decide cuando empieza el arrastre; una ref cambiada a mitad del arrastre cambia el componente al instante (consulta la overlayTransition del provider). El overOverlay de un destino de drop tiene prioridad mientras el arrastre está sobre él. El clon deja fuera los efectos de pulsación de los kits de UI (ripples) y cualquier elemento interior marcado con data-dnd-no-clone.

dropAnimation?

DropAnimationvalor · ref

Cómo aterriza el overlay cuando termina un arrastre de este elemento, en lugar de la dropAnimation del provider; la overDropAnimation de un destino de drop tiene prioridad. Un valor o una ref (una función es la animación), que se lee al soltar.

modifiers?

Modifier[]valor · ref · getter

Modificadores para los arrastres que empiezan aquí, aplicados después de los modifiers del provider: por ejemplo [restrictToVerticalAxis] para un elemento en una página donde los demás arrastres se mueven libremente. Se leen cuando empieza el arrastre.

axis?

'x' | 'y'valor · ref · getter

Bloquea en un eje los arrastres que empiezan aquí: 'x' solo mueve en horizontal, 'y' solo en vertical. El bloqueo va después de modifiers (restrictToHorizontalAxis / restrictToVerticalAxis al final), así que se mantiene hagan lo que hagan. Se lee cuando empieza el arrastre.

keyboardMode?

'pixels' | 'droppables'valor · ref · getter

Las flechas en los arrastres libres: mover por píxeles (por defecto) o saltar entre los destinos de drop que lo aceptan. Se lee en cada pulsación de flecha.

attributes?

booleanvalor · ref · getter

Pone los atributos role/tabindex/aria-* (true por defecto), sin sobrescribir nunca los del usuario. El id de las instrucciones del provider se añade a un aria-describedby existente como un token más (el tooltip de un kit de UI en el mismo elemento conserva el suyo), y solo se elimina ese token. En vivo: desactivarlo elimina lo que puso la biblioteca.

native?

boolean | NativeDragOptionsvalor · ref · getter

Un arrastre con el ratón es el arrastre propio del navegador, que puede salir de la página: al escritorio, a otra app o pestaña, a otra ventana de la app. En la página funciona como siempre (destinos, listas que hacen sitio), pero el navegador dibuja la imagen arrastrada en lugar del overlay. Los arrastres táctiles y con teclado siguen siendo de la biblioteca. true lleva el label como texto. Se lee cuando empieza una pulsación. canDrag se consulta al pulsar; el navegador decide cuánto debe moverse el ratón antes de que empiece su arrastre (activation no se le aplica).

Valor devuelto

Lo que devuelve makeDraggable.

ComputedRef<Key>

El id del elemento arrastrable: la opción id o el que se creó para él.

isDragging

ComputedRef<boolean>

Se está arrastrando (también como otro ítem de un multi-drag), o su overlay aún está aterrizando.

transform

ComputedRef<Coordinates | null>

Desplazamiento que hay que aplicar cuando overlay: false: el del arrastre, menos lo que se ha movido desde el inicio el contenido en el que está el elemento (se desplazó la página o un contenedor), para que el elemento siga bajo el puntero.

selected

WritableComputedRef<boolean>

Está en la selección del provider: arrastrar un ítem seleccionado los lleva todos. Asígnalo para seleccionarlo o deseleccionarlo.

Fuera de la página

Lo que lleva un arrastre native fuera de la página. Consulta archivos y otras apps.

Un elemento arrastrable o un ítem ordenable que un ratón puede arrastrar fuera de la página (native): al escritorio, a otra app, a otra pestaña, a otra ventana de la app.

data?

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

Lo que reciben otras apps y páginas: texto por tipo MIME, como { 'text/plain': title, 'text/uri-list': url }. Se lee cuando empieza el arrastre. Los ítems ordenables también se llevan a sí mismos, para las listas de su grupo en otra ventana de la app.

effect?

Lo que el arrastre permite hacer al sitio donde se suelta (effectAllowed). Por defecto 'copyMove': un movimiento saca aquí los ítems de su lista, una copia los deja.