当前位置：首页 > article >正文

Vue拖拽组件：vue-draggable-plus

article 2025/9/14 11:28:30

vue-draggable-plus 学习文档

简介

vue-draggable-plus 是一个基于 Sortablejs 的 Vue 拖拽排序组件，专为 Vue 3 (>=v3) 或 Vue >=2.7 设计。该组件解决了官方 Sortablejs Vue 组件与 Vue 3 严重脱节的问题。

核心特性

🎯 多种使用方式：支持组件、函数、指令三种使用方式
🔧 灵活的容器选择：可以指定任意元素作为拖拽容器
📦 完美兼容：基于成熟的 Sortablejs 库
🎨 组件库友好：解决组件库中列表根元素插槽缺失的问题

解决的痛点

在传统的 Sortablejs Vue 组件中，必须使用组件作为列表的直接子元素。当使用第三方组件库时，如果组件库没有提供列表根元素的插槽，就很难实现拖拽功能。vue-draggable-plus 通过支持选择器指定目标容器完美解决了这个问题。

安装

npm install vue-draggable-plus

使用方式

1. 组件方式

最直观的使用方式，适合简单的拖拽列表场景。

<template><VueDraggable ref="el" v-model="list"><div v-for="item in list" :key="item.id">{{ item.name }}</div></VueDraggable>
</template><script setup lang="ts">
import { ref } from 'vue'
import { VueDraggable } from 'vue-draggable-plus'const list = ref([{ name: 'Joao', id: 1 },{ name: 'Jean', id: 2 },{ name: 'Johanna', id: 3 },{ name: 'Juan', id: 4 }
])
</script>

特点：

使用 v-model 双向绑定数据
组件自动处理拖拽逻辑
适合简单场景

2. 函数方式

提供更多控制权和灵活性，适合复杂的拖拽需求。

<template><div ref="el"><div v-for="item in list" :key="item.id">{{ item.name }}</div></div>
</template><script setup lang="ts">
import { ref } from 'vue'
import { useDraggable } from 'vue-draggable-plus'const el = ref()
const list = ref([{ name: 'Joao', id: 1 },{ name: 'Jean', id: 2 },{ name: 'Johanna', id: 3 },{ name: 'Juan', id: 4 }
])// 返回拖拽实例，包含 start、destroy、pause 等方法
const draggable = useDraggable(el, list, {animation: 150,onStart() {console.log('拖拽开始')},onUpdate() {console.log('列表更新')},onEnd() {console.log('拖拽结束')}
})
</script>

特点：

返回拖拽实例对象
可以手动控制拖拽行为
支持丰富的事件回调
适合复杂交互场景

3. 指令方式

最简洁的使用方式，适合快速集成。

<template><div v-draggable="[list, options]"><div v-for="item in list" :key="item.id">{{ item.name }}</div></div>
</template><script setup lang="ts">
import { ref } from 'vue'
import { vDraggable } from 'vue-draggable-plus'const list = ref([{ name: 'Joao', id: 1 },{ name: 'Jean', id: 2 },{ name: 'Johanna', id: 3 },{ name: 'Juan', id: 4 }
])const options = {animation: 150,onStart() {console.log('拖拽开始')},onUpdate() {console.log('列表更新')}
}
</script>

特点：

代码最简洁
直接在模板中配置
适合快速原型开发

常用配置选项

基础配置

const options = {// 动画时长（毫秒）animation: 150,// 拖拽时的 CSS 类名ghostClass: 'sortable-ghost',chosenClass: 'sortable-chosen',dragClass: 'sortable-drag',// 是否禁用拖拽disabled: false,// 拖拽手柄选择器handle: '.drag-handle',// 过滤不可拖拽的元素filter: '.no-drag',// 拖拽方向限制direction: 'vertical', // 'vertical' | 'horizontal'
}

事件回调

const options = {// 拖拽开始onStart(evt) {console.log('开始拖拽', evt)},// 拖拽结束onEnd(evt) {console.log('拖拽结束', evt)},// 元素位置改变onUpdate(evt) {console.log('位置更新', evt)},// 元素添加到列表onAdd(evt) {console.log('添加元素', evt)},// 元素从列表移除onRemove(evt) {console.log('移除元素', evt)},// 拖拽过程中onMove(evt) {console.log('移动中', evt)// 返回 false 可以阻止移动return true}
}

高级用法

1. 双列表拖拽

