vue-dnd-kit

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

makeDraggable

Делает элемент перетаскиваемым — свободно или в цели, которые его принимают.

Редактировать страницу

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

function makeDraggable<TData = unknown>(  target: MaybeElementRef,  options?: DraggableOptions<TData>,): DraggableReturn;

Делает элемент перетаскиваемым. По умолчанию — свободное перетаскивание; сортируемые списки построены поверх него.

const el = useTemplateRef<HTMLElement>('el');
const { isDragging } = makeDraggable(el, { id: 'card', type: 'card', data: { title } });

См. drag and drop. Элементы сортируемых списков — тоже перетаскиваемые элементы: makeSortableItem принимает те же опции и не только.

Live

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

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

<template>
  <!-- No drop target here: let go, and each card goes back where it was. -->
  <DnDProvider>
    <div class="cards">
      <DragCard title="Grab it anywhere" code="makeDraggable(el)" />
      <DragCard title="Grab the handle" code="{ handle: grip }" handle />
      <DragCard title="It moves itself" code="{ overlay: false }" self />
      <DragCard title="Not now" code="{ disabled: true }" disabled />
    </div>
  </DnDProvider>
</template>

<style scoped>
.cards {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 220px));
  gap: 14px;
}

@media (max-width: 480px) {
  .cards {
    grid-template-columns: minmax(0, 1fr);
  }
}
</style>

Опции

Опции makeDraggable. Каждая опция, кроме canDrag, принимает значение, ref или геттер (overlay, dropAnimation — значение или ref) и читается, когда она нужна, поэтому изменение вступает в силу не позже следующего драга.

id?
Keyзначение · ref · геттер

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

data?
TDataзначение · ref · геттер

Всё, что должен нести драг: события и цели читают это как active.data.

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

Название для людей: тексты для скринридеров называют его вместо id (Picked up Tomato). События передают его как active.label и в items.

type?
string | string[]значение · ref · геттер

Его тип или типы, которые сверяются с правилами accept целей. Без типа он подходит к любой цели.

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

true: его нельзя перетащить (он сообщает aria-disabled).

handle?
MaybeElement | stringзначение · ref · геттер

Элемент или селектор внутри перетаскиваемого элемента, который начинает драг (и получает атрибуты).

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

Переопределяет activation провайдера. Читается в начале нажатия.

canDrag?
(event: PointerEvent | KeyboardEvent) => boolean

Дополнительное условие, например перетаскивать только при зажатой клавише.

overlay?
boolean | Componentзначение · ref

true (по умолчанию): за указателем следует оверлей — его рендерит слот #overlay провайдера или клон элемента. Компонент: оверлей рендерит его с OverlayProps, в приоритете перед слотом. false: оверлея нет, сам элемент движется через возвращённый transform. Значение или ref (функция — это функциональный компонент, так что (props) => <Card {...props} /> работает). Есть ли оверлей, решается в начале драга; ref, переключённый посреди драга, сразу меняет компонент (см. overlayTransition провайдера). overOverlay цели важнее, пока драг над ней. В клон не попадают эффекты нажатия UI-китов (ripple) и любые элементы внутри с пометкой data-dnd-no-clone.

dropAnimation?
DropAnimationзначение · ref

Как приземляется оверлей, когда заканчивается драг этого элемента, вместо dropAnimation провайдера; overDropAnimation цели важнее. Значение или ref (функция — это анимация), читается при броске.

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

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

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

Фиксирует драги, которые начинаются здесь, по одной оси: 'x' — только по горизонтали, 'y' — только по вертикали. Фиксация идёт после modifiers (последним — restrictToHorizontalAxis / restrictToVerticalAxis), поэтому держится, что бы они ни делали. Читается в начале драга.

keyboardMode?
'pixels' | 'droppables'значение · ref · геттер

Стрелки при свободном перетаскивании: сдвиг на пиксели (по умолчанию) или прыжки между целями, которые принимают драг. Читается при каждом нажатии стрелки.

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

Выставлять атрибуты role/tabindex/aria-* (по умолчанию true), никогда не перезаписывая ваши собственные. Id инструкций провайдера добавляется к существующему aria-describedby ещё одним токеном (тултип UI-кита на том же элементе сохраняет свой), и удаляется только этот токен. Работает на лету: при выключении убирается то, что выставила библиотека.

native?
boolean | NativeDragOptionsзначение · ref · геттер

Драг мышью — это собственный драг браузера, который может покинуть страницу: на рабочий стол, в другое приложение или вкладку, в другое окно приложения. На странице он работает как обычно (цели, списки, которые освобождают место), но вместо оверлея перетаскиваемое изображение рисует браузер. Драги касанием и с клавиатуры остаются драгами библиотеки. true несёт label как текст. Читается в начале нажатия. canDrag спрашивается при нажатии; насколько должна сдвинуться мышь, прежде чем начнётся драг, решает браузер (activation к нему не применяется).

Возвращает

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

id
ComputedRef<Key>

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

isDragging
ComputedRef<boolean>

Его перетаскивают (в том числе как ещё один элемент мульти-драга), или его оверлей ещё приземляется.

transform
ComputedRef<Coordinates | null>

Смещение, которое нужно применить при overlay: false: смещение драга за вычетом того, насколько с начала сдвинулось содержимое, в котором находится элемент (прокрутилась страница или контейнер), так что элемент остаётся под указателем.

selected
WritableComputedRef<boolean>

Он в выделении провайдера: драг одного выделенного элемента несёт их все. Присвойте значение, чтобы выделить или снять выделение.

За пределы страницы

Что драг native несёт за пределы страницы. См. файлы и другие приложения.

Перетаскиваемый элемент или элемент сортируемого списка, который мышью можно вытащить за пределы страницы (native): на рабочий стол, в другое приложение, в другую вкладку, в другое окно приложения.

data?
(active: Active) => Record<string, string>

Что получают другие приложения и страницы: текст по MIME-типу, в виде { 'text/plain': title, 'text/uri-list': url }. Читается в начале драга. Элементы сортируемых списков несут ещё и самих себя — для списков своей группы в другом окне приложения.

effect?
'copy' | 'move' | 'link' | 'copyMove' | 'copyLink' | 'linkMove' | 'all'

Что драг разрешает сделать месту, куда его бросили (effectAllowed). По умолчанию 'copyMove': перемещение забирает элементы из их списка здесь, копирование оставляет их.