vue-dnd-kit

Dokumentation/API

makeSortableList

Macht einen Container zu einer sortierbaren Liste – ein Entwurf, der sich während des Ziehens neu ordnet und beim Drop zurückgeschrieben wird.

Diese Seite bearbeiten

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

function makeSortableList<T>(  target: MaybeElementRef,  options: SortableListOptions<T>,): SortableListReturn<T>;

Macht einen Container zu einer sortierbaren Liste. Rendere die zurückgegebenen items (die Entwurfsreihenfolge), nicht dein Array: Der Drop wird nach onDrop in options.items zurückgeschrieben, sofern event.preventDefault() event.result nicht dir überlässt.

const list = useTemplateRef<HTMLElement>('list');
const { items } = makeSortableList(list, { items: tasks, group: 'board' });

Ihre Zeilen rufen makeSortableItem auf. Siehe Sortierbare Listen und Listen mit gemeinsamen Elementen.

Live

Demo wird geladen…

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

const strategy = ref<'vertical' | 'horizontal' | 'grid'>('grid');
const placeholder = ref<'item' | 'indicator'>('item');
const behavior = ref<'sort' | 'swap'>('sort');
</script>

<template>
  <DnDProvider>
    <div class="demo">
      <div class="switches">
        <Segmented v-model="strategy" name="strategy" :options="['vertical', 'horizontal', 'grid']" />
        <Segmented v-model="placeholder" name="placeholder" :options="['item', 'indicator']" />
        <Segmented v-model="behavior" name="behavior" :options="['sort', 'swap']" />
      </div>
      <code class="call">makeSortableList(el, { strategy: '{{ strategy }}', placeholder: '{{ placeholder }}', behavior: '{{ behavior }}' })</code>
      <Tiles :strategy="strategy" :placeholder="placeholder" :behavior="behavior" />
    </div>
  </DnDProvider>
</template>

<style scoped>
.demo {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 18px;
  max-width: 100%;
}

.switches {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 16px;
}

.call {
  max-width: 100%;
  padding: 6px 10px;
  overflow-x: auto;
  border-radius: 8px;
  background: color-mix(in srgb, currentColor 6%, transparent);
  font: 11px/1.4 ui-monospace, Menlo, Consolas, monospace;
  white-space: nowrap;
  color: #42b883;
}
</style>

Optionen

Optionen von makeSortableList. Eine Komponente kann mehrere Listen (und Bäume) erstellen: Jedes darin gerenderte Element gehört zur innersten, deren DOM-Element es enthält.

Optionen nehmen einen Wert, ein Ref oder einen Getter entgegen (overlay, overOverlay, dropAnimation, overDropAnimation, animation: einen Wert oder ein Ref) und werden gelesen, wenn die Liste sie braucht, sodass eine Änderung spätestens ab dem nächsten Drag gilt. Ausnahmen: id und group werden einmal gelesen, wenn die Liste erstellt wird; items ist das Modell selbst; Funktionen (getKey, filter, clone, createItem, die Callbacks) werden so übergeben, wie sie sind.

items
SortableItems<T>

Die Quelle der Wahrheit. Ein beschreibbares Ref bekommt beim Drop das neue Array, direkt nach onDrop. Eine schreibgeschützte Quelle (ein Getter, ein readonly Ref, ein computed) kann das nicht: Rufe event.preventDefault() auf und wende event.result selbst an. Entwicklungs-Builds warnen dort vor einem Drop, der der Bibliothek überlassen wird und dann nichts ändert.

getKey?
(item: T) => Key

Standard: item.id oder bei Primitiven das Element selbst. Liefert auch die Schlüssel für makeSortableItem({ item }).

filter?
(item: T) => boolean

Zeigt nur die Elemente, für die es true zurückgibt (eine Suche, ein Tag): items (das zurückgegebene) enthält sie, und ein Drag sortiert unter ihnen. Die anderen behalten ihre Plätze in der Quelle: Ein Drop schreibt das ganze Array, jedes ausgeblendete Element weiterhin hinter dem gezeigten, dem es folgte (hinter dem nächsten, das an seinem Platz blieb, wenn jenes sich bewegt hat). Reaktiv: Was es liest (ein Ref mit der Suchanfrage), gilt sofort. e.to.index und activeIndex zählen die gezeigten Elemente.

id?
Key

Standard: useId(), stabil zwischen Server- und Client-Rendering. Wird einmal gelesen.

label?
stringWert · Ref · Getter

Der lesbare Name der Liste: Screenreader-Texte nennen ihn statt ihrer ID (position 2 of 5 in Garden).

