快捷導(dǎo)航

Vue Draggable實(shí)現(xiàn)拖拽功能的操作方法

更新時(shí)間：2025年10月23日 10:00:48 作者：吃代碼長(zhǎng)大的前端

vuedraggable 是一個(gè)基于強(qiáng)大的 Sortable.js 庫(kù)的 Vue 組件,它允許你通過拖拽的方式對(duì)列表進(jìn)行排序、移動(dòng)、克隆等操作,并且與 Vue 的數(shù)據(jù)響應(yīng)式系統(tǒng)無縫集成,本文介紹Vue Draggable實(shí)現(xiàn)拖拽功能,感興趣的朋友跟隨小編一起看看吧

1. VueDraggable 的核心概念

數(shù)據(jù)驅(qū)動(dòng): 你只需要管理一個(gè)數(shù)組數(shù)據(jù)，vuedraggable 會(huì)自動(dòng)處理 DOM 的移動(dòng)和更新。
基于 Sortable.js: 它繼承了 Sortable.js 的所有強(qiáng)大功能和配置選項(xiàng)。
組件化: 以 Vue 組件的形式使用，非常易于集成。

2. 如何安裝和使用

A. 安裝

對(duì)于 Vue 3 (推薦)
你需要安裝 vuedraggable@next 版本。

npm install vuedraggable@next

對(duì)于 Vue 2
使用默認(rèn)版本即可。

npm install vuedraggable

本指南將主要以 Vue 3 的 vuedraggable@next 為例，因?yàn)樗砹宋磥淼姆较颉?/p>

B. 基本用法

下面是一個(gè)最簡(jiǎn)單的例子，展示了如何在一個(gè)列表中進(jìn)行拖拽排序。

<template>
  <div>
    <h3>可拖拽列表</h3>
    <draggable 
      v-model="myList" 
      item-key="id"
      @start="onStart"
      @end="onEnd"
    >
      <template #item="{element, index}">
        <div class="list-item">
          {{ element.name }} (ID: {{ element.id }}) - 索引: {{ index }}
        </div>
      </template>
    </draggable>
    <pre>{{ JSON.stringify(myList, null, 2) }}</pre>
  </div>
</template>
<script setup>
import { ref } from 'vue';
import draggable from 'vuedraggable';
const myList = ref([
  { id: 1, name: '蘋果' },
  { id: 2, name: '香蕉' },
  { id: 3, name: '橘子' },
  { id: 4, name: '葡萄' }
]);
const onStart = (event) => {
  console.log('拖拽開始', event);
};
const onEnd = (event) => {
  console.log('拖拽結(jié)束', event);
  // event.oldIndex - 拖拽前的位置
  // event.newIndex - 拖拽后的位置
  console.log(`從索引 ${event.oldIndex} 移動(dòng)到 ${event.newIndex}`);
};
</script>
<style scoped>
.list-item {
  padding: 10px;
  margin: 5px;
  background-color: #f0f0f0;
  border: 1px solid #ccc;
  cursor: grab;
}
.list-item:active {
  cursor: grabbing;
}
</style>

核心解釋:

import draggable from 'vuedraggable': 引入組件。
<draggable>: 這是 vuedraggable 的組件標(biāo)簽。
v-model="myList": 這是最關(guān)鍵的部分。它將組件與你的數(shù)據(jù)數(shù)組 myList 雙向綁定。當(dāng)你在界面上拖拽排序后，myList 數(shù)組的順序會(huì)自動(dòng)更新。
item-key="id": 極其重要！為了讓 Vue 能夠高效地跟蹤和復(fù)用每個(gè)列表項(xiàng)，你需要提供一個(gè)唯一的 key。它可以是一個(gè)字符串，指向你數(shù)組對(duì)象中唯一的屬性（如 id），或者是一個(gè)返回唯一值的函數(shù)。
#item="{element, index}": 這是默認(rèn)插槽的用法。vuedraggable 會(huì)遍歷你的 v-model 數(shù)組，并為每一項(xiàng)提供 element (當(dāng)前項(xiàng)的數(shù)據(jù)) 和 index (當(dāng)前項(xiàng)的索引) 作為插槽 prop，供你在模板中使用。

C. 兩個(gè)列表之間拖拽

這是另一個(gè)常見場(chǎng)景，例如從一個(gè)"待辦事項(xiàng)"列表拖到"已完成"列表。

<template>
  <div class="two-lists">
    <div>
      <h3>待辦事項(xiàng)</h3>
      <draggable
        v-model="list1"
        item-key="id"
        group="tasks"
        class="list-group"
      >
        <template #item="{element}">
          <div class="list-group-item">{{ element.name }}</div>
        </template>
      </draggable>
    </div>
    <div>
      <h3>已完成</h3>
      <draggable
        v-model="list2"
        item-key="id"
        group="tasks"
        class="list-group"
      >
        <template #item="{element}">
          <div class="list-group-item">{{ element.name }}</div>
        </template>
      </draggable>
    </div>
  </div>
