Documentation/API

makeSortableTree

Fait d'un conteneur un arbre triable, rendu à plat avec des profondeurs — imbrication en glissant de côté ou en survolant un nœud.

Modifier cette page

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

function makeSortableTree<T>(  target: MaybeElementRef,  options: SortableTreeOptions<T>,): SortableTreeReturn<T>;

Fait d'un conteneur un arbre triable. Rendez les items renvoyés (les nœuds visibles dans l'ordre du brouillon, indentés selon depth) avec un composant de ligne qui appelle makeSortableItem. Au dépôt, après onDrop, les nœuds déplacés (avec leurs sous-arbres) sont écrits dans options.items, sauf si event.preventDefault() vous laisse event.result.

const root = useTemplateRef<HTMLElement>('root');
const { items } = makeSortableTree(root, { items: files, indentation: 20, collapsed });

Chaque ligne appelle makeSortableItem avec id: () => node.key. Voir Arbres.

Live Changez une option, puis faites glisser une ligne de côté

Chargement de la démo…

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

<template>
  <DnDProvider>
    <FileTree />
  </DnDProvider>
</template>

Options

Options de makeSortableTree. Un multi-drag déplace les nœuds sélectionnés en un seul bloc, chacun avec son sous-arbre, vers une même place et une même profondeur (dans l'ordre du document) ; un nœud sélectionné à l'intérieur d'un autre nœud sélectionné suit dans son sous-arbre. Cela vaut aussi pour le nœud saisi (comme dans VS Code) : il reste à l'intérieur du nœud sélectionné qui le contient, lequel se déplace avec son sous-arbre, tandis que l'overlay reste sur la ligne saisie. canNest et maxDepth s'appliquent à tout le bloc.

Les autres options signifient la même chose que dans makeSortableList. Elles acceptent une valeur, une ref ou un getter (overlay, overOverlay, animation, dropAnimation, overDropAnimation : une valeur ou une ref) et sont lues quand l'arbre 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 l'arbre ; items est le modèle lui-même ; les fonctions (getKey, getChildren, setChildren, canNest, clone, createItem, les callbacks) sont passées telles quelles.

items

SortableItems<T>

Les nœuds racines. Une ref modifiable : au dépôt, la bibliothèque donne aux nœuds modifiés leurs nouveaux enfants (setChildren) et écrit un nouveau tableau de racines. Une source en lecture seule (un getter, une ref readonly, un computed) : appelez event.preventDefault() et appliquez event.result vous-même (comme pour SortableListOptions.items).

getKey?

(node: T) => Key

Par défaut : node.id. Sert aussi de clé à makeSortableItem({ item }), aux copies et aux nœuds créés.

getChildren?

(node: T) => T[]

Les enfants d'un nœud. Par défaut : node.children.

setChildren?

(node: T, children: T[]) => void

Comment l'écriture par défaut donne à un nœud ses nouveaux enfants. Par défaut : node.children = children.

withChildren?

(node: T, children: T[]) => T

Une copie de node avec children, pour event.result : un nouvel arbre qui laisse vos nœuds tels quels (l'écriture par défaut passe toujours par setChildren). Par défaut : { ...node } auquel les enfants sont donnés via setChildren ({ ...node, children } sans setChildren). Passez-la pour des instances de classe et des nœuds qui demandent plus qu'une copie superficielle.

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 à l'arbre : les textes pour les lecteurs d'écran le disent à la place de son id.

data?

unknownvaleur · ref · getter

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

activation?

ActivationOptionsvaleur · ref · getter

Comment un appui sur les lignes de cet arbre lance un glissement, à la place de l'activation du provider (celle propre à une ligne l'emporte).

overlay?

Componentvaleur · ref

Composant d'overlay pour les lignes de cet arbre (l'overlay propre à une ligne l'emporte). Une ref changée en plein glissement le remplace aussitôt.

overOverlay?

Componentvaleur · ref

Ce que montre l'overlay pendant qu'un glissement que cet arbre accepte le survole (voir SortableListOptions.overOverlay). Sa prop to indique où le dépôt s'imbriquerait.

dropAnimation?

DropAnimationvaleur · ref

Comment l'overlay atterrit quand un glissement des lignes de cet arbre se termine (voir SortableListOptions.dropAnimation).

overDropAnimation?

DropAnimationvaleur · ref

Comment l'overlay atterrit quand il est déposé dans cet arbre (voir SortableListOptions.overDropAnimation).

modifiers?

Modifier[]valeur · ref · getter

Modificateurs des glissements des lignes de cet arbre, appliqués après les modifiers du provider (les modifiers propres à une ligne l'emportent) : par exemple [restrictToVerticalAxis]. Lus au début du glissement. Un axe verrouillé permet quand même l'imbrication : la profondeur vient alors du survol du milieu d'une ligne.

axis?

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

Verrouille sur un axe les glissements des lignes de cet arbre (l'axis propre à une ligne l'emporte), après les modificateurs. Avec 'y', les lignes s'imbriquent quand même : la profondeur vient alors du survol du milieu d'une ligne. Lu au début du glissement.

group?

string | SortableGroupOptions<T>

Les listes et les arbres qui ont le même nom de groupe s'échangent des items. Par défaut : un groupe à lui seul. 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).

indentation?

numbervaleur · ref · getter

Pixels de décalage horizontal par niveau de profondeur. 24 par défaut.

nesting?

TreeNestingvaleur · ref · getter

Comment la profondeur est choisie : décalage horizontal, survol du milieu d'une ligne, ou les deux (par défaut).

placeholder?

SortablePlaceholdervaleur · ref · getter

'item' (par défaut) : le nœud glissé se déplace parmi les lignes à sa profondeur projetée. 'indicator' : l'arbre ne bouge pas ; indicator (sur l'arbre et sur le makeSortableItem de chaque ligne) indique où va le dépôt, avec sa depth et son parentKey, et c'est vous qui dessinez la ligne. Un dépôt à l'extérieur annule alors le glissement.

maxDepth?

numbervaleur · ref · getter

Profondeur maximale autorisée (les racines sont à 0). Les descendants des nœuds glissés comptent.

canNest?

(node: T, parent: T) => boolean

Si node peut aller sous parent ; un multi-drag pose la question pour chaque nœud glissé.

collapsed?

ReadonlySet<Key>valeur · ref · getter

Clés des nœuds dont les enfants sont masqués.

clone?

(node: T) => T

Crée des copies (group.pull: 'clone', la touche modificatrice de copie). Obligatoire pour copier. Renvoyez la copie avec tout son sous-arbre : un dossier copié garde ses enfants. La copie et chacun de ses descendants ont besoin de leurs propres clés (lues avec getKey), comme chaque nœud d'un arbre.

createItem?

(active: Active) => T

Accepte des éléments déplaçables simples venus de l'extérieur : crée le nœud à insérer, à la position et à la profondeur projetées (canNest et maxDepth s'y appliquent). Au clavier, une flèche en direction de l'arbre y fait entrer l'élément déplaçable, au niveau de la ligne devant laquelle il va, et les flèches déplacent ensuite le nœud 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 et au dépôt (voir le createItem de la liste) ; un nœud dossier avec un enfant par fichier contient plusieurs fichiers.