data?
unknownWert · Ref · Getter

Alles, was es über die Liste als Drop-Ziel zu sagen gibt: Events tragen es als over.data, solange ein Drag über ihr ist.

activation?
ActivationOptionsWert · Ref · Getter

Wie ein Druck auf die Elemente dieser Liste einen Drag startet, statt activation des Providers (die eigene eines Elements gewinnt). Wird gelesen, wenn ein Druck beginnt.

overlay?
ComponentWert · Ref

Overlay-Komponente für die Elemente dieser Liste (das eigene overlay eines Elements gewinnt). Sie bekommt OverlayProps und bleibt für den ganzen Drag erhalten, auch über anderen Listen, sofern das Ziel unter dem Drag kein eigenes Overlay hat (overOverlay). Ein mitten im Drag umgeschaltetes Ref tauscht sie sofort.

overOverlay?
ComponentWert · Ref

Was das Overlay zeigt, während ein Drag, den diese Liste annimmt, über ihr ist, egal aus welcher Liste er kommt: eine Komponente, die OverlayProps und das eigene Overlay des Drags als Standard-Slot bekommt (siehe DroppableOptions.overOverlay). Wird live gelesen.

dropAnimation?
DropAnimationWert · Ref

Wie das Overlay landet, wenn ein Drag der Elemente dieser Liste endet, statt der dropAnimation des Providers (die eigene eines Elements gewinnt; die eines Drop-Ziels gewinnt gegen beide). Wird beim Drop gelesen.

overDropAnimation?
DropAnimationWert · Ref

Wie das Overlay landet, wenn es in diese Liste abgelegt wird, egal aus welcher Liste es kommt: gewinnt gegen die dropAnimation des gezogenen Elements und des Providers. Wird beim Drop gelesen.

modifiers?
Modifier[]Wert · Ref · Getter

Modifier für Drags der Elemente dieser Liste, angewendet nach den modifiers des Providers (die eigenen modifiers eines Elements gewinnen): z. B. [restrictToVerticalAxis], um die Elemente einer vertikalen Liste auf ihrer Achse zu halten. Wird beim Start des Drags gelesen.

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

Beschränkt Drags der Elemente dieser Liste auf eine Achse: 'y' für eine vertikale Liste, 'x' für eine horizontale (das eigene axis eines Elements gewinnt). Die Sperre kommt nach den Modifiern, sie gilt also, egal was diese tun. Wird beim Start des Drags gelesen.

group?
string | SortableGroupOptions<T>

Listen mit demselben Gruppennamen tauschen Elemente aus. Standard: eine eigene Gruppe. Wird einmal gelesen.

acceptMode?
AcceptModeWert · Ref · Getter

Multi-Drag von Elementen mehrerer Typen: 'all' (Standard) oder 'some' müssen angenommen werden (group.put).

strategy?
SortableStrategyWert · Ref · Getter

Standard 'vertical'.

behavior?
SortableBehaviorWert · Ref · Getter

'swap': Das gezogene Element tauscht live den Platz mit dem Element unter dem Zeiger; wieder darauf oder aus den Listen hinaus zu ziehen macht das rückgängig. Listen einer Gruppe, die beide tauschen, tauschen Elemente untereinander aus: Das Element unter dem Zeiger wandert an den Platz des gezogenen, es muss also seine Liste verlassen (group.pull: true) und in die des gezogenen Elements kommen können (group.put). Multi-Drag sortiert stattdessen. Standard 'sort'.

placeholder?
SortablePlaceholderWert · Ref · Getter

'indicator': Die Liste bewegt sich nicht, indicator sagt, wohin der Drop geht. Standard 'item'.

multiple?
MultipleModeWert · Ref · Getter

Multi-Drag-Modus der Drags, die in dieser Liste beginnen. Standard 'group'. Wird beim Start des Drags gelesen.

sort?
booleanWert · Ref · Getter

false: Elemente lassen sich innerhalb dieser Liste nicht neu ordnen (Paletten).

clone?
(item: T) => T

Erstellt Kopien (pull: 'clone', Modifier-Taste zum Kopieren). Zum Kopieren erforderlich.

createItem?
(active: Active) => T | T[]

Nimmt einfache ziehbare Elemente von außen an: erstellt das einzufügende Element. Mit der Tastatur holt ein Pfeil in Richtung der Liste das ziehbare Element herein (auf seiner Höhe, wie bei Bewegungen zwischen Listen), und das erstellte Element bewegt sich dann wie jedes andere von Slot zu Slot.

