Documentación/API

makeSortableTree

Convierte un contenedor en un árbol ordenable, renderizado en plano con profundidades — anidamiento arrastrando hacia un lado o pasando sobre un nodo.

Editar esta página

Esta página la ha traducido una IA y puede contener imprecisiones. Leer el original en inglés

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

Convierte un contenedor en un árbol ordenable. Renderiza los items devueltos (los nodos visibles en el orden del borrador, con sangría según depth) con un componente de fila que llame a makeSortableItem. Al soltar, después de onDrop, los nodos movidos (con sus subárboles) se escriben en options.items, salvo que event.preventDefault() te deje event.result a ti.

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

Cada fila llama a makeSortableItem con id: () => node.key. Consulta Árboles.

Live Cambia una opción y luego arrastra una fila hacia un lado

Cargando la demo…

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

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

Opciones

Opciones de makeSortableTree. Un multi-drag mueve los nodos seleccionados como un solo bloque, cada uno con su subárbol, a un mismo sitio y profundidad (en el orden del documento); un nodo seleccionado dentro de otro seleccionado viaja dentro de su subárbol. Eso vale también para el nodo agarrado (como en VS Code): se queda dentro del nodo seleccionado en el que está, que se mueve con su subárbol, mientras el overlay se queda en la fila agarrada. canNest y maxDepth se aplican a todo el bloque.

Las demás opciones significan lo mismo que en makeSortableList. Aceptan un valor, una ref o un getter (overlay, overOverlay, animation, dropAnimation, overDropAnimation: un valor o una ref) y se leen cuando el árbol las necesita, así que un cambio se aplica, como muy tarde, en el siguiente arrastre. Excepciones: id y group se leen una sola vez, al crear el árbol; items es el propio modelo; las funciones (getKey, getChildren, setChildren, canNest, clone, createItem, los callbacks) se pasan tal cual.

items

SortableItems<T>

Los nodos raíz. Una ref escribible: al soltar, la biblioteca da a los nodos modificados sus nuevos hijos (setChildren) y escribe un nuevo array de raíces. Una fuente de solo lectura (un getter, una ref readonly, un computed): llama a event.preventDefault() y aplica event.result tú mismo (como en SortableListOptions.items).

getKey?

(node: T) => Key

Por defecto: node.id. También da la clave de makeSortableItem({ item }), de las copias y de los nodos creados.

getChildren?

(node: T) => T[]

Los hijos de un nodo. Por defecto: node.children.

setChildren?

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

Cómo da la escritura por defecto sus nuevos hijos a un nodo. Por defecto: node.children = children.

withChildren?

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

Una copia de node con children, para event.result: un árbol nuevo que deja tus nodos como están (la escritura por defecto sigue pasando por setChildren). Por defecto: { ...node } con los hijos asignados mediante setChildren ({ ...node, children } sin setChildren). Pásala para instancias de clases y para nodos que necesiten algo más que una copia superficial.

id?

Key

Por defecto: useId(), estable entre el renderizado en el servidor y en el cliente. Se lee una vez.

label?

stringvalor · ref · getter

El nombre que la gente le da al árbol: los textos para lectores de pantalla lo dicen en lugar de su id.

data?

unknownvalor · ref · getter

Cualquier cosa que contar sobre el árbol como destino de drop: los eventos lo llevan como over.data mientras un arrastre está sobre él.

activation?

ActivationOptionsvalor · ref · getter

Cómo una pulsación sobre las filas de este árbol inicia un arrastre, en lugar de la activation del provider (la propia de una fila tiene prioridad).

overlay?

Componentvalor · ref

Componente de overlay para las filas de este árbol (el overlay propio de una fila tiene prioridad). Una ref cambiada a mitad del arrastre lo cambia al instante.

overOverlay?

Componentvalor · ref

Lo que muestra el overlay mientras un arrastre que este árbol acepta está sobre él (consulta SortableListOptions.overOverlay). Su prop to dice dónde se anidaría el drop.

dropAnimation?

DropAnimationvalor · ref

Cómo aterriza el overlay cuando termina un arrastre de las filas de este árbol (consulta SortableListOptions.dropAnimation).

