Documentation/API

makeSortableList

Fait d'un conteneur une liste triable — un brouillon qui se réordonne pendant le glissement et qui est réécrit au dépôt.

Modifier cette page

Cette page a été traduite par IA et peut contenir des inexactitudes. Lire l'original en anglais

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

Fait d'un conteneur une liste triable. Rendez les items renvoyés (l'ordre du brouillon), pas votre tableau : le dépôt est réécrit dans options.items, après onDrop, sauf si event.preventDefault() vous laisse event.result.

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

Ses lignes appellent makeSortableItem. Voir Listes triables et Listes qui partagent des items.

Live Changez les options, puis faites glisser une tuile

Chargement de la démo…

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

Options

Options de makeSortableList. Un composant peut créer plusieurs listes (et arbres) : chaque item rendu dedans rejoint la plus intérieure dont l'élément le contient.

Les options acceptent une valeur, une ref ou un getter (overlay, overOverlay, dropAnimation, overDropAnimation, animation : une valeur ou une ref) et sont lues quand la liste en a besoin : un changement s'applique donc au plus tard au glissement suivant. Exceptions : id et group sont lus une seule fois, à la création de la liste ; items est le modèle lui-même ; les fonctions (getKey, filter, clone, createItem, les callbacks) sont passées telles quelles.

items

SortableItems<T>

La source de vérité. Une ref modifiable reçoit le nouveau tableau au dépôt, juste après onDrop. Une source en lecture seule (un getter, une ref readonly, un computed) ne le peut pas : appelez event.preventDefault() et appliquez event.result vous-même. Les builds de développement signalent un dépôt laissé à la bibliothèque dans ce cas, qui ne change alors rien.

getKey?

(item: T) => Key

Par défaut : item.id, ou l'item lui-même pour les primitives. Sert aussi de clé à makeSortableItem({ item }).

filter?

(item: T) => boolean

N'affiche que les items pour lesquels elle renvoie true (une recherche, une étiquette) : items (celui qui est renvoyé) les contient, et un glissement trie parmi eux. Les autres gardent leur place dans la source : un dépôt écrit le tableau entier, chaque item masqué toujours après l'item affiché qu'il suivait (après le plus proche resté en place, quand celui-là a bougé). Réactive : ce qu'elle lit (une ref de recherche) s'applique aussitôt. e.to.index et activeIndex comptent les items affichés.

id?

Key

Par défaut : useId(), stable entre le rendu serveur et le rendu client. Lu une seule fois.

label?

stringvaleur · ref · getter

Le nom que les gens donnent à la liste : les textes pour les lecteurs d'écran le disent à la place de son id (position 2 of 5 in Garden).

data?

unknownvaleur · ref · getter

Tout ce qu'il y a à dire sur la liste en tant que cible de dépôt : les événements le transportent dans over.data tant qu'un glissement la survole.

activation?

ActivationOptionsvaleur · ref · getter

Comment un appui sur les items de cette liste lance un glissement, à la place de l'activation du provider (celle propre à un item l'emporte). Lue au début d'un appui.

overlay?

Componentvaleur · ref

Composant d'overlay pour les items de cette liste (l'overlay propre à un item l'emporte). Il reçoit OverlayProps et est conservé pendant tout le glissement, y compris au-dessus d'autres listes, sauf si la cible sous le glissement a son propre overlay (overOverlay). Une ref changée en plein glissement le remplace aussitôt.

overOverlay?

Componentvaleur · ref

Ce que montre l'overlay pendant qu'un glissement que cette liste accepte la survole, quelle que soit la liste d'où il vient : un composant qui reçoit OverlayProps et l'overlay propre au glissement comme slot par défaut (voir DroppableOptions.overOverlay). Lu en direct.

dropAnimation?

DropAnimationvaleur · ref

Comment l'overlay atterrit quand un glissement des items de cette liste se termine, à la place de la dropAnimation du provider (celle propre à un item l'emporte ; celle d'une cible de dépôt l'emporte sur les deux). Lu au dépôt.

overDropAnimation?

DropAnimationvaleur · ref

Comment l'overlay atterrit quand il est déposé dans cette liste, quelle que soit la liste d'où il vient : l'emporte sur la dropAnimation de l'item glissé et sur celle du provider. Lu au dépôt.

modifiers?

Modifier[]valeur · ref · getter

