vue-dnd-kit

Documentação/API

Sensores

O que transforma entrada em arrastes — os sensores embutidos de ponteiro e de teclado, e a API para escrever os seus.

Editar esta página

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

import { defineSensor, useSensor, pointerSensor, keyboardSensor } from '@vue-dnd-kit/core';
pointerSensor
Sensor

Mouse, toque e caneta via Pointer Events. Em sensors por padrão.

keyboardSensor
Sensor

Espaço/Enter, setas e Escape (reconfiguráveis com a opção keyboard do provider). Em sensors por padrão; ele também cancela arrastes por ponteiro e personalizados com Escape, mesmo com keyboard: false.

defineSensor
(sensor: Sensor) => Sensor

Define um sensor (veja Sensor): só ajuda com os tipos e retorna o seu argumento.

useSensor
(sensor: Sensor) => void

Executa um sensor no provider acima enquanto o componente que o chama (ou o effect scope) existir, ao lado dos sensors do provider. O arraste dele é cancelado quando ele é desmontado.

Um sensor só diz "arraste este item a partir daqui", depois para onde ele se moveu e que ele soltou ou foi cancelado; o provider verifica o resto (o que pode ser arrastado, a ativação, um arraste por vez). Veja Sensores e arrastes programáticos.

Abaixo, um pequeno sensor personalizado (executado com useSensor) arrasta as peças do tabuleiro a partir do minimapa, ao lado dos sensores do próprio provider.

Live

Carregando a 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 arrastes: ponteiro, teclado, ou uma sua (um gamepad, um joystick na tela, voz, arrastes roteirizados). setup roda uma vez por provider, só no navegador, dentro de um effect scope que termina com o provider (ou quando o sensor sai de sensors, ou quando o componente que chamou useSensor é desmontado). Registre os listeners com useEventListener ou retorne uma função de limpeza; um arraste que ainda esteja em andamento nesse momento é cancelado.

Para envolver um sensor, rode o setup dele com um contexto seu. Object.create(context, { activate: { value: … } }) mantém os getters ao vivo (status, drag, props): um spread os congelaria.

name?
string

Para depuração.

setup
(context: SensorContext) => void | (() => void)

Começa a escutar a entrada, uma vez por provider: chame context.activate() quando ele quiser arrastar. Pode retornar uma função de limpeza, executada quando o sensor para.

O que um sensor recebe do provider em que roda.

props
Readonly<DnDProviderProps>

As props do provider (por exemplo, activation, keyboard). Leia-as quando precisar: elas podem mudar.

status
DnDStatus

O status de arraste do provider, seja qual for o sensor que conduz o arraste.

drag
SensorDrag | null

O arraste do provider, pendente ou em andamento, seja qual for o sensor que o iniciou; null quando não há nenhum. Os sensores podem conduzir os arrastes uns dos outros: o sensor de teclado move e solta todo arraste por teclado, por exemplo, um que um botão "Move" pegou (@vue-dnd-kit/actions).

activate
(activation: SensorActivation) => SensorDrag | null

Pede para arrastar um item. O provider verifica se está ocioso (um arraste por vez, nenhum enquanto um drop pousa), se o alvo é um draggable dele que não está desabilitado, onde a entrada caiu (veja target) e o canDrag do draggable, depois espera a restrição de ativação e inicia o arraste. Retorna o arraste (pendente, ou já em andamento quando não há nada a esperar), ou null quando nenhum arraste pode começar.

cancel
() => void

Cancela o arraste ou a ativação pendente do provider, seja qual for o sensor que os conduz (Escape, uma aba oculta).

Ativação

O que um sensor pede quando a entrada dele quer arrastar (SensorContext.activate()).

target
Element | Key

Onde a entrada caiu: um elemento dentro de um draggable, ou o id de um draggable. Um elemento precisa pertencer a este provider; nos arrastes 'pointer', ele precisa estar no handle, quando houver um, e não em um filho interativo (um botão, um input); nos arrastes 'keyboard', ele precisa ser o alvo de foco do draggable (o handle, senão o próprio draggable) e não um campo editável. Um id pula essas verificações: o arraste começa a partir do item, onde quer que a entrada estivesse.

type?
SensorType

Como o arraste se move. 'pointer' (padrão): ele segue os pontos passados a move(), os alvos são testados ali, os contêineres rolam automaticamente nas bordas e a página mostra o cursor de mão agarrando. 'keyboard': ele se move de item em item com step() e place(), como as setas fazem, os alvos são revelados em vez de rolados automaticamente, e o foco volta para o item quando ele termina. Active.sensor diz qual.

point?
Coordinates

Onde o arraste começa, em coordenadas da viewport. Padrão: o centro do draggable.

event?
PointerEvent | KeyboardEvent

O evento de entrada. Ele é repassado ao canDrag do draggable: sem ele (um gamepad, um arraste programático), o canDrag não é consultado. Um pointerType igual a 'touch' faz do arraste um arraste por toque (haptics).