</template>
<script setup>
import { ref } from 'vue';
import draggable from 'vuedraggable';
const list1 = ref([
  { id: 1, name: '寫代碼' },
  { id: 2, name: '測(cè)試功能' },
]);
const list2 = ref([
  { id: 3, name: '修復(fù)Bug' },
  { id: 4, name: '上線發(fā)布' },
]);
</script>
<style>
.two-lists { display: flex; gap: 20px; }
.list-group { min-height: 100px; background-color: #eee; padding: 10px; }
.list-group-item { padding: 10px; background-color: white; border: 1px solid #ddd; margin-bottom: 5px; cursor: grab; }
</style>

核心解釋:

group="tasks": 兩個(gè) draggable 組件設(shè)置了相同的 group 名稱。這告訴 vuedraggable，它們屬于同一個(gè)組，元素可以在它們之間相互拖拽。

3. 所有屬性 (Props)

vuedraggable 的屬性主要分為兩類：組件自身屬性和繼承自 Sortable.js 的選項(xiàng)。

A. 組件核心屬性

屬性名	類型	默認(rèn)值	描述
`v-model`	`Array`	`[]`	必需。用于雙向綁定的數(shù)據(jù)數(shù)組。當(dāng)拖拽操作完成時(shí)，此數(shù)組會(huì)自動(dòng)更新。
`item-key`	`String` \| `Function`	-	必需。用于 Vue diff 算法的唯一標(biāo)識(shí)。可以是對(duì)象中的屬性名（如 `'id'`）或一個(gè)返回唯一值的函數(shù) `(element) => element.id`。
`tag`	`String`	`'div'`	指定 `draggable` 組件渲染的根元素標(biāo)簽，例如 `'ul'`, `'tbody'` 等。
`componentData`	`Object`	`{}`	一個(gè)對(duì)象，用于向渲染的根元素（由 `tag` 決定）傳遞額外的 HTML 屬性，如 `class`, `style`, `id` 等。

B. 繼承自 Sortable.js 的選項(xiàng) (作為 Props 使用)

這些屬性直接控制拖拽的行為，非常強(qiáng)大。

屬性名	類型	默認(rèn)值	描述
`group`	`String` \| `Object`	`undefined`	用于在多個(gè)列表之間拖拽。設(shè)置為相同字符串名的列表可以互相拖拽。也可以是對(duì)象 `{ name: 'my-group', pull: true, put: true, pull: 'clone' }` 來進(jìn)行更精細(xì)的控制。
`sort`	`Boolean`	`true`	是否允許在列表內(nèi)部進(jìn)行排序。
`disabled`	`Boolean`	`false`	是否禁用整個(gè) `draggable` 組件。
`animation`	`Number`	`150`	拖拽動(dòng)畫的持續(xù)時(shí)間（毫秒）。設(shè)置為 `0` 則禁用動(dòng)畫。
`handle`	`String`	`undefined`	指定一個(gè) CSS 選擇器（如 `.drag-handle`），只有拖拽這個(gè)選擇器匹配的元素才能觸發(fā)拖拽。
`filter`	`String`	`undefined`	指定一個(gè) CSS 選擇器，該選擇器匹配的元素將不能被拖拽（例如，輸入框）。
`ghostClass`	`String`	`'sortable-ghost'`	拖拽時(shí)，元素在目標(biāo)位置的占位符的 CSS 類名。
`chosenClass`	`String`	`'sortable-chosen'`	拖拽時(shí)，被選中的源元素的 CSS 類名。
`dragClass`	`String`	`'sortable-drag'`	拖拽時(shí)，正在被拖拽的元素的克隆體的 CSS 類名。
`forceFallback`	`Boolean`	`false`	如果為 `true`，將強(qiáng)制使用 JS 來模擬拖拽效果（創(chuàng)建一個(gè)克隆元素），而不是使用原生的 HTML5 拖放 API。在某些復(fù)雜場(chǎng)景或 iframe 中可能需要。
`fallbackClass`	`String`	`'sortable-fallback'`	當(dāng) `forceFallback: true` 時(shí)，被拖拽的克隆元素的 CSS 類名。
`fallbackOnBody`	`Boolean`	`false`	當(dāng) `forceFallback: true` 時(shí)，是否將克隆元素附加到 `document.body`。
`delay`	`Number`	`0`	鼠標(biāo)按下后需要等待多少毫秒才能開始拖拽。
`delayOnTouchOnly`	`Boolean`	`false`	如果為 `true`，`delay` 選項(xiàng)僅在觸摸設(shè)備上生效。
`touchStartThreshold`	`Number`	`0`	觸摸設(shè)備上，手指需要移動(dòng)多少像素才能開始拖拽。
`swapThreshold`	`Number`	`1`	拖拽元素覆蓋目標(biāo)元素的百分比達(dá)到多少時(shí)才進(jìn)行交換（0 到 1）。
`invertSwap`	`Boolean`	`false`	如果為 `true`，當(dāng)拖拽元素中心越過目標(biāo)元素中心時(shí)才進(jìn)行交換。

4. 所有事件 (Events)

你可以通過 @event-name 的方式監(jiān)聽這些事件來執(zhí)行自定義邏輯。

事件名	載荷 (Payload)	描述
`start`	`(event)`	拖拽開始時(shí)觸發(fā)。`event` 包含 `oldIndex`。
`end`	`(event)`	拖拽結(jié)束時(shí)觸發(fā)。`event` 包含 `oldIndex`, `newIndex`。
`add`	`(event)`	當(dāng)元素從另一個(gè)列表拖拽進(jìn)來時(shí)，在新列表上觸發(fā)。`event` 包含 `newIndex`。
`remove`	`(event)`	當(dāng)元素被拖拽到另一個(gè)列表時(shí)，在舊列表上觸發(fā)。`event` 包含 `oldIndex`。
`update`	`(event)`	當(dāng)列表內(nèi)部排序發(fā)生變化時(shí)觸發(fā)。`event` 包含 `oldIndex`, `newIndex`。
`choose`	`(event)`	當(dāng)一個(gè)元素被選中時(shí)觸發(fā)。`event` 包含 `oldIndex`。
`unchoose`	`(event)`	當(dāng)一個(gè)元素被取消選中時(shí)觸發(fā)。`event` 包含 `oldIndex`。
`sort`	`(event)`	當(dāng)列表排序發(fā)生任何變化時(shí)觸發(fā)（包括 `add`, `remove`, `update`）。
`change`	`(event)`	這是一個(gè)更通用的事件，當(dāng)列表發(fā)生變化時(shí)觸發(fā)。`event` 對(duì)象包含 `added`、`removed` 或 `moved` 字段，描述了具體的變化。
`clone`	`(original)`	當(dāng)使用 `pull: 'clone'` 時(shí)，在克隆元素時(shí)觸發(fā)。`original` 是原始元素的數(shù)據(jù)。
`move`	`(event, originalEvent)`	拖拽過程中每次移動(dòng)都會(huì)觸發(fā)。可以通過返回 `false` 來取消本次移動(dòng)。

5. 所有插槽 (Slots)

插槽名	作用域變量 ({...})	描述
`item`	`{element, index}`	默認(rèn)插槽。用于渲染列表中的每一個(gè)可拖拽項(xiàng)。`element` 是當(dāng)前項(xiàng)的數(shù)據(jù)對(duì)象，`index` 是當(dāng)前項(xiàng)在數(shù)組中的索引。
`header`	-	在列表的開頭添加一個(gè)固定的、不可拖拽的區(qū)域。
`footer`	-	在列表的末尾添加一個(gè)固定的、不可拖拽的區(qū)域。

插槽示例

<draggable v-model="myList" item-key="id">
  <!-- 頭部插槽 -->
  <template #header>
    <div class="header">這是列表的頭部</div>
  </template>
  <!-- 默認(rèn)/item 插槽 -->
  <template #item="{element}">
    <div class="list-item">{{ element.name }}</div>
  </template>
  <!-- 尾部插槽 -->
  <template #footer>
    <div class="footer">這是列表的尾部</div>
  </template>
</draggable>

6. 方法 (Methods)

通常情況下，你不需要直接調(diào)用 vuedraggable 的方法，因?yàn)樗菙?shù)據(jù)驅(qū)動(dòng)的。但在某些特殊情況下，你可能需要通過 ref 訪問底層的 Sortable.js 實(shí)例。