overDropAnimation?

DropAnimationvalor · ref

Cómo aterriza el overlay cuando se suelta en este árbol (consulta SortableListOptions.overDropAnimation).

modifiers?

Modifier[]valor · ref · getter

Modificadores para los arrastres de las filas de este árbol, aplicados después de los modifiers del provider (los modifiers propios de una fila tienen prioridad): por ejemplo [restrictToVerticalAxis]. Se leen cuando empieza el arrastre. Con un eje bloqueado se sigue anidando: la profundidad sale entonces de pasar sobre el centro de una fila.

axis?

'x' | 'y'valor · ref · getter

Bloquea en un eje los arrastres de las filas de este árbol (el axis propio de una fila tiene prioridad), después de los modificadores. Con 'y' las filas se siguen anidando: la profundidad sale entonces de pasar sobre el centro de una fila. Se lee cuando empieza el arrastre.

group?

string | SortableGroupOptions<T>

Las listas y los árboles con el mismo nombre de grupo intercambian ítems. Por defecto: un grupo propio. Se lee una vez.

acceptMode?

AcceptModevalor · ref · getter

Multi-drag de ítems de varios tipos: deben aceptarse 'all' (por defecto) o 'some' (group.put).

indentation?

numbervalor · ref · getter

Píxeles de desplazamiento horizontal por nivel de profundidad. 24 por defecto.

nesting?

TreeNestingvalor · ref · getter

Cómo se elige la profundidad: desplazamiento horizontal, pasar sobre el centro de una fila, o ambos (por defecto).

placeholder?

SortablePlaceholdervalor · ref · getter

'item' (por defecto): el nodo arrastrado se mueve entre las filas a su profundidad proyectada. 'indicator': el árbol no se mueve; indicator (en el árbol y en el makeSortableItem de cada fila) indica adónde va el drop, con su depth y su parentKey, y la línea la dibujas tú. Soltar fuera, en ese caso, cancela.

maxDepth?

numbervalor · ref · getter

La profundidad máxima permitida (las raíces son 0). Los descendientes de los nodos arrastrados cuentan.

canNest?

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

Si node puede ir bajo parent; un multi-drag pregunta por cada nodo arrastrado.

collapsed?

ReadonlySet<Key>valor · ref · getter

Claves de los nodos cuyos hijos están ocultos.

clone?

(node: T) => T

Crea copias (group.pull: 'clone', la tecla modificadora de copia). Necesaria para copiar. Devuelve la copia con todo su subárbol: una carpeta copiada conserva sus hijos. La copia y cada uno de sus descendientes necesitan claves propias (que se leen con getKey), como todo nodo de un árbol.

createItem?

(active: Active) => T

Acepta elementos arrastrables simples de fuera: crea el nodo que se va a insertar, en la posición y la profundidad proyectadas (se le aplican canNest y maxDepth). Con el teclado, una flecha hacia el árbol mete en él el elemento arrastrable, al nivel de la fila delante de la que va, y luego las flechas mueven el nodo como a cualquier otro. Con un arrastre desde fuera de la página (external), se le pregunta dos veces, mientras se mantiene y al soltar (consulta el createItem de la lista); un nodo carpeta con un hijo por archivo admite varios archivos.

external?

ExternalAcceptvalor · ref · getter

Acepta arrastres desde fuera de la página: archivos, enlaces, texto (consulta ExternalAccept), con createItem. Los nodos de su grupo arrastrados desde otra ventana de la app entran tal cual. Un valor, una ref o un getter, que se lee en vivo.

dropOutside?

DropOutsidevalor · ref · getter

Un drop fuera de todo destino: dejar los nodos donde está el placeholder, cancelar o quitarlos. 'placeholder' por defecto ('cancel' con placeholder: 'indicator'). Se lee al soltar.

animation?

LayoutAnimationvalor · ref

Animación FLIP de este árbol; por defecto, la animation del provider. Un valor o una ref (una función es una animación personalizada).

animateChanges?

AutoAnimationvalor · ref · getter

Como en SortableListOptions, para las filas visibles: nodos añadidos, quitados o movidos, y las filas que un nodo muestra u oculta al expandirse o plegarse (collapsed).