activation?
PointerKind | ActivationConstraint

O que o arraste espera antes de começar (useDnD().status é 'activating' até lá, com o progresso). Para um tipo de ponteiro, é lida a opção activation do draggable, depois a do provider, depois os padrões (mouse 4px, imediato em um handle; caneta 4px; toque, um toque longo de 200ms com 5px de tolerância). Uma restrição é usada como está. Padrão: nenhuma, o arraste começa na hora.

onStart?
(drag: SensorDrag) => void

O arraste começou, depois da ativação: por exemplo, capture o ponteiro.

onEnd?
(drag: SensorDrag) => void

O arraste acabou: a ativação foi abortada, ou ele foi solto ou cancelado (por quem quer que seja).

onResume?
(drag: SensorDrag) => void

O drop que o sensor pediu não aconteceu e o arraste continua (onBeforeDrop respondeu 'continue'): move, drop e cancel voltam a valer. Um sensor de ponteiro deixa o item seguir o ponteiro até o próximo soltar.

Por tipo de ponteiro. Padrões: mouse { distance: 4 } (imediato em um handle), caneta { distance: 4 }, toque { delay: 200, tolerance: 5 }.

type ActivationOptions = Partial< Record<PointerKind, ActivationConstraint> >

O que um pressionamento precisa fazer antes de virar um arraste: percorrer distance, ou ser mantido por delay, o que vier primeiro. Nada definido: o arraste começa na hora.

distance?
number

Pixels que o ponteiro precisa percorrer antes de o arraste começar.

delay?
number

Milissegundos que o ponteiro precisa ficar pressionado antes de o arraste começar.

tolerance?
number

Com delay: movimento em px que aborta a ativação, para que a página possa rolar.

O arraste

Um arraste de um sensor, de activate() até ele terminar. Toda chamada é ignorada quando não se aplica mais: movimentos antes do início ou depois do fim, um segundo drop().

id
Key

Id do item arrastado.

type
SensorType

Como o arraste se move, conforme activate() pediu (SensorActivation.type).

state
SensorDragState

Em que ponto o arraste está: esperando a ativação, arrastando ou encerrado.

started
boolean

O arraste começou, mesmo que já tenha terminado (o sensor de ponteiro engole o clique que vem depois dele).

move
(point: Coordinates) => void

A entrada se moveu. Enquanto pendente, a restrição de ativação é verificada (passar da tolerância dela a aborta); durante o arraste, o arraste vai para lá. Os arrastes por ponteiro recebem uma posição por frame; os arrastes por teclado se movem na hora, depois dos passos anteriores.

step
(direction: SensorDirection, options?: SensorStepOptions) => Promise<void>

Arrastes por teclado: um passo de seta, como fazem as setas do sensor de teclado (o próximo item de uma lista, o próximo alvo que aceita no modo 'droppables', ou keyboard.step pixels). Os passos entram em fila: cada um roda assim que o anterior é renderizado, e uma tecla repetida (event.repeat) é ignorada enquanto um passo ainda está sendo resolvido. Os arrastes por ponteiro o ignoram.

place
(position: SortablePosition) => Promise<boolean>

Coloca o item em uma posição de uma lista ordenável, como fazem os movimentos por teclado (outras listas só o recebem se o aceitarem), e move o arraste para o novo lugar. Resolve false quando nenhuma lista o aceita ali. Entra em fila como step() nos arrastes por teclado.

drop
() => Promise<boolean>

Solta: uma ativação pendente é abortada em vez disso. Resolve assim que o arraste termina e pousa: true quando o drop é concluído, false quando ele foi recusado (por um alvo, pelo onBeforeDrop) ou não havia nada para soltar.

cancel
() => void

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

  • 'pending': esperando a restrição de ativação;
  • 'dragging': do início até o drop ser decidido ou o arraste ser cancelado;
  • 'ended': a ativação foi abortada, ou o arraste foi solto ou cancelado, pelo sensor ou por qualquer outra coisa (Escape, uma aba oculta, useDnD().cancel(), o provider sendo desmontado).
type SensorDragState = 'pending' | 'dragging' | 'ended'

Opções de SensorDrag.step().

event?
KeyboardEvent

O pressionar de tecla, repassado ao getKeyboardCoordinates dos monitores. Padrão: um keydown da seta.

fast?
boolean

Um passo maior nos arrastes livres (como o Shift). Padrão: event.shiftKey.

Seta de um passo de teclado.

type SensorDirection = 'up' | 'down' | 'left' | 'right'

Uma posição em uma lista ordenável, para SensorDrag.place() (e para o moveItem de @vue-dnd-kit/actions). Só para listas: as árvores posicionam os itens pelas próprias keys.

list?
Key

Id da lista (SortableListOptions.id). Padrão: a lista em que o item está.

index?
number

Índice onde o item acaba ficando, contado sem o próprio item (um bloco de multi-drag conta uma vez). Limitado ao tamanho da lista; padrão: o final.