Документация/API

makeSortableTree

Делает контейнер сортируемым деревом, отрисованным плоско с глубинами, — вложение сдвигом вбок или наведением на узел.

Страница переведена ИИ и может содержать неточности. Читать английский оригинал

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

Делает контейнер сортируемым деревом. Рендерите возвращённый items (видимые узлы в порядке черновика, с отступом по depth) компонентом строки, который вызывает makeSortableItem. При броске, после onDrop, перемещённые узлы (со своими поддеревьями) записываются в options.items, если только event.preventDefault() не оставляет event.result вам.

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

Каждая строка вызывает makeSortableItem с id: () => node.key. См. деревья.

Live Переключите опцию, затем перетащите строку вбок

Загружаем демо…

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

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

Опции

Опции makeSortableTree. Мульти-драг перемещает выделенные узлы одним блоком, каждый со своим поддеревом, в одно место и на одну глубину (в порядке документа); выделенный узел внутри другого выделенного едет в его поддереве. Это касается и взятого узла (как в VS Code): он остаётся внутри выделенного узла, в котором находится, и тот перемещается со своим поддеревом, а оверлей остаётся на взятой строке. canNest и maxDepth применяются ко всему блоку.

Остальные опции значат то же, что в makeSortableList. Они принимают значение, ref или геттер (overlay, overOverlay, animation, dropAnimation, overDropAnimation — значение или ref) и читаются, когда они нужны дереву, поэтому изменение вступает в силу не позже следующего драга. Исключения: id и group читаются один раз, при создании дерева; items — это сама модель; функции (getKey, getChildren, setChildren, canNest, clone, createItem, колбэки) передаются как есть.

items

SortableItems<T>

Корневые узлы. Записываемый ref: при броске библиотека даёт изменённым узлам новых потомков (setChildren) и записывает новый массив корней. Источник только для чтения (геттер, readonly ref, computed): вызовите event.preventDefault() и примените event.result сами (как в SortableListOptions.items).

getKey?

(node: T) => Key

По умолчанию — node.id. Также задаёт ключи для makeSortableItem({ item }), копий и созданных узлов.

getChildren?

(node: T) => T[]

Потомки узла. По умолчанию — node.children.

setChildren?

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

Как запись по умолчанию даёт узлу новых потомков. По умолчанию — node.children = children.

withChildren?

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

Копия node с children для event.result: новое дерево, которое оставляет ваши узлы как есть (запись по умолчанию всё равно идёт через setChildren). По умолчанию — { ...node }, которому потомки переданы через setChildren ({ ...node, children }, если setChildren нет). Передавайте её для экземпляров классов и узлов, которым мало поверхностной копии.

id?

Key

По умолчанию — useId(), совпадает при рендере на сервере и на клиенте. Читается один раз.

label?

stringзначение · ref · геттер

Название дерева для людей: тексты для скринридеров называют его вместо id.

data?

unknownзначение · ref · геттер

Любые сведения о дереве как о цели: события передают их как over.data, пока над ним драг.

activation?

ActivationOptionsзначение · ref · геттер

Как нажатие на строки этого дерева начинает драг, вместо activation провайдера (собственная опция строки важнее).

overlay?

Componentзначение · ref

Компонент оверлея для строк этого дерева (собственный overlay строки важнее). Ref, переключённый посреди драга, сразу его меняет.

overOverlay?

Componentзначение · ref

Что показывает оверлей, пока над этим деревом драг, который оно принимает (см. SortableListOptions.overOverlay). Его проп to говорит, куда вложился бы бросок.

dropAnimation?

DropAnimationзначение · ref

Как приземляется оверлей, когда заканчивается драг строк этого дерева (см. SortableListOptions.dropAnimation).

overDropAnimation?

DropAnimationзначение · ref

Как приземляется оверлей, когда его бросают в это дерево (см. SortableListOptions.overDropAnimation).

modifiers?

Modifier[]значение · ref · геттер

Модификаторы для драгов строк этого дерева; применяются после modifiers провайдера (собственные modifiers строки важнее). Например, [restrictToVerticalAxis]. Читается в начале драга. С зафиксированной осью вложение всё равно работает: глубина тогда задаётся наведением на середину строки.

axis?

'x' | 'y'значение · ref · геттер

Фиксирует драги строк этого дерева по одной оси (собственный axis строки важнее), после модификаторов. С 'y' строки всё равно вкладываются: глубина тогда задаётся наведением на середину строки. Читается в начале драга.

group?

string | SortableGroupOptions<T>

Списки и деревья с одинаковым именем группы обмениваются элементами. По умолчанию — своя отдельная группа. Читается один раз.

acceptMode?

AcceptModeзначение · ref · геттер

Мульти-драг элементов нескольких типов: принять (group.put) нужно все элементы ('all', по умолчанию) или некоторые ('some').

indentation?

numberзначение · ref · геттер

Горизонтальное смещение в пикселях на один уровень глубины. По умолчанию 24.

nesting?

TreeNestingзначение · ref · геттер

Как выбирается глубина: горизонтальным смещением, наведением на середину строки или и тем и другим (по умолчанию).

placeholder?

SortablePlaceholderзначение · ref · геттер

'item' (по умолчанию): перетаскиваемый узел движется между строками на своей расчётной глубине. 'indicator': дерево не двигается; indicator (у дерева и у makeSortableItem каждой строки) показывает, куда пойдёт бросок, с его depth и parentKey, а линию рисуете вы. Бросок снаружи тогда отменяет драг.

maxDepth?

numberзначение · ref · геттер

Максимально допустимая глубина (у корней 0). Собственные потомки перетаскиваемых узлов учитываются.

canNest?

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

Можно ли поместить node под parent; при мульти-драге вызывается для каждого перетаскиваемого узла.

