vue-dnd-kit

Documentação/API

Modificadores e colisão

Funções que mudam para onde vai o item arrastado, e as que escolhem o alvo sob ele.

Editar esta página

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

Live

Carregando a demo…

<script setup lang="ts">
import { ref } from 'vue';
import { DnDProvider, closestCenter, closestCorners, pointerFirst, pointerWithin, rectIntersection } from '@vue-dnd-kit/core';
import ModifierLab from './ModifierLab.vue';

// Collision detection is the provider's: it picks the target, here one of the two pads.
const COLLISIONS = { pointerFirst, pointerWithin, rectIntersection, closestCenter, closestCorners };
const collision = ref<keyof typeof COLLISIONS>('pointerFirst');
</script>

<template>
  <DnDProvider :collision="COLLISIONS[collision]">
    <div class="demo">
      <code class="call">&lt;DnDProvider :collision="{{ collision }}"&gt;</code>
      <div class="collisions" role="radiogroup" aria-label="collision">
        <label v-for="name in Object.keys(COLLISIONS)" :key="name" :class="{ on: collision === name }">
          <input v-model="collision" type="radio" :value="name" />
          {{ name }}
        </label>
      </div>
      <ModifierLab />
    </div>
  </DnDProvider>
</template>

<style scoped>
.demo {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 10px;
}

.collisions {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 2px;
  max-width: 100%;
  padding: 3px;
  border-radius: 9px;
  background: color-mix(in srgb, currentColor 7%, transparent);
}

.call {
  font: 11px/1.4 ui-monospace, Menlo, Consolas, monospace;
  color: #42b883;
}

label {
  padding: 4px 8px;
  border-radius: 6px;
  font: 11px/1.3 ui-monospace, Menlo, Consolas, monospace;
  cursor: pointer;
}

label.on {
  background: Canvas;
  box-shadow: 0 1px 3px rgb(0 0 0 / 0.25);
  font-weight: 600;
}

label:has(input:focus-visible) {
  outline: 2px solid #42b883;
}

input {
  position: absolute;
  opacity: 0;
  pointer-events: none;
}
</style>

Modificadores

import { restrictToParent, snapToGrid } from '@vue-dnd-kit/core';

makeSortableList(list, { items, modifiers: [restrictToParent] });
makeDragArea(board, { modifiers: [snapToGrid({ x: 24, y: 24, smooth: true })] });

Um modificador recebe o deslocamento do arraste e retorna um novo. Eles rodam em ordem: os modifiers do provider, os de uma área de arraste, os do próprio draggable (ou da lista dele), depois os limites da área (restrictToArea), e a trava de axis por último. Veja Eixos, limites e grades.

restrictToVerticalAxis
Modifier

Move só na vertical: na horizontal ele acompanha o conteúdo onde começou (containerShift), não importa como a página role. A opção axis: 'y' faz o mesmo, por último.

restrictToHorizontalAxis
Modifier

Move só na horizontal: na vertical ele acompanha o conteúdo onde começou (containerShift), não importa como a página role. A opção axis: 'x' faz o mesmo, por último.

restrictToWindowEdges
Modifier

Mantém o overlay dentro da janela.

restrictToParent
Modifier

Mantém o overlay dentro do contêiner onde o arraste começou: a lista ordenável (não o pai dela no DOM) ou, para draggables simples, o elemento pai.

restrictToElement
(target: MaybeElementRef) => Modifier

Mantém o overlay dentro de um elemento: o elemento, um ref ou um getter.

restrictToFirstScrollableAncestor
Modifier

Mantém o overlay dentro do primeiro ancestral rolável do elemento arrastado.

snapToGrid
(size: number | SnapToGridOptions) => Modifier

Encaixa o overlay em uma grade, na célula mais próxima: um número é o tamanho de células quadradas; as opções definem cada eixo, onde a grade começa e um deslizamento entre as células (SnapToGridOptions).

snapCenterToCursor
Modifier

Centraliza o overlay sob o ponteiro em vez de manter o deslocamento de onde ele foi pego.

Opções de snapToGrid.

x?
number

A largura da célula em px. Sem ela (ou 0), o arraste se move livremente no eixo x.