Modificateurs des glissements des items de cette liste, appliqués après les modifiers du provider (les modifiers propres à un item l'emportent) : par exemple [restrictToVerticalAxis] pour garder les items d'une liste verticale sur leur axe. Lus au début du glissement.

axis?

'x' | 'y'valeur · ref · getter

Verrouille sur un axe les glissements des items de cette liste : 'y' pour une liste verticale, 'x' pour une liste horizontale (l'axis propre à un item l'emporte). Le verrouillage vient après les modificateurs : il tient donc quoi qu'ils fassent. Lu au début du glissement.

group?

string | SortableGroupOptions<T>

Les listes qui ont le même nom de groupe s'échangent des items. Par défaut : un groupe à elle seule. Lu une seule fois.

acceptMode?

AcceptModevaleur · ref · getter

Multi-drag d'items de plusieurs types : 'all' (par défaut) ou 'some' doivent être acceptés (group.put).

strategy?

SortableStrategyvaleur · ref · getter

'vertical' par défaut.

behavior?

SortableBehaviorvaleur · ref · getter

'swap' : l'item glissé échange sa place avec l'item survolé, en direct ; revenir sur lui ou sortir des listes annule l'échange. Les listes d'un même groupe qui font toutes deux des échanges s'échangent des items : l'item survolé prend la place de l'item glissé, il doit donc pouvoir quitter sa liste (group.pull: true) et entrer dans celle de l'item glissé (group.put). Un multi-drag trie à la place. 'sort' par défaut.

placeholder?

SortablePlaceholdervaleur · ref · getter

'indicator' : la liste ne bouge pas, indicator indique où va le dépôt. 'item' par défaut.

multiple?

MultipleModevaleur · ref · getter

Mode multi-drag des glissements qui commencent dans cette liste. 'group' par défaut. Lu au début du glissement.

sort?

booleanvaleur · ref · getter

false : les items ne peuvent pas être réordonnés dans cette liste (palettes).

clone?

(item: T) => T

Crée des copies (pull: 'clone', touche modificatrice de copie). Obligatoire pour copier.

createItem?

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

Accepte des éléments déplaçables simples venus de l'extérieur : crée l'item à insérer. Au clavier, une flèche en direction de la liste y fait entrer l'élément déplaçable (à sa hauteur, comme pour les déplacements entre listes), et l'item créé se déplace ensuite par emplacements comme n'importe quel autre.

Pour un glissement venu de l'extérieur de la page (external), elle est appelée deux fois : pendant le glissement, pour l'item qui montre où il va (seuls active.external.fileTypes et types sont connus à ce moment-là), et au dépôt, avec ses données (active.external.ready), pour ce qui est inséré. Un tableau d'items est inséré en entier là où était l'emplacement : un item par fichier.

external?

ExternalAcceptvaleur · ref · getter

Accepte les glissements venus de l'extérieur de la page : fichiers, liens, texte (voir ExternalAccept). La liste leur fait de la place comme à un élément déplaçable simple, avec createItem, dont elle a besoin. Les items de son groupe glissés depuis une autre fenêtre de l'application (native) n'ont besoin d'aucune des deux options : ils entrent tels quels. Une valeur, une ref ou un getter, lu en direct.

dropOutside?

DropOutsidevaleur · ref · getter

Un dépôt hors de toute cible : garder les items là où se trouve le placeholder, annuler, ou les retirer. 'placeholder' par défaut ('cancel' avec placeholder: 'indicator'). Lu au dépôt.

animation?

LayoutAnimationvaleur · ref

Animation FLIP de cette liste ; par défaut : l'animation du provider. Une valeur ou une ref (une fonction est une animation personnalisée).

animateChanges?

AutoAnimationvaleur · ref · getter

Anime les changements de items qui ne viennent pas d'un glissement : items ajoutés, retirés, déplacés et filtrés (voir AutoAnimation). Par défaut : l'animateChanges du provider, désactivé sauf s'il y est défini. Lu quand items change.

animateSize?

booleanvaleur · ref · getter

La taille de la liste elle-même suit ses items : quand un glissement fait entrer ou sortir un item (et au dépôt, et pour les changements que montre animateChanges), elle grandit ou rétrécit jusqu'à sa nouvelle taille avec la durée et l'easing d'animation au lieu de sauter, et ce qui l'entoure suit le mouvement. true par défaut ; false la laisse sauter. Lue à chaque changement.

autoScroll?

boolean | AutoScrollOptionsvaleur · ref · getter

Remplace l'autoScroll du provider pour le conteneur défilant de cette liste. Lu au début du glissement.

dropzone?

MaybeElementRef

L'élément qui reçoit les dépôts pour la liste, par défaut l'élément de la liste lui-même : par exemple toute la colonne autour d'une courte liste de cartes, pour qu'une carte lâchée sous la dernière atterrisse quand même dans la liste (à la fin). Les items restent dans l'élément de la liste.

disabled?

booleanvaleur · ref · getter

true : ses items ne peuvent pas être glissés, et elle n'accepte aucun item.

onBeforeDrop?

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

Consulté avant un dépôt dans cette liste, et avant que dropOutside: 'remove' n'en retire les items : false le refuse (les items reviennent à leur place), des clés n'acceptent que ces items. Peut être asynchrone : l'overlay attend là où il a été déposé. Une erreur refuse aussi le dépôt. Voir SortableDropEvent pour result et preventDefault.

onDrop?

(event: SortableDropEvent<T>) => void

Appelé une fois qu'un dépôt dans cette liste est accepté, avant qu'il ne soit écrit : items contient encore l'ancien ordre, event.result le nouveau. Synchrone : l'écriture suit dès qu'il retourne, sauf s'il a appelé event.preventDefault(). Appelé aussi sur la liste d'où viennent les items quand ils sont retirés (to.index vaut -1).

Valeur de retour

Ce que renvoie makeSortableList.

Key

L'id de la liste : l'option id, ou celui créé pour elle.

items

ComputedRef<T[]>

L'ordre du brouillon : rendez-le, et non le tableau source.

isOver

ComputedRef<boolean>

Un glissement survole la liste.

isAccepting

ComputedRef<boolean>

Quelque chose est en cours de glissement et cette liste l'accepte.

indicator

ComputedRef<SortableIndicator | null>

Mode indicateur : où va le dépôt dans cette liste ; null quand ce n'est pas ici.

activeKey

ComputedRef<Key | null>

La ligne qu'un virtualiseur doit garder montée : l'emplacement tant qu'il est dans cette liste (une copie, un item créé), sinon l'item glissé ; null sans glissement.

activeIndex

ComputedRef<number>

Index de l'item actif dans le brouillon de cette liste, -1 quand il n'y est pas.

activeSize

ComputedRef<Size | null>

Taille de l'item glissé au début du glissement : par exemple pour la taille d'une ligne virtuelle qu'il occupe.

captureLayout

() => void

Anime les changements de mise en page que la bibliothèque n'a pas causés (par exemple une nouvelle mesure d'un virtualiseur).