external?

ExternalAcceptvaleur · ref · getter

Accepte les glissements venus de l'extérieur de la page : fichiers, liens, texte (voir ExternalAccept), avec createItem. Les nœuds de son groupe glissés depuis une autre fenêtre de l'application 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 nœuds 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 cet arbre ; par défaut : l'animation du provider. Une valeur ou une ref (une fonction est une animation personnalisée).

animateChanges?

AutoAnimationvaleur · ref · getter

Comme dans SortableListOptions, pour les lignes visibles : nœuds ajoutés, retirés ou déplacés, et lignes qu'un nœud affiche ou masque quand il se déplie ou se replie (collapsed).

animateSize?

booleanvaleur · ref · getter

La taille de l'arbre lui-même suit ses lignes, comme celle d'une liste (animateSize). true par défaut.

autoScroll?

boolean | AutoScrollOptionsvaleur · ref · getter

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

dropzone?

MaybeElementRef

Comme dans SortableListOptions : l'élément qui reçoit les dépôts pour l'arbre, par défaut celui de l'arbre lui-même.

disabled?

booleanvaleur · ref · getter

true : ses lignes ne peuvent pas être glissées, et il n'accepte aucun item.

onBeforeDrop?

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

Comme dans SortableListOptions.

onDrop?

(event: SortableTreeDropEvent<T>) => void

