Dokumentation/API
Sensoren
Was Eingaben zu Drags macht – die eingebauten Sensoren für Zeiger und Tastatur und die API, um eigene zu schreiben.
Diese Seite wurde von KI übersetzt und kann Ungenauigkeiten enthalten. Englisches Original lesen
import { defineSensor, useSensor, pointerSensor, keyboardSensor } from '@vue-dnd-kit/core';
SensorMaus, Touch und Stift über Pointer Events. Standardmäßig in sensors.
SensorLeertaste/Enter, Pfeiltasten und Escape (neu belegbar mit der Option keyboard des Providers). Standardmäßig in sensors; er bricht mit Escape auch Zeiger- und eigene Drags ab, selbst mit keyboard: false.
(sensor: Sensor) => SensorDefiniert einen Sensor (siehe Sensor): Es hilft nur bei den Typen und gibt sein Argument zurück.
(sensor: Sensor) => voidFührt einen Sensor im darüberliegenden Provider aus, solange die aufrufende Komponente (oder der Effect Scope) lebt, neben den sensors des Providers. Sein Drag wird beim Unmounten abgebrochen.
Ein Sensor sagt nur „ziehe dieses Element von hier“, dann, wohin es sich bewegt hat und dass es abgelegt oder abgebrochen wurde; den Rest prüft der Provider (was gezogen werden darf, Aktivierung, immer nur ein Drag gleichzeitig). Siehe Sensoren und programmatisches Ziehen.
Unten zieht ein kleiner eigener Sensor (gestartet mit useSensor) die Figuren des Bretts von
der Minikarte aus, neben den Sensoren des Providers.
Demo wird geladen…
<script setup lang="ts">
import { DnDProvider } from '@vue-dnd-kit/core';
import SensorDesk from './SensorDesk.vue';
</script>
<template>
<DnDProvider>
<SensorDesk />
</DnDProvider>
</template>Sensor
Eingabe, die Drags startet: Zeiger, Tastatur oder deine eigene (ein Gamepad, ein Joystick auf dem Bildschirm, Sprache, per Skript gesteuerte Drags). setup läuft einmal pro Provider, nur im Browser, innerhalb eines Effect Scopes, der mit dem Provider endet (oder wenn der Sensor sensors verlässt oder die Komponente, die useSensor aufgerufen hat, unmountet wird). Registriere Listener mit useEventListener oder gib eine Aufräumfunktion zurück; ein Drag, der dann noch läuft, wird abgebrochen.
Um einen Sensor zu umhüllen, führe sein setup mit einem eigenen Kontext aus. Object.create(context, { activate: { value: … } }) behält die Live-Getter (status, drag, props): Ein Spread würde sie einfrieren.
Was ein Sensor vom Provider bekommt, in dem er läuft.
Readonly<DnDProviderProps>Die Props des Providers (z. B. activation, keyboard). Lies sie, wenn du sie brauchst: Sie können sich ändern.
DnDStatusDer Drag-Status des Providers, egal welcher Sensor den Drag ausführt.
SensorDrag | nullDer Drag des Providers, wartend oder laufend, egal welcher Sensor ihn gestartet hat; null, wenn es keinen gibt. Sensoren können die Drags der anderen steuern: Der Tastatursensor bewegt jeden Tastatur-Drag und legt ihn ab, z. B. einen, den ein „Move“-Button aufgenommen hat (@vue-dnd-kit/actions).
(activation: SensorActivation) => SensorDrag | nullFragt an, ein Element zu ziehen. Der Provider prüft, dass er frei ist (immer nur ein Drag gleichzeitig, keiner, während ein Drop landet), dass das Ziel ein eigenes ziehbares Element ist, das nicht deaktiviert ist, wo die Eingabe gelandet ist (siehe target) und canDrag des ziehbaren Elements; dann wartet er auf die Aktivierungsbedingung und startet den Drag. Gibt den Drag zurück (wartend oder bereits laufend, wenn es nichts abzuwarten gibt) oder null, wenn kein Drag beginnen darf.
() => voidBricht den Drag oder die wartende Aktivierung des Providers ab, egal welcher Sensor ihn ausführt (Escape, ein verborgener Tab).
Aktivierung
Was ein Sensor anfragt, wenn seine Eingabe ziehen will (SensorContext.activate()).
Element | KeyWo die Eingabe gelandet ist: ein Element innerhalb eines ziehbaren Elements oder die ID eines ziehbaren Elements. Ein Element muss zu diesem Provider gehören; bei 'pointer'-Drags muss es auf dem Handle liegen, wenn es eines gibt, und nicht auf einem interaktiven Kind (einem Button, einem Eingabefeld); bei 'keyboard'-Drags muss es das Fokusziel des ziehbaren Elements sein (das Handle, sonst das ziehbare Element selbst) und kein editierbares Feld. Eine ID überspringt diese Prüfungen: Der Drag startet vom Element, wo auch immer die Eingabe war.
SensorTypeWie sich der Drag bewegt. 'pointer' (Standard): Er folgt den Punkten, die an move() übergeben werden, Ziele werden dort per Hit-Testing ermittelt, Container scrollen an ihren Rändern automatisch, und die Seite zeigt den Greif-Cursor. 'keyboard': Er bewegt sich mit step() und place() von Element zu Element, wie es die Pfeiltasten tun, Ziele werden ins Sichtfeld gebracht statt per Auto-Scroll angefahren, und der Fokus kehrt am Ende zum Element zurück. Active.sensor sagt, welcher Typ es ist.
CoordinatesWo der Drag beginnt, in Viewport-Koordinaten. Standard: die Mitte des ziehbaren Elements.
PointerEvent | KeyboardEventDas Eingabe-Event. Es wird an canDrag des ziehbaren Elements übergeben: Ohne Event (ein Gamepad, ein programmatischer Drag) wird canDrag nicht gefragt. Ein pointerType von 'touch' macht den Drag zu einem Touch-Drag (haptics).
PointerKind | ActivationConstraintWorauf der Drag wartet, bevor er beginnt (useDnD().status ist bis dahin 'activating', mit seinem Fortschritt). Eine Zeigerart liest dafür die Option activation des ziehbaren Elements, dann die des Providers, dann die Standardwerte (Maus 4px, sofort bei einem Handle; Stift 4px; Touch ein langes Drücken von 200ms mit 5px Toleranz). Eine Aktivierungsbedingung wird so verwendet, wie sie ist. Standard: keine, der Drag beginnt sofort.
(drag: SensorDrag) => voidDer Drag hat begonnen, nach seiner Aktivierung: z. B. den Zeiger einfangen.
(drag: SensorDrag) => voidDer Drag ist vorbei: Seine Aktivierung wurde abgebrochen, oder er wurde abgelegt oder (von wem auch immer) abgebrochen.
(drag: SensorDrag) => voidDer Drop, den der Sensor angefragt hat, hat nicht stattgefunden, und der Drag geht weiter (onBeforeDrop hat 'continue' geantwortet): move, drop und cancel gelten wieder. Ein Zeigersensor lässt das Element bis zum nächsten Loslassen dem Zeiger folgen.
Pro Zeigerart. Standardwerte: Maus { distance: 4 } (sofort bei einem Handle), Stift { distance: 4 }, Touch { delay: 200, tolerance: 5 }.
type ActivationOptions = Partial< Record<PointerKind, ActivationConstraint> >Was ein Drücken tun muss, bevor es zum Drag wird: distance zurücklegen oder für delay gehalten werden, je nachdem, was zuerst eintritt. Nichts gesetzt: Der Drag startet sofort.
Der Drag
Ein Drag eines Sensors, von activate() bis zu seinem Ende. Jeder Aufruf wird ignoriert, sobald er nicht mehr zutrifft: Bewegungen vor dem Start oder nach dem Ende, ein zweites drop().
KeyID des gezogenen Elements.
SensorTypeWie sich der Drag bewegt, wie von activate() angefragt (SensorActivation.type).
SensorDragStateWo der Drag steht: wartet auf seine Aktivierung, zieht oder ist beendet.
booleanDer Drag hat begonnen, auch wenn er inzwischen geendet hat (der Zeigersensor schluckt den Klick, der darauf folgt).
(point: Coordinates) => voidDie Eingabe hat sich bewegt. Im Wartezustand wird die Aktivierungsbedingung geprüft (eine Bewegung über ihre Toleranz hinaus bricht sie ab); während des Ziehens geht der Drag dorthin. Zeiger-Drags übernehmen eine Position pro Frame; Tastatur-Drags bewegen sich sofort, nach den Schritten davor.
(direction: SensorDirection, options?: SensorStepOptions) => Promise<void>Tastatur-Drags: ein Pfeilschritt, wie ihn die Pfeiltasten des Tastatursensors ausführen (das nächste Element einer Liste, das nächste annehmende Ziel im Modus 'droppables' oder keyboard.step Pixel). Schritte werden eingereiht: Jeder läuft, sobald der vorherige gerendert ist, und eine wiederholte Taste (event.repeat) wird übersprungen, solange noch einer läuft. Zeiger-Drags ignorieren ihn.
(position: SortablePosition) => Promise<boolean>Setzt das Element an eine Position einer sortierbaren Liste, wie es Tastaturbewegungen tun (andere Listen nehmen es nur, wenn sie es annehmen), und bewegt den Drag an seinen neuen Platz. Liefert false, wenn keine Liste es dort nimmt. In Tastatur-Drags wie step() eingereiht.
() => Promise<boolean>Legt ab: Eine wartende Aktivierung wird stattdessen abgebrochen. Liefert sein Ergebnis, sobald der Drag geendet hat und gelandet ist: true, wenn der Drop ausgeführt wurde, false, wenn er abgelehnt wurde (von einem Ziel, von onBeforeDrop) oder es nichts abzulegen gab.
() => voidBricht den Drag ab (er fliegt zurück) oder bricht eine wartende Aktivierung ab.
'pending': wartet auf die Aktivierungsbedingung;'dragging': vom Start, bis über den Drop entschieden ist oder der Drag abgebrochen wird;'ended': Die Aktivierung wurde abgebrochen, oder der Drag wurde abgelegt oder abgebrochen, vom Sensor oder durch etwas anderes (Escape, ein verborgener Tab,useDnD().cancel(), das Unmounten des Providers).
type SensorDragState = 'pending' | 'dragging' | 'ended'Optionen von SensorDrag.step().
Pfeil eines Tastaturschritts.
type SensorDirection = 'up' | 'down' | 'left' | 'right'Eine Position in einer sortierbaren Liste, für SensorDrag.place() (und moveItem aus @vue-dnd-kit/actions). Nur Listen: Bäume platzieren Elemente über ihre eigenen Schlüssel.