Groupes

Le groupe d'une liste : les listes qui échangent des items, et si des items peuvent quitter celle-ci et y entrer.

name

string

Les listes et les arbres de même nom échangent des items.

pull?

boolean | 'clone'

Si les items peuvent quitter cette liste : déplacement, copie ('clone', une palette) ou pas du tout.

put?

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

Si les items peuvent entrer dans cette liste : true (par défaut), false, un ou plusieurs types que les items doivent avoir (comme l'accept d'une cible de dépôt : avec acceptMode, tous ou certains), ou une fonction du glissement.

Ce avec quoi un group.put sous forme de fonction est appelé : les items qui entreraient dans la liste.

keys

Key[]

Clés des items.

items

T[]

Les items (pour un simple élément déplaçable, l'item créé par createItem).

types

string[]

Les types des items, réunis.

from

Key | null

Liste source, null pour les éléments déplaçables externes.

Key

Id de la liste interrogée.

L'événement de dépôt

Ce que reçoivent onBeforeDrop et onDrop.

Un dépôt sur une liste ou un arbre triable. Ses hooks s'exécutent dans l'ordre : onBeforeDrop décide, onDrop est prévenu, puis l'action par défaut écrit result dans les items de chaque liste qu'il nomme, et l'overlay atterrit. preventDefault() dans l'un ou l'autre hook empêche cette écriture, pour que vous puissiez appliquer result vous-même.

keys

Key[]

Clés des items glissés.

items

T[]

Les items qui atterrissent : ceux qui sont glissés, leurs copies (mode: 'copy'), ou l'item créé par createItem ('insert').

accepted

Key[]

Les clés qui passent : toutes, sauf si la liste ou onBeforeDrop n'en accepte qu'une partie.

rejected

Key[]

Les clés qui reviennent là où elles étaient.

from

{ list: Key | null; index: number }

Où le glissement a commencé : la liste et l'index de l'item actif. list vaut null pour un simple élément déplaçable venu de l'extérieur.

{ list: Key; index: number }

index vaut -1 quand rien n'a atterri : les items ont quitté leurs listes (e.source.remove(), dropOutside: 'remove').

sameList

boolean

Le dépôt reste dans la liste où le glissement a commencé.

mode

DragMode

Ce que fait le dépôt (voir DragMode).

partner?

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

mode: 'swap' : l'item avec lequel l'item glissé a été échangé. Il s'est déplacé en sens inverse : from, la place prise par l'item glissé (to ci-dessus), et to, celle où l'item glissé a commencé (from ci-dessus) ; entre deux listes, vers la liste de l'item glissé.

result

ReadonlyMap<Key, T[]>

Les nouveaux items de chaque liste modifiée par le dépôt, par id de liste : exactement ce que l'écriture par défaut place dans leurs items, sous forme de nouveaux tableaux. Les déplacements, les copies, les items créés, une acceptation partielle, les deux côtés d'un échange et les items retirés (e.source.remove() dans une cible à l'intérieur d'un item, une zone de corbeille, dropOutside: 'remove') y figurent tous ; une liste que le dépôt laisse telle quelle n'y figure pas. L'entrée d'un arbre est un nouveau tableau de racines : les nœuds sur les chemins modifiés sont des copies (withChildren), les sous-arbres intacts sont partagés, vos nœuds ne sont jamais mutés. Dans onBeforeDrop, c'est le dépôt tel qu'il se présente avant la réponse du hook (renvoyer certaines clés le modifie) ; onDrop reçoit la version finale.

preventDefault

() => void

Empêche l'écriture par défaut, dans toutes les listes de result (n'en écrire qu'une partie perdrait ou dupliquerait des items). Appliquez result vous-même dans onDrop, ou avant qu'un onBeforeDrop asynchrone ne se résolve, et l'overlay atterrit dans le nouvel ordre. S'il n'est appliqué nulle part, les listes restent telles qu'elles étaient et l'overlay revient à sa place (les copies et les items créés, qui n'ont pas encore de place, disparaissent en fondu).

