vue-dnd-kit

Dokumentation/API

useDnD und Monitore

Der Zustand des Drags und seine Events, überall unterhalb des Providers – und der Provider selbst, übergeben an eine andere Vue-App.

Diese Seite bearbeiten

Diese Seite wurde von KI übersetzt und kann Ungenauigkeiten enthalten. Englisches Original lesen

Live

Demo wird geladen…

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

Schreibgeschützter Drag-Zustand für eigene UI (Hervorheben gültiger Ziele, Spinner, Fortschritt).

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

Der Zustand des Drags im Provider, reaktiv. active und over werden geleert, sobald über den Drop entschieden ist, während das Overlay noch landet.

Der Zustand des Drags endet, wenn über den Drop entschieden ist: active, over und pointer sind null (und Drop-Zonen nehmen nichts mehr an), während das Overlay noch an seinen Platz animiert. Abgeleitete UI mischt nie den alten Drag mit den neuen Daten. Während ein asynchrones onBeforeDrop entscheidet, bleibt der Zustand so, wie er beim Loslassen war, aber die Seite ist nicht mehr im Drag-Modus: Ihr eigener Cursor und die Textauswahl sind zurück (ein Bestätigungsdialog funktioniert normal), und das Overlay wartet dort, wo es abgelegt wurde.

status ist 'dragging', solange ein Drag läuft, sonst 'dropping', solange über einen Drop entschieden wird oder ein Overlay noch landet, sonst 'idle' (abgesehen von 'activating' und 'selecting'). Ein neuer Drag wartet nicht auf die Landungen: Er startet sofort, und sie enden um ihn herum.

status
Readonly<Ref<DnDStatus>>

Was der Provider gerade tut (siehe DnDStatus).

active
Readonly<Ref<Active | null>>

Der laufende Drag; null ohne Drag und sobald über seinen Drop entschieden ist.

over
Readonly<Ref<Over | null>>

Das Drop-Ziel unter dem Drag; null über nichts.

pointer
Readonly<Ref<Coordinates | null>>

Zeiger in Viewport-Koordinaten, nach den Modifiern; null ohne Drag.

position
Readonly<Ref<Coordinates | null>>

Wo die linke obere Ecke der gezogenen Box gerade in over liegt, live: DnDEvent.position bei jeder Bewegung. null über nichts. Eine Overlay-Komponente liest es, um zu zeigen, wo sie landen würde (eine Uhrzeit in einem Kalender).

activation
{ progress: Readonly<Ref<number>> }

progress: wie weit ein Drücken seiner Aktivierungsbedingung nähergekommen ist, von 0 bis 1, solange status 'activating' ist: z. B. ein Ring, der sich während eines langen Drückens füllt.

isAutoScrolling
Readonly<Ref<boolean>>

Auto-Scroll bewegt gerade einen Container.

selection
DnDSelection

Die ausgewählten ziehbaren Elemente (siehe DnDSelection).

cancel
() => void

Bricht den Drag (er fliegt zurück) oder die ausstehende Aktivierung ab.

Auswahl

Die ausgewählten ziehbaren Elemente, nach ID: Ein Drag eines von ihnen trägt sie alle (Multi-Drag). Da sie nach ID geführt wird, übersteht eine Auswahl Unmounts (virtuelle Listen).

ids
ReadonlySet<Key>

Die ausgewählten IDs, reaktiv.

has
(id: Key) => boolean

Ob id ausgewählt ist.

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

Wählt diese IDs aus.

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

Hebt die Auswahl dieser IDs auf.

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

Wählt id aus oder hebt die Auswahl auf; force: true wählt es aus, false hebt die Auswahl auf.

set
(ids: Iterable<Key>) => void

Wählt diese IDs aus und keine anderen.

clear
() => void

Hebt die Auswahl aller IDs auf.

useDnDMonitor

function useDnDMonitor(monitor: DnDMonitor): void;

Abonniert die Events jedes Drags unter dem Provider, solange die aufrufende Komponente (oder der Effect Scope) lebt.

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

Deine Monitore werden vor dem Ziel zu einem Drop befragt (onBeforeDrop). Die Payloads findest du unter Events.

Hooks für jeden Drag unter dem Provider (useDnDMonitor).

onDragStart?
(event: DnDEvent) => void

Ein Drag hat begonnen, nach seiner Aktivierung.

onDragMove?
(event: DnDEvent) => void

Der Drag hat sich bewegt (höchstens einmal pro Frame).

onDragOver?
(event: DnDEvent) => void

Das Ziel unter dem Drag hat sich geändert.

onBeforeDrop?
(event: DnDEvent) => MaybePromise<BeforeDropResult>

Läuft, bevor der Drop festgeschrieben wird (siehe BeforeDropResult): 'reject' lehnt ihn ab, IDs nehmen eine Teilmenge an.

onDragEnd?
(event: DnDEndEvent) => void

Eine Benachrichtigung, sobald der Drop erledigt ist: Sortierbare Listen haben ihr onDrop ausgeführt und ihn geschrieben.

onDragCancel?
(event: DnDEvent) => void

Der Drag wurde abgebrochen oder sein Drop abgelehnt: Die Elemente fliegen zurück.

onDragResume?
(event: DnDEvent) => void

onBeforeDrop hat 'continue' geantwortet: Es gab keinen Drop, und der Drag geht weiter.

onDragSettle?
(event: DnDEvent | DnDEndEvent) => void

Das Overlay eines beendeten Drags ist gelandet: nach seiner Drop-Animation (oder dem Rückflug bei einem Abbruch), mit dem Event, das onDragEnd (ein DnDEndEvent) oder onDragCancel bekommen hat. Der nächste Drag kann inzwischen begonnen haben: Drags warten nicht auf Landungen.

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

Drags per Tastatur: nächste Zeigerposition für eine Pfeiltaste (z. B. der nächste sortierbare Slot).

Womit getKeyboardCoordinates für eine Pfeiltaste aufgerufen wird.

active
Active

Der Drag.

pointer
Coordinates

Wo der Drag gerade ist, in Viewport-Koordinaten.

direction
Coordinates

Einheitsvektor der gedrückten Pfeiltaste.

useDnDContext und provideDnDContext

function useDnDContext(): DnDContext;

Der Provider über dieser Komponente, als opakes Handle für provideDnDContext: Es bringt den Provider in Shadow Roots und separate Vue-Apps.

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

Teilt einen Provider (aus useDnDContext()) mit einer anderen Vue-App, z. B. einer, die in einem Shadow Root gemountet ist.

// 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);

Ein Provider, wie useDnDContext() ihn zurückgibt, zur Übergabe an provideDnDContext(): Eine andere Vue-App (z. B. eine in einem Shadow Root gemountete) arbeitet dann mit demselben Provider. Opak: Er hat keine öffentlichen Member und ändert sich daher nie mit den Interna der Bibliothek.