Dokumentation/API

makeDraggable

Macht ein Element ziehbar – frei oder in die Drop-Ziele, die es annehmen.

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

function makeDraggable<TData = unknown>(  target: MaybeElementRef,  options?: DraggableOptions<TData>,): DraggableReturn;

Macht ein Element ziehbar. Standardmäßig freies Ziehen; sortierbare Listen bauen darauf auf.

const el = useTemplateRef<HTMLElement>('el');
const { isDragging } = makeDraggable(el, { id: 'card', type: 'card', data: { title } });

Siehe Drag and Drop. Auch sortierbare Elemente sind ziehbare Elemente: makeSortableItem nimmt dieselben Optionen und mehr.

Live Ziehe jede Karte. Lass los, und sie kehrt zurück

Demo wird geladen…

<script setup lang="ts">
import { DnDProvider } from '@vue-dnd-kit/core';
import DragCard from './DragCard.vue';
</script>

<template>
  <!-- No drop target here: let go, and each card goes back where it was. -->
  <DnDProvider>
    <div class="cards">
      <DragCard title="Grab it anywhere" code="makeDraggable(el)" />
      <DragCard title="Grab the handle" code="{ handle: grip }" handle />
      <DragCard title="It moves itself" code="{ overlay: false }" self />
      <DragCard title="Not now" code="{ disabled: true }" disabled />
    </div>
  </DnDProvider>
</template>

<style scoped>
.cards {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 220px));
  gap: 14px;
}

@media (max-width: 480px) {
  .cards {
    grid-template-columns: minmax(0, 1fr);
  }
}
</style>

Optionen

Optionen von makeDraggable. Jede Option außer canDrag nimmt einen Wert, ein Ref oder einen Getter entgegen (overlay, dropAnimation: einen Wert oder ein Ref) und wird gelesen, wenn sie gebraucht wird, sodass eine Änderung spätestens ab dem nächsten Drag gilt.

id?

KeyWert · Ref · Getter

Stabile ID. Übergib in virtuellen Listen, in denen Elemente wiederverwendet werden, einen Getter. Standard: useId(), stabil zwischen Server- und Client-Rendering, aber neu für jede Komponenteninstanz.

data?

TDataWert · Ref · Getter

Alles, was der Drag mitführen soll: Events und Drop-Ziele lesen es als active.data.

label?

stringWert · Ref · Getter

Der lesbare Name: Screenreader-Texte nennen ihn statt der ID (Picked up Tomato). Events tragen ihn als active.label und in items.

type?

string | string[]Wert · Ref · Getter

Sein Typ oder seine Typen, abgeglichen mit den accept-Regeln der Drop-Ziele. Ohne Typ passt es zu jedem Ziel.

disabled?

booleanWert · Ref · Getter

true: Es kann nicht gezogen werden (es meldet aria-disabled).

handle?

MaybeElement | stringWert · Ref · Getter

Element oder Selektor innerhalb des ziehbaren Elements, der den Drag startet (und die Attribute bekommt).

activation?

ActivationOptionsWert · Ref · Getter

Überschreibt activation des Providers. Wird gelesen, wenn ein Druck beginnt.

canDrag?

(event: PointerEvent | KeyboardEvent) => boolean

Zusätzliche Bedingung, z. B. nur ziehen, solange eine Taste gedrückt ist.

overlay?

boolean | ComponentWert · Ref

true (Standard): Ein Overlay folgt dem Zeiger, gerendert vom Slot #overlay des Providers oder als Klon des Elements. Eine Komponente: Das Overlay rendert sie mit OverlayProps, vor dem Slot. false: kein Overlay, das Element selbst bewegt sich über das zurückgegebene transform. Ein Wert oder ein Ref (eine Funktion ist eine funktionale Komponente, (props) => <Card {...props} /> funktioniert also). Ob es ein Overlay gibt, wird beim Start des Drags entschieden; ein mitten im Drag umgeschaltetes Ref tauscht die Komponente sofort (siehe overlayTransition des Providers). Das overOverlay eines Drop-Ziels gewinnt, solange der Drag darüber ist. Der Klon lässt die Druckeffekte von UI-Kits (Ripples) weg sowie jedes Element darin, das mit data-dnd-no-clone markiert ist.

dropAnimation?