給組件添加 ref:

<draggable ref="draggableRef" ...>

在 <script setup> 中定義 ref:

import { ref } from 'vue';
const draggableRef = ref(null);

訪問 Sortable.js 實(shí)例:
vuedraggable 將 Sortable.js 實(shí)例暴露在 sortable 屬性上。

const sortableInstance = draggableRef.value.sortable;

現(xiàn)在你可以調(diào)用 Sortable.js 的原生方法，例如：

sortableInstance.toArray(): 返回一個(gè)包含所有子元素 data-id 的數(shù)組。
sortableInstance.sort(orderArray): 根據(jù)提供的 ID 數(shù)組對(duì)列表進(jìn)行排序。
sortableInstance.destroy(): 銷毀 Sortable 實(shí)例。

注意: 直接操作 Sortable.js 實(shí)例可能會(huì)繞過 Vue 的響應(yīng)式系統(tǒng)，請(qǐng)謹(jǐn)慎使用。絕大多數(shù)場(chǎng)景都可以通過 props 和 events 來完成。

總結(jié)

vuedraggable 是一個(gè)功能強(qiáng)大且易于使用的庫(kù)。掌握它的關(guān)鍵在于：

v-model 和 item-key 是基礎(chǔ)，必須正確設(shè)置。
使用 group 屬性實(shí)現(xiàn)多列表交互。
通過 Props (如 animation, handle, ghostClass) 來定制拖拽行為和外觀。
監(jiān)聽 Events (如 end, add, change) 來在拖拽操作后執(zhí)行業(yè)務(wù)邏輯（例如，向服務(wù)器發(fā)送更新后的排序）。
利用 Slots (item, header, footer) 來靈活地定義列表結(jié)構(gòu)。