Bei einem Drag von außerhalb der Seite (external) wird es zweimal gefragt: während er gehalten wird, nach dem Element, das zeigt, wo er hinkommt (dann sind nur active.external.fileTypes und types bekannt), und beim Drop, mit seinen Daten (active.external.ready), nach dem, was eingefügt wird. Ein Array von Elementen wird komplett dort eingefügt, wo der Slot war: eines pro Datei.

external?
ExternalAcceptWert · Ref · Getter

Nimmt Drags von außerhalb der Seite an: Dateien, Links, Text (siehe ExternalAccept). Die Liste macht ihnen Platz wie einem einfachen ziehbaren Element, mit createItem, das sie dafür braucht. Elemente ihrer Gruppe, die aus einem anderen Fenster der App hereingezogen werden (native), brauchen keine der beiden Optionen: Sie kommen als sie selbst hinein. Ein Wert, ein Ref oder ein Getter, live gelesen.

dropOutside?
DropOutsideWert · Ref · Getter

Ein Drop außerhalb aller Ziele: die Elemente dort behalten, wo der Platzhalter ist, abbrechen oder sie entfernen. Standard 'placeholder' ('cancel' mit placeholder: 'indicator'). Wird beim Drop gelesen.

animation?
LayoutAnimationWert · Ref

FLIP-Animation dieser Liste; Standard: animation des Providers. Ein Wert oder ein Ref (eine Funktion ist eine eigene Animation).

animateChanges?
AutoAnimationWert · Ref · Getter

Animiert Änderungen von items, die kein Drag ausgelöst hat: hinzugefügte, entfernte, verschobene und gefilterte Elemente (siehe AutoAnimation). Standard: animateChanges des Providers, aus, sofern dort nicht gesetzt. Wird gelesen, wenn sich items ändert.

animateSize?
booleanWert · Ref · Getter

Die eigene Größe der Liste folgt ihren Elementen: Wenn ein Drag ein Element hereinbringt oder herausnimmt (und beim Drop und bei den Änderungen, die animateChanges zeigt), wächst oder schrumpft sie mit Dauer und Easing von animation auf ihre neue Größe, statt zu springen, und was um sie herum ist, bewegt sich mit. Standard true; false lässt sie springen. Wird bei jeder Änderung gelesen.

autoScroll?
boolean | AutoScrollOptionsWert · Ref · Getter

Überschreibt autoScroll des Providers für den Scroll-Container dieser Liste. Wird beim Start des Drags gelesen.

dropzone?
MaybeElementRef

Das Element, das Drops für die Liste annimmt, standardmäßig das Listenelement selbst: z. B. die ganze Spalte um eine kurze Liste von Karten, sodass eine Karte, die unterhalb der letzten losgelassen wird, trotzdem in der Liste landet (an ihrem Ende). Die Elemente bleiben im Listenelement.

disabled?
booleanWert · Ref · Getter

true: Ihre Elemente können nicht gezogen werden, und sie nimmt keine Elemente an.

onBeforeDrop?
( event: SortableDropEvent<T>, ) => MaybePromise<BeforeDropResult>

Wird vor einem Drop in diese Liste gefragt und bevor dropOutside: 'remove' ihre Elemente herausnimmt: false lehnt ihn ab (die Elemente fliegen zurück), einige Schlüssel nehmen nur diese an. Darf asynchron sein: Das Overlay wartet dort, wo es abgelegt wurde. Auch ein Fehler lehnt den Drop ab. Siehe SortableDropEvent für result und preventDefault.

onDrop?
(event: SortableDropEvent<T>) => void

Wird aufgerufen, sobald ein Drop in diese Liste angenommen ist, bevor er geschrieben wird: items enthält noch die alte Reihenfolge, event.result die neue. Synchron: Das Schreiben folgt, sobald es zurückkehrt, sofern es nicht event.preventDefault() aufgerufen hat. Wird auch für die Liste aufgerufen, aus der die Elemente kamen, wenn sie entfernt werden (to.index ist -1).

Rückgabe

Was makeSortableList zurückgibt.

id
Key

Die ID der Liste: die Option id oder die dafür erzeugte.

items
ComputedRef<T[]>

Entwurfsreihenfolge: Rendere das, nicht das Quell-Array.

isOver
ComputedRef<boolean>

Ein Drag ist über der Liste.

isAccepting
ComputedRef<boolean>

Etwas wird gezogen, und diese Liste nimmt es an.

indicator
ComputedRef<SortableIndicator | null>