collapsed?

ReadonlySet<Key>значение · ref · геттер

Ключи узлов, чьи потомки скрыты.

clone?

(node: T) => T

Создаёт копии (group.pull: 'clone', клавиша-модификатор копирования). Обязательна для копирования. Возвращайте копию со всем поддеревом: скопированная папка сохраняет своих потомков. Копии и каждому её потомку нужны собственные ключи (читаются через getKey), как и любому узлу дерева.

createItem?

(active: Active) => T

Принимает обычные перетаскиваемые элементы извне: создаёт узел для вставки в расчётную позицию и на расчётную глубину (к нему применяются canNest и maxDepth). С клавиатуры стрелка в сторону дерева забирает перетаскиваемый элемент на уровень строки, перед которой он встаёт, и дальше стрелки двигают узел, как любой другой. Для драга извне страницы (external) её спрашивают дважды — пока драг удерживают и при броске (см. createItem списка); узел-папка с потомком на каждый файл вмещает несколько файлов.

external?

ExternalAcceptзначение · ref · геттер

Принимает драги извне страницы: файлы, ссылки, текст (см. ExternalAccept), с createItem. Узлы его группы, перетащенные из другого окна приложения, попадают в дерево как есть. Значение, ref или геттер, читается вживую.

dropOutside?

DropOutsideзначение · ref · геттер

Бросок вне всех целей: оставить узлы там, где плейсхолдер, отменить или удалить их. По умолчанию 'placeholder' ('cancel' при placeholder: 'indicator'). Читается при броске.

animation?

LayoutAnimationзначение · ref

FLIP-анимация этого дерева; по умолчанию — animation провайдера. Значение или ref (функция — это своя анимация).

animateChanges?

AutoAnimationзначение · ref · геттер

Как в SortableListOptions, для видимых строк: добавленные, удалённые или перемещённые узлы, а также строки, которые узел показывает или скрывает, когда раскрывается или сворачивается (collapsed).

animateSize?

booleanзначение · ref · геттер

Собственный размер дерева следует за его строками, как у списка (animateSize). По умолчанию true.

autoScroll?

boolean | AutoScrollOptionsзначение · ref · геттер

Переопределяет autoScroll провайдера для скролл-контейнера этого дерева. Читается в начале драга.

dropzone?

MaybeElementRef

Как в SortableListOptions: элемент, который принимает броски для дерева; по умолчанию — собственный элемент дерева.

disabled?

booleanзначение · ref · геттер

true: его строки нельзя перетащить, и оно не принимает элементы.

onBeforeDrop?

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

Как в SortableListOptions.

onDrop?

(event: SortableTreeDropEvent<T>) => void

Как в SortableListOptions: до записи, которую пропускает event.preventDefault().

Возвращает

Что возвращает makeSortableTree.

Key

Id дерева: опция id или созданный для него id.

items

ComputedRef<FlatNode<T>[]>

Видимые узлы в порядке черновика; у активного узла — его расчётная глубина.

projected

ComputedRef<TreeProjection | null>

Куда приземлился бы активный узел; null, если его нет в этом дереве.

indicator

ComputedRef<SortableIndicator | null>

Режим индикатора: куда пойдёт бросок, с его depth и parentKey; null, если не здесь.

isOver

ComputedRef<boolean>

Над деревом драг.

isAccepting

ComputedRef<boolean>

Что-то перетаскивается, и это дерево это принимает.

activeKey

ComputedRef<Key | null>

Строка, которую виртуализатор должен держать смонтированной: слот, пока он в этом дереве (перетаскиваемый узел, выделенный узел, внутри которого едет взятый, копия, созданный узел), иначе — перетаскиваемый узел.

activeIndex

ComputedRef<number>

Индекс activeKey в items; -1, если его здесь нет.

activeSize

ComputedRef<Size | null>

Размер перетаскиваемой строки в начале драга.

captureLayout

() => void

Анимирует изменения раскладки, которые вызвала не библиотека (например, повторный замер виртуализатора).

Плоские узлы

Видимый узел дерева — в том виде, в каком их перечисляет items дерева: рендерите их по порядку, с отступом по depth.

key

Key

Ключ узла (getKey).

item

T

Ваш узел.

depth

number

Его глубина: у корней 0. У перетаскиваемого узла — его расчётная глубина.

parentKey

Key | null

Ключ его родителя; null для корня.

index

number

Индекс среди соседних узлов.

hasChildren

boolean

У него есть потомки, показанные или нет.

collapsed

boolean

Его потомки скрыты (его ключ есть в collapsed).

Проекция

Куда приземлился бы перетаскиваемый узел в дереве.

depth

number

Глубина, которую он получил бы (у корней 0).

parentKey

Key | null

Узел, под который он попал бы; null в корне.

Как драг в дереве выбирает глубину: 'offset' — по тому, насколько он сдвинут вбок (indentation на уровень); 'hover' — наведением на середину строки, которая принимает его как потомка; 'both'.

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

Событие броска

Событие броска в дереве. index — позиция среди соседних узлов под parentKey (from — до перемещения; to — после него, когда узел уже убран со старого места). from.parentKey равен null для корневых узлов и для элементов из другого списка. Мульти-драг перемещает keys (каждый со своим поддеревом) рядом друг с другом: from — где был узел, ведущий драг (взятый или выделенный узел, внутри которого он едет), to — куда приземляется первый из них. Копирование (mode: 'copy') оставляет узлы на местах и вставляет items — их копии; обычный перетаскиваемый элемент (mode: 'insert') — узел, созданный createItem.

from

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

Где был узел, ведущий драг: его дерево, его индекс среди соседних узлов, его родитель.

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

Куда приземляется первый брошенный узел: его дерево, его индекс среди новых соседних узлов, его новый родитель.