y?
number

A altura da célula em px. Sem ela (ou 0), o arraste se move livremente no eixo y: { y: 15 } encaixa só o horário de um evento de calendário.

origin?
'container' | 'delta'

'container' (padrão): o canto superior esquerdo do overlay pousa nas linhas de uma grade traçada a partir do canto superior esquerdo do contêiner (containerRect: a lista ordenável ou o elemento pai). 'delta': o deslocamento do arraste é arredondado, mantendo fora da grade o ponto onde o item começou.

smooth?
boolean | AnimationOptions

Desliza o overlay entre as posições encaixadas (padrão 80ms). A colisão continua usando a posição encaixada na hora.

Muda para onde o item arrastado vai: recebe o deslocamento do arraste (transform) e retorna um novo.

type Modifier = (args: ModifierArgs) => Coordinates

O que um modificador recebe, a cada movimento do arraste.

transform
Coordinates

Deslocamento desde o início do arraste, como modificado pelos modificadores anteriores.

active
Active

O arraste.

activeRect
Rect

Retângulo do elemento arrastado no início do arraste.

overlayRect
Rect

Retângulo da caixa do overlay se ela fosse movida por transform, no tamanho que tem agora. Com overlayFit: 'slot', a caixa se redimensiona ao redor do ponteiro, então nem sempre é activeRect movido por transform.

origin
Coordinates

Posição do ponteiro no início do arraste.

containerRect
Rect | null

Contêiner da lista ordenável (ou elemento pai) do item arrastado, onde ele está agora (acompanha a rolagem).

containerShift
Coordinates

Quanto o conteúdo onde o arraste começou se moveu na tela desde o início: o contêiner se moveu (a página ou um contêiner em volta dele rolou, o layout mudou) e o conteúdo dele rolou dentro dele. As travas de eixo prendem o outro eixo ali, para que o arraste fique na sua linha ou coluna desse conteúdo.

windowRect
Rect

Retângulo da janela (a viewport).

over
Over | null

O alvo de drop sob o arraste, como encontrado por último; null sobre nada.

Detecção de colisão

import { closestCorners } from '@vue-dnd-kit/core';

<DnDProvider :collision="closestCorners" />

O collision do provider escolhe o alvo; o melhor candidato vem primeiro.

pointerFirst
CollisionDetection

Padrão: o que está sob o ponteiro, senão o que o overlay sobrepõe.

pointerWithin
CollisionDetection

Alvos sob o ponteiro, obtidos por hit-testing: respeita z-order, overlays e shadow roots.

rectIntersection
CollisionDetection

Alvos que se sobrepõem ao overlay: maior prioridade, depois aninhamento mais profundo, depois intersection over union.

closestCenter
CollisionDetection

Todos os alvos, pela distância entre os centros.

closestCorners
CollisionDetection

Todos os alvos, pela soma das distâncias entre os cantos (bom para alvos empilhados, como colunas de kanban).

Retorna os ids dos candidatos, o melhor primeiro.

type CollisionDetection = (args: CollisionArgs) => Key[]

O que uma detecção de colisão recebe, a cada movimento do arraste.

pointer
Coordinates

Ponteiro em coordenadas da viewport, depois dos modificadores.

overlayRect
Rect | null

Retângulo da caixa arrastada (o overlay, ou o próprio elemento com overlay: false) onde o arraste a colocou.

candidates
CollisionCandidate[]

Todos os alvos de drop para onde o arraste poderia ir, quer a regra accept deles aceite o arraste ou não.

hits
Key[]

Alvos de drop sob o ponteiro, obtidos por hit-testing (respeita z-order e shadow roots), o melhor primeiro.

Um alvo de drop que uma detecção de colisão pode escolher: habilitado, na página e não totalmente recortado.

id
Key

Id do alvo de drop.

rect
Rect

Parte visível do alvo: recortada pelos contêineres de rolagem dele e pela viewport.

priority
number

A priority do alvo (padrão 0): o maior vence quando alvos se sobrepõem sem aninhamento. Itens ordenáveis vencem os contêineres.

depth?
number

Nível de aninhamento entre os alvos de drop: 0 no topo, alvos mais profundos têm valores maiores.