animateSize?

booleanvalor · ref · getter

El tamaño propio del árbol sigue a sus filas, como el de una lista (animateSize). Por defecto true.

autoScroll?

boolean | AutoScrollOptionsvalor · ref · getter

Sustituye el autoScroll del provider para el contenedor desplazable de este árbol. Se lee cuando empieza el arrastre.

dropzone?

MaybeElementRef

Como en SortableListOptions: el elemento que recibe los drops del árbol, por defecto el propio del árbol.

disabled?

booleanvalor · ref · getter

true: sus filas no se pueden arrastrar y no acepta ítems.

onBeforeDrop?

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

Como en SortableListOptions.

onDrop?

(event: SortableTreeDropEvent<T>) => void

Como en SortableListOptions: antes de la escritura, que event.preventDefault() omite.

Valor devuelto

Lo que devuelve makeSortableTree.

Key

El id del árbol: la opción id o el que se creó para él.

items

ComputedRef<FlatNode<T>[]>

Los nodos visibles en el orden del borrador; el nodo activo lleva su profundidad proyectada.

projected

ComputedRef<TreeProjection | null>

Dónde aterrizaría el nodo activo, null cuando no está en este árbol.

indicator

ComputedRef<SortableIndicator | null>

Modo indicador: adónde va el drop, con su depth y su parentKey; null cuando no es aquí.

isOver

ComputedRef<boolean>

Hay un arrastre sobre el árbol.

isAccepting

ComputedRef<boolean>

Se está arrastrando algo y este árbol lo acepta.

activeKey

ComputedRef<Key | null>

La fila que un virtualizador debe mantener montada: el hueco mientras está en este árbol (el nodo arrastrado, el nodo seleccionado dentro del que viaja el agarrado, una copia, un nodo creado) y, si no, el nodo arrastrado.

activeIndex

ComputedRef<number>

Índice de activeKey en items, -1 cuando no está aquí.

activeSize

ComputedRef<Size | null>

Tamaño de la fila arrastrada al inicio del arrastre.

captureLayout

() => void

Anima los cambios de layout que no causó la biblioteca (por ejemplo, una nueva medición de un virtualizador).

Nodos planos

Un nodo visible de un árbol, tal como los lista items del árbol: renderízalos en orden, con sangría según depth.

key

Key

La clave del nodo (getKey).

item

T

Tu nodo.

depth

number

Su profundidad: las raíces son 0. El nodo arrastrado tiene su profundidad proyectada.

parentKey

Key | null

Clave de su padre; null para una raíz.

index

number

Índice entre sus hermanos.

hasChildren

boolean

Tiene hijos, mostrados o no.

collapsed

boolean

Sus hijos están ocultos (su clave está en collapsed).

Proyección

Dónde aterrizaría el nodo arrastrado en un árbol.

depth

number

La profundidad que tendría (las raíces son 0).

parentKey

Key | null

El nodo bajo el que iría; null en la raíz.

Cómo elige su profundidad un arrastre en un árbol: 'offset', según cuánto se desplaza de lado (indentation por nivel); 'hover', pasando por encima del centro de una fila, que lo toma como hijo; 'both'.

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

El evento de drop

Evento de drop de un árbol. index es la posición entre los hermanos bajo parentKey (from: antes del movimiento; to: después, con el nodo ya quitado de su sitio anterior). from.parentKey es null para los nodos raíz y para los ítems que vienen de otra lista. Un multi-drag mueve las keys (cada una con su subárbol) una junto a otra: from es donde estaba el nodo que guía el arrastre (el agarrado, o el nodo seleccionado dentro del que viaja), to donde aterriza el primero de ellos. Una copia (mode: 'copy') deja los nodos donde están e inserta items, sus copias; un elemento arrastrable simple (mode: 'insert'), el nodo que creó createItem.

from

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

Dónde estaba el nodo que encabeza el arrastre: su árbol, su índice entre sus hermanos, su padre.

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

Dónde aterriza el primer nodo soltado: su árbol, su índice entre sus nuevos hermanos, su nuevo padre.