Indikator-Modus: wohin der Drop in dieser Liste geht; null, wenn nicht hier.

activeKey
ComputedRef<Key | null>

Die Zeile, die ein Virtualizer gemountet halten muss: der Slot, solange er in dieser Liste ist (eine Kopie, ein erstelltes Element), sonst das gezogene Element; null ohne Drag.

activeIndex
ComputedRef<number>

Index des aktiven Elements im Entwurf dieser Liste, -1, wenn es nicht hier ist.

activeSize
ComputedRef<Size | null>

Größe des gezogenen Elements beim Start des Drags: z. B. für die Größe einer virtuellen Zeile, die es hält.

captureLayout
() => void

Animiert Layoutänderungen, die nicht die Bibliothek verursacht hat (z. B. ein erneutes Messen durch einen Virtualizer).

Gruppen

Die Gruppe einer Liste: die Listen, die Elemente austauschen, und ob Elemente diese verlassen und in sie kommen dürfen.

name
string

Listen und Bäume mit demselben Namen tauschen Elemente aus.

pull?
boolean | 'clone'

Ob Elemente diese Liste verlassen können: verschieben, kopieren ('clone', eine Palette) oder gar nicht.

put?
boolean | string | string[] | ((context: SortablePutContext<T>) => boolean)

Ob Elemente in diese Liste kommen können: true (Standard), false, ein Typ oder Typen, die die Elemente haben müssen (wie das accept eines Drop-Ziels: mit acceptMode alle oder einige), oder eine Funktion des Drags.

Womit ein group.put in Form einer Funktion aufgerufen wird: die Elemente, die in die Liste kämen.

keys
Key[]

Schlüssel der Elemente.

items
T[]

Die Elemente (bei einem einfachen ziehbaren Element das, das createItem erzeugt hat).

types
string[]

Die Typen der Elemente, zusammen.

from
Key | null

Quellliste, null für externe ziehbare Elemente.

to
Key

ID der gefragten Liste.

Das Drop-Event

Was onBeforeDrop und onDrop bekommen.

Ein Drop auf eine sortierbare Liste oder einen Baum. Seine Hooks laufen in dieser Reihenfolge: onBeforeDrop entscheidet, onDrop wird informiert, dann schreibt die Standardaktion result in die items jeder Liste, die darin genannt ist, und das Overlay landet. preventDefault() in einem der beiden Hooks überspringt dieses Schreiben, sodass du result selbst anwenden kannst.

keys
Key[]

Schlüssel der gezogenen Elemente.

items
T[]

Die Elemente, die landen: die gezogenen, ihre Kopien (mode: 'copy') oder das Element, das createItem erzeugt hat ('insert').

accepted
Key[]

Schlüssel, die durchgehen: alle, sofern die Liste oder onBeforeDrop nicht nur einige annimmt.

rejected
Key[]

Schlüssel, die dorthin zurückfliegen, wo sie waren.

from
{ list: Key | null; index: number }

Wo der Drag begann: die Liste und der Index des aktiven Elements. list ist null bei einem einfachen ziehbaren Element von außen.

to
{ list: Key; index: number }

index ist -1, wenn nichts gelandet ist: Die Elemente haben ihre Listen verlassen (e.source.remove(), dropOutside: 'remove').

sameList
boolean

Der Drop bleibt in der Liste, in der der Drag begann.

mode
DragMode

Was der Drop bewirkt (siehe DragMode).

partner?
{ key: Key; item: T; from: { list: Key; index: number }; to: { list: Key; index: number } }

mode: 'swap': das Element, mit dem das gezogene getauscht wurde. Es hat sich in die Gegenrichtung bewegt, von from, dem Platz, den das gezogene Element eingenommen hat (to oben), nach to, dem Platz, an dem das gezogene Element begonnen hat (from oben); zwischen Listen in die Liste des gezogenen Elements.

result
ReadonlyMap<Key, T[]>

Die neuen Elemente jeder Liste, die der Drop ändert, nach Listen-ID: genau das, was das Standard-Schreiben in ihre items setzt, als neue Arrays. Verschiebungen, Kopien, erstellte Elemente, eine teilweise Annahme, beide Seiten eines Tauschs und entfernte Elemente (e.source.remove() in einem Ziel innerhalb eines Elements, eine Papierkorb-Zone, dropOutside: 'remove') sind alle darin enthalten; eine Liste, die der Drop unverändert lässt, nicht. Der Eintrag eines Baums ist ein neues Wurzel-Array: Die Knoten auf den geänderten Pfaden sind Kopien (withChildren), unberührte Teilbäume werden geteilt, deine Knoten werden nie mutiert. In onBeforeDrop ist es der Drop, wie er vor der Antwort des Hooks aussieht (einige Schlüssel zurückzugeben ändert ihn); onDrop bekommt den endgültigen.