defaultPrevented

boolean

preventDefault() a été appelé, dans onBeforeDrop ou dans onDrop.

external?

ExternalData

Un glissement venu de l'extérieur de la page (external) : ce qu'il transportait, avec ses données (il a été déposé).

Indicateur

Ce que contient indicator en mode placeholder: 'indicator'.

Où va le dépôt avec placeholder: 'indicator' : la liste ne bouge pas, vous dessinez la ligne.

list

Key

Id de la liste (ou de l'arbre) où va le dépôt.

index

number

Position d'insertion dans la liste telle qu'elle est rendue.

key

Key | null

Item auquel l'indicateur est rattaché ; null dans une liste vide.

side

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

Côté de key où va la ligne. 'inside' (arbres) : le milieu d'une ligne qui accepte les nœuds glissés est survolé, et le dépôt va à l'intérieur, comme son premier enfant. 'swap' (behavior: 'swap') : key est l'item avec lequel le dépôt fait l'échange ; marquez l'item lui-même.

depth?

number

Arbres : profondeur que reçoivent les nœuds déposés (les racines sont à 0), par exemple pour indenter la ligne.

parentKey?

Key | null

Arbres : parent que reçoivent les nœuds déposés, null au niveau racine.

Valeurs

Une source d'items triables. Une ref modifiable : la bibliothèque y écrit chaque dépôt. Une source en lecture seule (un getter, une ref readonly, un computed : un store immuable, un état serveur, un store modifié uniquement via des actions) : c'est vous qui appliquez chaque dépôt depuis event.result, après event.preventDefault() (voir SortableDropEvent).

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

Comment une liste dispose ses items : en colonne ('vertical'), en ligne ('horizontal') ou en grille qui passe à la ligne ('grid').

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

Ce que fait le survol d'un item : 'sort' fait de la place (les items intermédiaires se décalent), 'swap' échange les deux items.

type SortableBehavior = 'sort' | 'swap'

Comment un glissement montre où il va : 'item', l'emplacement de l'item glissé se déplace dans la liste ; 'indicator', la liste reste telle quelle et indicator indique où va le dépôt (vous dessinez la ligne).

type SortablePlaceholder = 'item' | 'indicator'

Ce que font les autres items sélectionnés dans un multi-drag :

'group' : ils quittent leur place et voyagent avec l'item actif sous forme de placeholders contigus, si bien que, pendant le survol, la liste montre déjà le résultat du dépôt ;
'gaps' : ils restent en place jusqu'au dépôt ;
'stack' : ils se regroupent dans l'overlay.

L'overlay par défaut montre les items glissés en colonne dans le sens de la liste ('group', 'gaps' ; en rangée dans les listes horizontales, en pile derrière l'item actif dans les grilles), ou l'item actif avec un compteur ('stack').

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

Ce que fait un dépôt hors de toute cible : 'placeholder' garde les items là où se trouve leur emplacement, 'cancel' les renvoie, 'remove' les retire de leur liste.

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