Comme dans SortableListOptions : avant l'écriture, que event.preventDefault() empêche.

Valeur de retour

Ce que renvoie makeSortableTree.

Key

L'id de l'arbre : l'option id, ou celui créé pour lui.

items

ComputedRef<FlatNode<T>[]>

Les nœuds visibles dans l'ordre du brouillon ; le nœud actif porte sa profondeur projetée.

projected

ComputedRef<TreeProjection | null>

Où atterrirait le nœud actif, null quand il n'est pas dans cet arbre.

indicator

ComputedRef<SortableIndicator | null>

Mode indicateur : où va le dépôt, avec sa depth et son parentKey ; null quand ce n'est pas dans cet arbre.

isOver

ComputedRef<boolean>

Un glissement survole l'arbre.

isAccepting

ComputedRef<boolean>

Quelque chose est en cours de glissement et cet arbre l'accepte.

activeKey

ComputedRef<Key | null>

La ligne qu'un virtualiseur doit garder montée : l'emplacement tant qu'il est dans cet arbre (le nœud glissé, le nœud sélectionné dans lequel le nœud saisi est emporté, une copie, un nœud créé), sinon le nœud glissé.

activeIndex

ComputedRef<number>

Index d'activeKey dans items, -1 quand il n'y est pas.

activeSize

ComputedRef<Size | null>

Taille de la ligne glissée au début du glissement.

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

Nœuds plats

Un nœud visible d'un arbre, tel que les liste l'items de l'arbre : rendez-les dans l'ordre, indentés selon depth.

key

Key

La clé du nœud (getKey).

item

T

Votre nœud.

depth

number

Sa profondeur : les racines sont à 0. Le nœud glissé a sa profondeur projetée.

parentKey

Key | null

Clé de son parent ; null pour une racine.

index

number

Index parmi les frères.

hasChildren

boolean

Il a des enfants, affichés ou non.

collapsed

boolean

Ses enfants sont masqués (sa clé est dans collapsed).

Projection

Où le nœud glissé atterrirait dans un arbre.

depth

number

La profondeur qu'il aurait (les racines sont à 0).

parentKey

Key | null

Le nœud sous lequel il irait ; null à la racine.

Comment un glissement dans un arbre choisit sa profondeur : 'offset', selon son déplacement latéral (indentation par niveau) ; 'hover', en survolant le milieu d'une ligne, qui le prend comme enfant ; 'both'.

type TreeNesting = 'offset' | 'hover' | 'both'

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

Événement de dépôt d'un arbre. index est la position parmi les frères sous parentKey (from : avant le déplacement ; to : après, le nœud étant déjà retiré de son ancienne place). from.parentKey vaut null pour les nœuds racines et pour les items venant d'une autre liste. Un multi-drag déplace les keys (chacune avec son sous-arbre) côte à côte : from est l'endroit où se trouvait le nœud qui mène le glissement (celui qui a été saisi, ou le nœud sélectionné dans lequel il est emporté), to l'endroit où atterrit le premier d'entre eux. Une copie (mode: 'copy') laisse les nœuds là où ils sont et insère items, leurs copies ; un élément déplaçable simple (mode: 'insert'), le nœud créé par createItem.

from

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

Où était le nœud qui mène le glissement : son arbre, son index parmi ses frères, son parent.

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

Où atterrit le premier nœud déposé : son arbre, son index parmi ses nouveaux frères, son nouveau parent.