Documentação/API

useDnD e monitores

O estado do arraste e seus eventos, em qualquer lugar sob o provider — e o próprio provider, entregue a outro app Vue.

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

Live Selecione fichas, segure a ficha c, arraste sobre o painel travado

Carregando a 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 do arraste, somente leitura, para UI personalizada (destaque de alvos válidos, spinners, progresso).

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

O estado do arraste do provider, reativo. active e over são limpos assim que o drop é decidido, enquanto o overlay ainda pousa.

O estado do arraste termina quando o drop é decidido: active, over e pointer passam a ser null (e os droppables deixam de aceitar) enquanto o overlay ainda está sendo animado até o lugar. Uma UI derivada nunca mistura o arraste antigo com os dados novos. Enquanto um onBeforeDrop assíncrono decide, o estado é mantido como estava no momento em que o item foi solto, mas a página sai do modo de arraste: o cursor e a seleção de texto dela voltam (um diálogo de confirmação funciona normalmente), e o overlay espera onde foi solto.

status é 'dragging' enquanto um arraste está em andamento; senão, 'dropping' enquanto um drop é decidido ou um overlay ainda pousa; senão, 'idle' (deixando de lado 'activating' e 'selecting'). Um novo arraste não espera os pousos: ele começa na hora, e eles terminam ao redor dele.

status

Readonly<Ref<DnDStatus>>

O que o provider está fazendo (veja DnDStatus).

active

Readonly<Ref<Active | null>>

O arraste em andamento; null sem nenhum, e assim que o drop dele é decidido.

over

Readonly<Ref<Over | null>>

O alvo de drop sob o arraste; null sobre nada.

pointer

Readonly<Ref<Coordinates | null>>

Ponteiro em coordenadas da viewport, depois dos modificadores; null sem arraste.

position

Readonly<Ref<Coordinates | null>>

Onde está o canto superior esquerdo da caixa arrastada dentro de over, ao vivo: o DnDEvent.position de cada movimento. null sobre nada. Um componente de overlay o lê para mostrar onde pousaria (um horário em um calendário).

activation

{ progress: Readonly<Ref<number>> }

progress: o quanto um pressionamento já avançou rumo à sua restrição de ativação, de 0 a 1, enquanto status é 'activating': por exemplo, um anel que se enche durante um toque longo.

isAutoScrolling

Readonly<Ref<boolean>>

A rolagem automática está movendo um contêiner.

selection

DnDSelection

Os draggables selecionados (veja DnDSelection).

cancel

() => void

Cancela o arraste (ele volta ao lugar), ou a ativação pendente.

Seleção

Os draggables selecionados, por id: um arraste de um deles carrega todos (multi-drag). Guardada por id, uma seleção sobrevive a desmontagens (listas virtuais).

ids

ReadonlySet<Key>

Os ids selecionados, reativos.

has

(id: Key) => boolean

Se id está selecionado.

add

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

Seleciona esses ids.

delete

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

Desmarca esses ids.

toggle

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

Seleciona id ou o desmarca; force: true o seleciona, false o desmarca.

set

(ids: Iterable<Key>) => void

Seleciona esses ids e nenhum outro.

clear

() => void

Desmarca todos os ids.

useDnDMonitor

function useDnDMonitor(monitor: DnDMonitor): void;

Assina os eventos de todo arraste sob o provider, enquanto o componente que a chama (ou o effect scope) existir.

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

Os seus monitores são consultados sobre um drop (onBeforeDrop) antes do alvo. Os payloads estão na página de eventos.

Hooks para todo arraste sob o provider (useDnDMonitor).

onDragStart?

(event: DnDEvent) => void

Um arraste começou, depois da sua ativação.

onDragMove?

(event: DnDEvent) => void

O arraste se moveu (no máximo uma vez por frame).

onDragOver?

(event: DnDEvent) => void

O alvo sob o arraste mudou.

onBeforeDrop?

(event: DnDEvent) => MaybePromise<BeforeDropResult>

Roda antes de o drop ser efetivado (veja BeforeDropResult): 'reject' o recusa, ids aceitam um subconjunto.

onDragEnd?

(event: DnDEndEvent) => void

Uma notificação assim que o drop termina: as listas ordenáveis já rodaram o onDrop delas e o gravaram.

onDragCancel?

(event: DnDEvent) => void

O arraste foi cancelado, ou o seu drop foi recusado: os itens voltam ao lugar.

onDragResume?

(event: DnDEvent) => void

onBeforeDrop respondeu 'continue': não houve drop, e o arraste continua.

onDragSettle?

(event: DnDEvent | DnDEndEvent) => void

O overlay de um arraste encerrado pousou: depois da sua animação de drop (ou do voo de volta de um cancelamento), com o evento que onDragEnd (um DnDEndEvent) ou onDragCancel recebeu. O próximo arraste pode ter começado nesse meio-tempo: os arrastes não esperam os pousos.

getKeyboardCoordinates?

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

Arrastes por teclado: a próxima posição do ponteiro para uma seta (por exemplo, a próxima posição ordenável).

Com o que getKeyboardCoordinates é chamado, para uma tecla de seta.

active

Active

O arraste.

pointer

Coordinates

Onde o arraste está agora, em coordenadas da viewport.

direction

Coordinates

Vetor unitário da seta pressionada.

useDnDContext e provideDnDContext

function useDnDContext(): DnDContext;

O provider acima deste componente, como um handle opaco para provideDnDContext: ele leva o provider para dentro de shadow roots e de apps Vue separados.

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

Compartilha um provider (de useDnDContext()) com outro app Vue, por exemplo, um montado dentro de um 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);

Um provider como useDnDContext() o retorna, para entregar a provideDnDContext(): outro app Vue (por exemplo, um montado em uma shadow root) passa então a funcionar com o mesmo provider. Opaco: não tem membros públicos, então nunca muda com os detalhes internos da biblioteca.