文档/API

makeDraggable

让元素可拖拽——自由拖拽，或拖进接收它的放置目标。

本页由 AI 翻译，可能存在不准确之处。阅读英文原文

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 } });

参见拖放。可排序项也是可拖拽元素：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 或 getter（overlay、dropAnimation：值或 ref），并在需要时读取，所以变化最迟在下一次拖拽时生效。

id?

Key值 · ref · getter

稳定的 id。在元素会被回收的虚拟列表中，传入 getter。默认：useId()，在服务端和客户端渲染之间保持稳定，但每个组件实例都不同。

data?

TData值 · ref · getter

拖拽要携带的任何内容：事件和放置目标以 active.data 读取它。

label?

string值 · ref · getter

人们对它的称呼：屏幕阅读器文本会说出它，而不是 id（Picked up Tomato）。事件以 active.label 和在 items 中携带它。

type?

string | string[]值 · ref · getter

它的一个或多个类型，由放置目标的 accept 规则来匹配。没有类型时它适合任何目标。

disabled?

boolean值 · ref · getter

true：它不能被拖拽（会报告 aria-disabled）。

handle?

MaybeElement | string值 · ref · getter

可拖拽元素内部用于开始拖拽的元素或选择器（它也会得到相关属性）。

activation?

ActivationOptions值 · ref · getter

覆盖 provider 的 activation。在按下开始时读取。

canDrag?

(event: PointerEvent | KeyboardEvent) => boolean

额外的关卡，例如只在按住某个键时才能拖拽。

overlay?

boolean | Component值 · ref

true（默认）：浮层跟随指针，由 provider 的 #overlay 插槽渲染，或者是元素的克隆。组件：浮层以 OverlayProps 渲染它，优先于插槽。false：没有浮层，元素本身通过返回的 transform 移动。值或 ref（函数即函数式组件，所以 (props) => <Card {...props} /> 也可以）。是否有浮层在拖拽开始时决定；在拖拽过程中切换的 ref 会立即替换组件（见 provider 的 overlayTransition）。拖拽位于放置目标上方时，目标的 overOverlay 优先。克隆会排除 UI 库的按下效果（水波纹），以及内部任何标记了 data-dnd-no-clone 的元素。

dropAnimation?

DropAnimation值 · ref

这个元素的拖拽结束时浮层如何落位，替代 provider 的 dropAnimation；放置目标的 overDropAnimation 优先。值或 ref（函数即动画），在放置时读取。

modifiers?

Modifier[]值 · ref · getter

从这里开始的拖拽的修饰器，在 provider 的 modifiers 之后应用：例如在一个其他拖拽都可以自由移动的页面上，为某个元素设置 [restrictToVerticalAxis]。在拖拽开始时读取。

axis?

'x' | 'y'值 · ref · getter

把从这里开始的拖拽锁定在一个轴上：'x' 只水平移动，'y' 只垂直移动。锁定在 modifiers 之后执行（相当于把 restrictToHorizontalAxis / restrictToVerticalAxis 放在最后），所以无论修饰器做什么，锁定都成立。在拖拽开始时读取。

keyboardMode?

'pixels' | 'droppables'值 · ref · getter

自由拖拽中的方向键：按像素移动（默认），或在接收它的放置目标之间跳转。每次按下方向键时读取。

attributes?

boolean值 · ref · getter

设置 role/tabindex/aria-* 属性（默认 true），永远不会覆盖用户自己设置的。provider 的操作说明 id 会作为又一个 token 加入已有的 aria-describedby（同一元素上 UI 库的提示框会保留它自己的），并且只有这个 token 会被移除。实时生效：关闭后，库设置的属性会被移除。

native?

boolean | NativeDragOptions值 · ref · getter

用鼠标拖拽它就是浏览器自己的拖拽，可以离开页面：拖到桌面上，拖进另一个应用或标签页，拖进应用的另一个窗口。在页面上它照常工作（目标、腾出位置的列表），但拖拽的图像由浏览器绘制，代替浮层。触摸拖拽和键盘拖拽仍是本库的拖拽。true 把 label 作为文本携带。在按下开始时读取。canDrag 在按下时询问；鼠标移动多远后开始拖拽由浏览器决定（activation 对它不适用）。