preventDefault
() => void

Überspringt das Standard-Schreiben, in jede Liste in result (nur einige zu schreiben würde Elemente verlieren oder duplizieren). Wende result selbst in onDrop an oder bevor ein asynchrones onBeforeDrop aufgelöst wird, und das Overlay landet in der neuen Reihenfolge. Wird es nirgends angewendet, bleiben die Listen, wie sie waren, und das Overlay fliegt zurück (Kopien und erstellte Elemente, die noch keinen Platz haben, werden ausgeblendet).

defaultPrevented
boolean

preventDefault() wurde aufgerufen, in onBeforeDrop oder onDrop.

external?
ExternalData

Ein Drag von außerhalb der Seite (external): was er trug, mit seinen Daten (er wurde abgelegt).

Indikator

Was indicator im Modus placeholder: 'indicator' enthält.

Wohin der Drop mit placeholder: 'indicator' geht: Die Liste bewegt sich nicht, du zeichnest die Linie.

list
Key

ID der Liste (oder des Baums), in die der Drop geht.

index
number

Einfügeposition in der Liste, wie sie gerendert ist.

key
Key | null

Element, an dem der Indikator hängt; null in einer leeren Liste.

side
'before' | 'after' | 'inside' | 'swap'

Seite von key, an der die Linie erscheint. 'inside' (Bäume): Der Zeiger ist über der Mitte einer Zeile, die die gezogenen Knoten aufnimmt; der Drop geht als ihr erstes Kind hinein. 'swap' (behavior: 'swap'): key ist das Element, mit dem der Drop tauscht; markiere das Element selbst.

depth?
number

Bäume: Tiefe, die die abgelegten Knoten bekommen (Wurzeln sind 0), z. B. um die Linie einzurücken.

parentKey?
Key | null

Bäume: Elternknoten, den die abgelegten Knoten bekommen, null auf der Wurzelebene.

Werte

Eine Quelle sortierbarer Elemente. Ein beschreibbares Ref: Die Bibliothek schreibt jeden Drop hinein. Eine schreibgeschützte Quelle (ein Getter, ein readonly Ref, ein computed: ein unveränderlicher Store, Server-State, ein Store, der nur über Actions geändert wird): Du wendest jeden Drop aus event.result an, nach event.preventDefault() (siehe SortableDropEvent).

type SortableItems = Ref<T[]> | Readonly<Ref<readonly T[]>> | (() => readonly T[])

Wie eine Liste ihre Elemente anordnet: als Spalte ('vertical'), als Zeile ('horizontal') oder als umbrechendes Raster ('grid').

type SortableStrategy = 'vertical' | 'horizontal' | 'grid'

Was das Hovern über einem Element bewirkt: 'sort' macht Platz (die Elemente dazwischen verschieben sich), 'swap' tauscht die beiden Elemente.

type SortableBehavior = 'sort' | 'swap'

Wie ein Drag zeigt, wohin er geht: 'item', der Slot des gezogenen Elements wandert durch die Liste; 'indicator', die Liste bleibt, wie sie ist, und indicator sagt, wohin der Drop geht (du zeichnest die Linie).

type SortablePlaceholder = 'item' | 'indicator'

Was die anderen ausgewählten Elemente bei einem Multi-Drag tun:

  • 'group': Sie verlassen ihre Plätze und begleiten das aktive Element als zusammenhängende Platzhalter, sodass die Liste schon beim Hovern das Ergebnis des Drops zeigt;
  • 'gaps': Sie bleiben bis zum Drop an ihrem Platz;
  • 'stack': Sie fallen im Overlay zusammen.

Das Standard-Overlay zeigt die gezogenen Elemente in einer Spalte entlang der Liste ('group', 'gaps'; eine Zeile in horizontalen Listen, ein Stapel hinter dem aktiven Element in Rastern) oder das aktive Element mit einer Anzahl ('stack').

type MultipleMode = 'group' | 'gaps' | 'stack'

Was ein Drop außerhalb aller Ziele bewirkt: 'placeholder' behält die Elemente dort, wo ihr Slot ist, 'cancel' schickt sie zurück, 'remove' nimmt sie aus ihrer Liste.

type DropOutside = 'placeholder' | 'cancel' | 'remove'