Documentação/API

makeDraggable

Torna um elemento arrastável — arraste livre, ou para dentro dos alvos de drop que o aceitam.

Esta página foi traduzida por IA e pode conter imprecisões. Ler o original em inglês

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

Torna um elemento arrastável. Arraste livre por padrão; as listas ordenáveis são construídas sobre ele.

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

Veja Arrastar e soltar. Os itens ordenáveis também são draggables: makeSortableItem aceita as mesmas opções e outras mais.

Live Arraste cada card. Solte, e ele volta ao lugar

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

Opções

Opções de makeDraggable. Toda opção, exceto canDrag, aceita um valor, um ref ou um getter (overlay, dropAnimation: um valor ou um ref) e é lida quando é necessária, então uma mudança vale, no máximo, a partir do próximo arraste.

id?

Keyvalor · ref · getter

Id estável. Passe um getter em listas virtuais, onde os elementos são reciclados. Padrão: useId(), estável entre a renderização no servidor e no cliente, mas novo a cada instância do componente.

data?

TDatavalor · ref · getter

Qualquer coisa que o arraste deva carregar: os eventos e os alvos de drop a leem como active.data.

label?

stringvalor · ref · getter

Como as pessoas o chamam: os textos para leitores de tela dizem isso em vez do id (Picked up Tomato). Os eventos o trazem como active.label e em items.

type?

string | string[]valor · ref · getter

O tipo ou os tipos dele, comparados pelas regras accept dos alvos de drop. Sem nenhum, ele serve para qualquer alvo.

disabled?

booleanvalor · ref · getter

true: ele não pode ser arrastado (informa aria-disabled).

handle?

MaybeElement | stringvalor · ref · getter

Elemento ou seletor dentro do draggable que inicia o arraste (e recebe os atributos).

activation?

ActivationOptionsvalor · ref · getter

Sobrescreve a activation do provider. Lido quando um clique começa.

canDrag?

(event: PointerEvent | KeyboardEvent) => boolean

Barreira extra, por exemplo, arrastar só enquanto uma tecla está pressionada.

overlay?

boolean | Componentvalor · ref

true (padrão): um overlay segue o ponteiro, renderizado pelo slot #overlay do provider ou como um clone do elemento. Um componente: o overlay o renderiza com OverlayProps, antes do slot. false: sem overlay, o próprio elemento se move por meio do transform retornado. Um valor ou um ref (uma função é um componente funcional, então (props) => <Card {...props} /> funciona). Se há overlay ou não é decidido quando o arraste começa; um ref trocado durante o arraste troca o componente na hora (veja o overlayTransition do provider). O overOverlay de um alvo de drop prevalece enquanto o arraste está sobre ele. O clone deixa de fora os efeitos de clique de UI kits (ripples) e qualquer elemento interno marcado com data-dnd-no-clone.

dropAnimation?

DropAnimationvalor · ref

Como o overlay pousa quando um arraste deste elemento termina, em vez do dropAnimation do provider; o overDropAnimation de um alvo de drop prevalece. Um valor ou um ref (uma função é a animação), lido no drop.

modifiers?

Modifier[]valor · ref · getter

Modificadores para os arrastes que começam aqui, aplicados depois dos modifiers do provider: por exemplo, [restrictToVerticalAxis] para um elemento em uma página onde os outros arrastes se movem livremente. Lido quando o arraste começa.

axis?

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

Trava em um eixo os arrastes que começam aqui: 'x' move só na horizontal, 'y' só na vertical. A trava vem depois de modifiers (por último, como restrictToHorizontalAxis / restrictToVerticalAxis), então se mantém não importa o que eles façam. Lido quando o arraste começa.

keyboardMode?

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

Setas nos arrastes livres: mover em pixels (padrão) ou saltar entre os alvos de drop que aceitam o item. Lido a cada toque de seta.

attributes?

booleanvalor · ref · getter

Define os atributos role/tabindex/aria-* (padrão true), sem nunca sobrescrever os que o usuário definiu. O id das instruções do provider entra em um aria-describedby existente como mais um token (uma tooltip de UI kit no mesmo elemento mantém o seu), e só esse token é removido. Ao vivo: desligar remove o que a biblioteca definiu.

native?

boolean | NativeDragOptionsvalor · ref · getter

Um arraste dele com o mouse é o arraste do próprio navegador, que pode sair da página: para a área de trabalho, para outro app ou aba, para outra janela do app. Na página ele funciona como sempre (alvos, listas que abrem espaço), mas o navegador desenha a imagem arrastada em vez do overlay. Arrastes por toque e por teclado continuam sendo da biblioteca. true carrega o label como texto. Lido quando um clique começa. canDrag é consultado no clique; o navegador decide quanto o mouse se move antes de o arraste dele começar (activation não se aplica a ele).

Retorno

O que makeDraggable retorna.

ComputedRef<Key>

O id do draggable: a opção id, ou o que foi gerado para ele.

isDragging

ComputedRef<boolean>

Ele está sendo arrastado (também como outro item de um multi-drag), ou o overlay dele ainda está pousando.

transform

ComputedRef<Coordinates | null>

Deslocamento a aplicar quando overlay: false: o do arraste, menos o quanto o conteúdo em que o elemento está se moveu desde o início (a página ou um contêiner rolou), para que o elemento continue sob o ponteiro.

selected

WritableComputedRef<boolean>

Ele está na seleção do provider: um arraste de um item selecionado carrega todos. Atribua um valor para selecionar ou desmarcar.

Para fora da página

O que um arraste native leva para fora da página. Veja arquivos e outros apps.

Um draggable ou item ordenável que um mouse pode arrastar para fora da página (native): para a área de trabalho, para outro app, outra aba, outra janela do app.

data?

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

O que outros apps e páginas recebem: texto por tipo MIME, como { 'text/plain': title, 'text/uri-list': url }. Lido quando o arraste começa. Itens ordenáveis também carregam a si mesmos, para as listas do grupo deles em outra janela do app.

effect?

O que o arraste permite ao lugar onde é solto (effectAllowed). Padrão 'copyMove': uma movimentação tira os itens da lista deles aqui, uma cópia os mantém.