<template><div class="container"><div class="list-container"><h3>列表 A</h3><VueDraggable v-model="listA" group="shared"class="drag-area"><div v-for="item in listA" :key="item.id" class="drag-item">{{ item.name }}</div></VueDraggable></div><div class="list-container"><h3>列表 B</h3><VueDraggable v-model="listB" group="shared"class="drag-area"><div v-for="item in listB" :key="item.id" class="drag-item">{{ item.name }}</div></VueDraggable></div></div>
</template><script setup lang="ts">
import { ref } from 'vue'
import { VueDraggable } from 'vue-draggable-plus'const listA = ref([{ name: '项目 A1', id: 1 },{ name: '项目 A2', id: 2 }
])const listB = ref([{ name: '项目 B1', id: 3 },{ name: '项目 B2', id: 4 }
])
</script><style>
.container {display: flex;gap: 20px;
}.list-container {flex: 1;
}.drag-area {min-height: 200px;border: 2px dashed #ccc;padding: 10px;
}.drag-item {padding: 8px;margin: 4px 0;background: #f0f0f0;border-radius: 4px;cursor: move;
}
</style>

2. 指定拖拽手柄

<template><VueDraggable v-model="list" handle=".drag-handle"><div v-for="item in list" :key="item.id" class="item"><span class="drag-handle">⋮⋮</span><span>{{ item.name }}</span><button @click="deleteItem(item.id)">删除</button></div></VueDraggable>
</template><script setup lang="ts">
import { ref } from 'vue'
import { VueDraggable } from 'vue-draggable-plus'const list = ref([{ name: '项目 1', id: 1 },{ name: '项目 2', id: 2 },{ name: '项目 3', id: 3 }
])const deleteItem = (id: number) => {const index = list.value.findIndex(item => item.id === id)if (index > -1) {list.value.splice(index, 1)}
}
</script><style>
.item {display: flex;align-items: center;padding: 8px;border: 1px solid #ddd;margin: 4px 0;
}.drag-handle {cursor: move;margin-right: 8px;color: #999;
}
</style>

3. 克隆模式

<template><div class="clone-demo"><div class="source"><h3>源列表（可克隆）</h3><VueDraggable v-model="sourceList":group="{ name: 'clone', pull: 'clone', put: false }":sort="false"><div v-for="item in sourceList" :key="item.id" class="item">{{ item.name }}</div></VueDraggable></div><div class="target"><h3>目标列表</h3><VueDraggable v-model="targetList"group="clone"><div v-for="item in targetList" :key="item.id" class="item">{{ item.name }}</div></VueDraggable></div></div>
</template><script setup lang="ts">
import { ref } from 'vue'
import { VueDraggable } from 'vue-draggable-plus'const sourceList = ref([{ name: '模板 1', id: 1 },{ name: '模板 2', id: 2 },{ name: '模板 3', id: 3 }
])const targetList = ref([])
</script>

最佳实践

1. 性能优化

<script setup lang="ts">
import { ref, shallowRef } from 'vue'
import { VueDraggable } from 'vue-draggable-plus'// 对于大列表，使用 shallowRef 提高性能
const largeList = shallowRef([...Array(1000)].map((_, i) => ({id: i,name: `项目 ${i}`
})))// 使用防抖处理频繁的拖拽事件
import { debounce } from 'lodash-es'const handleUpdate = debounce(() => {console.log('列表更新')// 执行保存等操作
}, 300)
</script>

2. 数据持久化

<script setup lang="ts">
import { ref, watch } from 'vue'
import { VueDraggable } from 'vue-draggable-plus'const list = ref([])// 监听列表变化，自动保存
watch(list, (newList) => {localStorage.setItem('dragList', JSON.stringify(newList))
}, { deep: true })// 页面加载时恢复数据
const loadData = () => {const saved = localStorage.getItem('dragList')if (saved) {list.value = JSON.parse(saved)}
}loadData()
</script>

3. 错误处理

<script setup lang="ts">
import { ref } from 'vue'
import { useDraggable } from 'vue-draggable-plus'const el = ref()
const list = ref([])const draggable = useDraggable(el, list, {onMove(evt) {// 验证移动是否合法const { dragged, related } = evt// 例如：某些项目不能移动到特定位置if (dragged.dataset.type === 'locked') {return false // 阻止移动}return true},onEnd(evt) {// 拖拽结束后验证数据完整性try {validateListIntegrity(list.value)} catch (error) {console.error('数据验证失败:', error)// 恢复到之前的状态restorePreviousState()}}
})const validateListIntegrity = (list) => {// 实现数据验证逻辑
}const restorePreviousState = () => {// 实现状态恢复逻辑
}
</script>