DropAnimationWert · Ref

Wie das Overlay landet, wenn ein Drag dieses Elements endet, statt der dropAnimation des Providers; die overDropAnimation eines Drop-Ziels gewinnt. Ein Wert oder ein Ref (eine Funktion ist die Animation), gelesen beim Drop.

modifiers?

Modifier[]Wert · Ref · Getter

Modifier für Drags, die hier beginnen, angewendet nach den modifiers des Providers: z. B. [restrictToVerticalAxis] für ein Element auf einer Seite, auf der sich andere Drags frei bewegen. Wird beim Start des Drags gelesen.

axis?

'x' | 'y'Wert · Ref · Getter

Beschränkt Drags, die hier beginnen, auf eine Achse: 'x' bewegt nur horizontal, 'y' nur vertikal. Die Sperre kommt nach modifiers (restrictToHorizontalAxis / restrictToVerticalAxis als Letztes), sie gilt also, egal was diese tun. Wird beim Start des Drags gelesen.

keyboardMode?

'pixels' | 'droppables'Wert · Ref · Getter

Pfeiltasten bei freien Drags: um Pixel bewegen (Standard) oder zwischen annehmenden Drop-Zielen springen. Wird bei jedem Druck auf eine Pfeiltaste gelesen.

attributes?

booleanWert · Ref · Getter

Setzt role-/tabindex-/aria-*-Attribute (Standard true) und überschreibt nie deine eigenen. Die ID der Anweisungen des Providers wird einem vorhandenen aria-describedby als weiteres Token hinzugefügt (ein Tooltip eines UI-Kits auf demselben Element behält sein eigenes), und nur dieses Token wird je entfernt. Live: Ausschalten entfernt, was die Bibliothek gesetzt hat.

native?

boolean | NativeDragOptionsWert · Ref · Getter

Ein Maus-Drag des Elements ist der eigene Drag des Browsers, der die Seite verlassen kann: auf den Desktop, in eine andere App oder einen anderen Tab, in ein anderes Fenster der App. Auf der Seite funktioniert er wie gewohnt (Ziele, Listen, die Platz machen), aber der Browser zeichnet das gezogene Bild statt des Overlays. Drags per Touch und Tastatur bleiben die der Bibliothek. true trägt das label als Text. Wird gelesen, wenn ein Druck beginnt. canDrag wird beim Drücken gefragt; wie weit sich eine Maus bewegen muss, bevor ihr Drag startet, entscheidet der Browser (activation gilt dafür nicht).

Rückgabe

Was makeDraggable zurückgibt.

ComputedRef<Key>

Die ID des ziehbaren Elements: die Option id oder die dafür erzeugte.

isDragging

ComputedRef<boolean>

Es wird gezogen (auch als weiteres Element eines Multi-Drags), oder sein Overlay landet noch.

transform

ComputedRef<Coordinates | null>

Versatz, der bei overlay: false anzuwenden ist: der des Drags, abzüglich dessen, wie weit sich der Inhalt, in dem das Element liegt, seit dem Start bewegt hat (die Seite oder ein Container wurde gescrollt), sodass das Element unter dem Zeiger bleibt.

selected

WritableComputedRef<boolean>

Es ist in der Auswahl des Providers: Ein Drag eines ausgewählten Elements trägt sie alle. Setze den Wert, um es aus- oder abzuwählen.

Aus der Seite hinaus

Was ein native-Drag aus der Seite hinausträgt. Siehe Dateien und andere Apps.

Ein ziehbares oder sortierbares Element, das eine Maus aus der Seite hinausziehen kann (native): auf den Desktop, in eine andere App, einen anderen Tab, ein anderes Fenster der App.

data?

(active: Active) => Record<string, string>

Was andere Apps und Seiten bekommen: Text nach MIME-Typ, als { 'text/plain': title, 'text/uri-list': url }. Wird beim Start des Drags gelesen. Sortierbare Elemente tragen außerdem sich selbst, für die Listen ihrer Gruppe in einem anderen Fenster der App.

effect?

Was der Drag dem Ort, an dem er abgelegt wird, erlaubt (effectAllowed). Standard 'copyMove': Ein Verschieben nimmt die Elemente hier aus ihrer Liste, eine Kopie lässt sie dort.