---

Vue Draggable 快速上手教程：轻松实现列表拖拽与排序

在现代 Web 应用中，拖拽（Drag and Drop）功能已经成为提升用户体验、构建直观界面的重要手段。无论是任务看板的卡片移动、表单元素的自由排序，还是文件上传与图片整理，拖拽都能极大地简化操作。对于 Vue.js 开发者而言，幸运的是，我们拥有一个强大且易于使用的库来处理这一需求——Vue.draggable。

Vue.draggable 是一个基于 Sortable.js 的 Vue.js 组件，它完美地结合了 Sortable.js 强大的拖拽能力与 Vue.js 的响应式数据绑定特性。通过简单的 v-model 指令，你就能让列表数据与拖拽行为同步，无需手动操作 DOM，大大提高了开发效率。

本教程将带你从零开始，详细了解如何快速上手 Vue.draggable，掌握其核心用法、重要属性和事件，并探索一些常见的应用场景。

1. 前言与准备工作

在深入学习 Vue.draggable 之前，你需要确保具备以下基础：

• Vue.js 基础知识: 了解 Vue 的组件化开发、模板语法、数据绑定（特别是 v-model）、事件处理、计算属性等。
• Node.js 和 npm/yarn: Vue.draggable 是一个 npm 包，你需要使用 npm 或 yarn 进行安装。
• 一个 Vue 项目: 你可以使用 Vue CLI、Vite 或其他构建工具创建一个 Vue 项目来进行实践。

Vue.draggable 兼容 Vue 2 和 Vue 3。本教程将主要基于 Vue 3 的语法进行讲解，但在关键差异处会进行说明。

2. 安装 Vue Draggable

安装 Vue.draggable 非常简单，只需要使用 npm 或 yarn 在你的项目目录中运行以下命令：

“`bash

使用 npm

npm install vue-draggable-next sortablejs

使用 yarn

yarn add vue-draggable-next sortablejs
“`

注意: Vue.draggable (特别是 vue-draggable-next 版本，兼容 Vue 3) 依赖于 sortablejs 库，所以你需要同时安装 sortablejs。vue-draggable-next 是 Vue.draggable 的 Vue 3 友好版本，通常推荐在新项目中使用。如果你的项目是 Vue 2 且不打算升级，可以安装 vuedraggable (注意没有 -next)。本教程主要使用 vue-draggable-next。

安装完成后，你就可以在你的 Vue 组件中引入并使用 draggable 组件了。

3. 基本用法：让列表动起来！

Vue.draggable 最核心的功能就是让一个基于数组渲染的列表变得可拖拽和排序。这通过 v-model 指令与你的列表数据绑定来实现。

假设你有一个 Vue 组件，其中有一个数组 myList，你想让这个数组中的元素可以互相拖拽排序。

步骤:

1. 在 <script> 标签中引入 draggable 组件。
2. 在 template 中使用 <draggable> 标签包裹你的列表元素。
3. 使用 v-model 将 draggable 组件与你的列表数据（数组）进行绑定。
4. 在 draggable 内部，使用 v-for 遍历数组并渲染每一个列表项。
5. 重要： 为 v-for 循环中的每个列表项设置一个 :key 属性。此外，对于 draggable 组件本身，从 [email protected] 或 [email protected] 开始，强制要求设置一个 :item-key 属性。这个 item-key 应该是一个函数或字符串，用于获取列表中每个项目的唯一标识。

代码示例:

“`vue

“`

代码解释:

1. 我们引入了 draggable 组件并注册它。
2. 在 setup 函数中，我们使用 ref 创建了一个响应式数组 myList，每个元素包含 id 和 name。
3. 在 <template> 中，我们使用了 <draggable> 标签。
   • v-model="myList": 这是关键！它将 draggable 的内部状态（元素的顺序）与 myList 数组同步。当你在页面上拖拽元素改变顺序时，myList 数组的顺序也会自动更新。反之，如果你在代码中修改 myList，页面上的元素顺序也会相应更新。
   • item-key="id": 我们指定 id 作为每个列表项的唯一键。Vue.draggable 需要这个键来高效地跟踪列表项的变化，这类似于 v-for 中的 :key，但它是提供给 draggable 内部使用的。你可以传入一个字符串（表示元素对象的属性名）或一个函数 (element) => element.id。
   • tag="ul": 指定 draggable 组件最终渲染成什么 HTML 标签。默认为 div。这里我们希望它是一个无序列表，所以设为 ul。
   • <template #item="{ element }">: 这是 Vue 3 的插槽（Slots）用法。draggable 组件提供了一个默认插槽，用于渲染列表项。通过 v-for 结合插槽，我们可以访问到当前循环的元素 (element)，然后渲染我们的列表项 (<li>)。Vue 2 的语法略有不同，通常是直接在 <draggable> 内部使用 v-for="element in myList"，但推荐使用插槽以兼容更多特性。
4. 我们添加了一些基本的 CSS 样式，让列表项看起来更像列表，并添加了 cursor: grab; 样式提示用户可以拖拽。
5. 最后，我们通过 <pre> 标签实时显示 myList 数组的内容，你可以看到拖拽后数组顺序的变化。

运行此组件，你将看到一个带有四个项目的列表，你可以尝试拖拽它们改变顺序，并观察下方数组数据的变化。

4. 重要属性 (Props)

Vue.draggable 提供了许多属性来定制拖拽行为。以下是一些最常用的：

• v-model (必填): 前面已经详细介绍，用于绑定列表数据（数组）。
• item-key (Vue 3 必填): 指定列表中每个项目的唯一键，可以是属性名字符串或函数。确保其值是唯一的。
• tag (可选): 指定 draggable 组件渲染的根 HTML 元素标签，默认为 div。
• group (可选): 用于连接多个可拖拽列表，实现列表间的元素移动。可以是一个字符串，或者一个配置对象 { name: string, pull: string|string[]|boolean|Function, put: string|string[]|boolean|Function }。
  • 当 group 是字符串时，所有具有相同 group 字符串的列表可以互相拖拽。
  • pull: 定义是否可以从当前列表向外拖拽元素。可以是 true (可以拖出)、false (不能拖出)、'clone' (拖出副本)、或一个函数。
  • put: 定义是否可以向当前列表拖入元素。可以是 true (可以拖入)、false (不能拖入)、一个表示允许拖入的组名的字符串或数组、或一个函数。
• handle (可选): 一个 CSS 选择器字符串。如果设置了这个属性，只有点击并拖拽匹配选择器的子元素时，整个列表项才能被拖拽。这对于只希望通过某个图标或区域进行拖拽的场景非常有用。
• filter (可选): 一个 CSS 选择器字符串。如果拖拽开始于匹配选择器的子元素，将阻止拖拽行为。这与 handle 相反，用于定义哪些区域是不可拖拽的。
• disabled (可选): 布尔值，默认为 false。如果设置为 true，将完全禁用当前 draggable 实例的拖拽功能。
• animation (可选): 拖拽动画的毫秒数。设置大于 0 的值会使元素在排序时具有平滑的过渡效果。
• easing (可选): 动画缓动函数，例如 'cubic-bezier(1, 0, 0, 1)'。
• ghost-class (可选): 被拖拽元素在原位置留下的占位符元素的 CSS 类名。
• chosen-class (可选): 当前被选中（正在被拖拽）的元素的 CSS 类名。
• drag-class (可选): 正在被拖拽元素的 副本（当 force-fallback 为 true 时）的 CSS 类名。
• force-fallback (可选): 布尔值，默认为 false。如果设置为 true，即使浏览器原生支持，也会强制使用基于 CSS translate 的拖拽方式。在某些复杂的 CSS 布局（如 flex 或 grid）下，原生拖拽可能表现不佳，此时可以尝试开启此选项。
• sort (可选): 布尔值，默认为 true。如果设置为 false，元素将无法在当前列表中进行排序，但如果设置了 group，仍然可以拖拽到其他列表。
• clone (可选): 布尔值或函数，默认为 false。如果设置为 true 或返回一个新对象的函数，拖拽的将是列表项的副本，原始项留在原位。结合 group 的 pull: 'clone' 非常有用，可以创建一个“工具箱”列表，从中拖拽项目到其他地方。

5. 事件处理

除了通过 v-model 自动更新数据外，你还可以监听 draggable 组件触发的各种事件，以执行额外的逻辑，例如在拖拽开始、结束或数据改变时触发后端 API 调用、记录日志等。

常用的事件包括：

• @start: 拖拽开始时触发。
• @end: 拖拽结束时触发。
• @add: 元素被添加到当前列表时触发（从其他列表拖入）。
• @remove: 元素从当前列表被移除时触发（拖拽到其他列表）。
• @update: 元素在当前列表中排序时触发（只改变了位置，没有增减）。
• @change: 当列表内容或顺序发生变化时触发，包含 add, remove, update 三种类型的变化信息。这个事件非常实用，可以统一处理所有改变数据的场景。

事件对象:

这些事件都会接收一个事件对象作为参数，这个对象通常包含关于拖拽操作的详细信息。虽然不同事件的属性略有不同，但常见的重要属性包括：

• evt.item: 被拖拽的 DOM 元素。
• evt.from: 元素被拖拽前的父容器 DOM 元素。
• evt.to: 元素被拖拽后的父容器 DOM 元素。
• evt.oldIndex: 元素在拖拽前在 from 容器中的索引。
• evt.newIndex: 元素在拖拽后在 to 容器中的索引。
• evt.oldDraggableIndex: 元素在拖拽前在 draggable 组件数据数组中的索引（考虑到 handle 或 filter 可能导致 DOM 索引与数据索引不一致）。
• evt.newDraggableIndex: 元素在拖拽后在 draggable 组件数据数组中的索引。
• 对于 @add 和 @remove 事件，事件对象中还会有 newIndex 和 oldIndex 等属性指向对应的位置。
• 对于 @change 事件，事件对象有一个属性 added, removed, 或 moved，分别包含对应操作的详细信息（如 element, newIndex, oldIndex 等）。

代码示例 (事件处理):

在前面的基础上，我们添加事件监听。

“`vue

“`

代码解释:

1. 我们在 <draggable> 组件上添加了 @start, @end, @change 监听器，并分别指向 onStart, onEnd, onChange 方法。
2. 在对应的事件处理方法中，我们通过 console.log 打印事件对象，并向 eventLogs 数组中添加简单的日志信息，方便在页面上查看。
3. onEnd 事件通常是执行保存操作的好时机，因为此时拖拽已经完成，v-model 绑定的数据数组 (myList) 已经更新为最终的顺序。
4. onChange 事件非常强大，它能告诉你列表发生了哪种类型的变化（添加、移除或移动），并且提供了详细的变化信息。当你在实现如看板或跨列表拖拽时，onChange 会非常有用，你可以根据是 added、removed 还是 moved 来执行不同的逻辑，比如更新数据库中的条目归属或顺序。

通过监听这些事件，你可以精确控制拖拽行为发生时你的应用程序的反应。

6. 连接多个列表 (Kanban 示例)

Vue.draggable 的强大之处在于可以轻松实现多个列表之间的拖拽。这只需要给不同的 <draggable> 组件设置相同的 group 属性即可。

代码示例 (简单 Kanban):

我们将创建两个列表：一个表示待办事项，一个表示已完成事项，并允许事项在这两个列表之间拖拽。

“`vue

“`

代码解释:

1. 我们创建了两个 ref 数组 todoList 和 doneList。
2. 创建了两个 <draggable> 组件，分别绑定 todoList 和 doneList。
3. 关键: 两个 <draggable> 组件都设置了相同的 group="tasks" 属性。这告诉 Sortable.js（以及 Vue.draggable）这两个列表属于同一个组，元素可以在它们之间自由拖拽。
4. 我们添加了一些 CSS 样式来模拟看板的列和卡片样式，并为完成项添加了特殊样式。
5. 注意，当元素在列表之间移动时，v-model 会自动处理数据的更新。从 todoList 拖拽到 doneList，元素会自动从 todoList 移除并添加到 doneList 的相应位置。

运行此示例，你就可以轻松地将事项从一个列表拖拽到另一个列表，实现一个简单的看板功能。

如果你需要更精细地控制哪些组可以互相拖拽，或者控制是复制还是移动，可以使用 group 属性的配置对象语法，例如：

“`vue

…

…

…

…
“`

7. 使用 handle 和 filter 控制拖拽区域

有时你不想让列表项的任何位置都可以触发拖拽，而是希望用户点击一个特定的区域（如拖拽图标）才能拖拽整个项目。这时可以使用 handle 属性。

相反，如果你想阻止用户在列表项内的某个特定元素（如按钮、输入框）上开始拖拽，可以使用 filter 属性。

代码示例 (handle):

“`vue

“`

代码解释:

1. 我们在列表项 <li> 中添加了一个 <span> 元素，并给它加上了 handle 类。
2. 我们在 <draggable> 组件上设置了 handle=".handle" 属性。
3. 现在，只有当你点击并拖拽带有 handle 类的 <span> 时，整个 <li> 才能被拖拽。点击 <li> 的其他区域（如文本或按钮）则不会触发拖拽，按钮的点击事件也会正常工作。

代码示例 (filter):

“`vue

“`

代码解释:

1. 我们在按钮 <button> 上添加了 no-drag 类，并绑定了一个点击事件。
2. 我们在 <draggable> 组件上设置了 filter=".no-drag" 属性。
3. 现在，当你点击列表项的其他区域时，可以正常拖拽。但是当你点击带有 no-drag 类的按钮时，将不会触发拖拽，而是会触发按钮的点击事件 (alertName)。

8. 插槽 (Slots) 的进一步应用

除了默认插槽（用于渲染列表项）和 item 插槽（Vue 3 推荐用于渲染列表项），Vue.draggable 还提供了 header 和 footer 插槽，允许你在可拖拽区域的上方和下方添加固定的、不可拖拽的内容。

“`vue

“`

代码解释:

1. 我们使用了 #header 和 #footer 具名插槽。
2. 放在这两个插槽内的内容（这里是两个 <li>）将分别显示在可拖拽列表项的上方和下方。
3. 这些插槽内的元素是不受 draggable 控制的，它们是固定的，不能被拖拽或排序。

9. 克隆 (Clone) 模式

在某些场景下，你可能希望拖拽的是列表项的一个副本，而不是移动原始项。例如，一个组件库面板，你可以从面板中拖拽组件实例到画布上。这可以使用 clone 属性实现。

结合 group 的 pull: 'clone' 选项，可以实现从一个源列表拖拽副本到目标列表的功能。

“`vue

“`

代码解释:

1. componentList 表示工具箱中的可用组件，canvasItems 表示画布上已经放置的组件实例。
2. 工具箱的 <draggable> 设置 group 的 pull: 'clone'，表示只能从这里拖出副本。同时 put: false 和 sort: false 禁用向工具箱拖入和工具箱内部排序。
3. 画布的 <draggable> 设置 group 的 put: true，允许从 ‘components’ 组拖入。
4. 关键: 工具箱的 <draggable> 设置了 :clone="cloneComponent"。当从这个列表拖拽时，会调用 cloneComponent 函数。这个函数接收原始元素作为参数，并返回一个用于拖拽的新对象。我们在这里为副本生成了一个新的唯一 id。
5. 注意 canvasItems 的 item-key 是 id，而 componentList 的 item-key 是 type。这是合理的，因为工具箱中的项是模板，用 type 标识；而画布上的项是实例，需要用唯一的 id 标识。
6. 当从工具箱拖拽一个项目到画布时，会触发工具箱的 @remove 事件（因为它克隆了）和画布的 @add 事件。画布的 canvasItems 数组会通过 v-model 添加一个新的、带有唯一 id 的元素（由 cloneComponent 创建）。

这个例子展示了如何利用 clone 和 group 的高级配置实现更复杂的拖拽交互，如可视化编辑器中的组件拖放。

10. 常见问题与技巧

• item-key 的重要性: 在 Vue 3 中，item-key 是强制要求的。它为 draggable 提供了每个元素的稳定身份，这对于 Sortable.js 正确跟踪元素的移动和 Vue 的虚拟 DOM 更新至关重要。务必使用一个真正唯一的属性作为 item-key。
• 样式问题 (Flex/Grid): 在使用 display: flex 或 display: grid 的父容器中嵌套 draggable 列表时，有时可能会遇到拖拽占位符或拖拽元素位置异常的问题。这通常是因为 Sortable.js 在计算位置时受到 flex/grid 布局的影响。尝试为 draggable 组件添加 force-fallback="true" 属性，强制使用基于 transform 的拖拽方式，这有时能解决兼容性问题。另外，确保你的列表项 (<template #item> 内部的元素) 是 draggable 组件的直接子元素。
• 数据更新与持久化: v-model 自动处理前端数据的更新非常方便。但大多数应用都需要将拖拽后的顺序或跨列表的变动保存到后端。最佳实践是在 @end 或 @change 事件中触发你的保存逻辑，将更新后的数据 (v-model 绑定的数组) 发送到服务器。
• 性能优化: 如果你的列表中有成百上千个项目，拖拽性能可能会下降。Vue.draggable 本身是高效的，但大量的 DOM 元素和复杂的列表项渲染会是瓶颈。在这种情况下，考虑结合使用虚拟列表（Virtual List）库（如 vue-virtual-scroller, vue-recycle-scroller）来只渲染视口内的项目，这能显著提升性能。不过，将虚拟列表与拖拽结合可能需要更深入的配置和技巧。
• 嵌套拖拽: Vue.draggable 也支持嵌套的拖拽列表，比如实现一个多层级的树形结构拖拽。这需要仔细配置 group 属性，确保父子列表之间的拖拽规则正确。文档中有更详细的例子。

11. 总结

Vue.draggable 是一个为 Vue 开发者量身打造的强大拖拽库。通过与 Vue 的 v-model 深度集成，它极大地简化了列表拖拽和排序功能的实现。本教程从安装、基本用法讲起，详细介绍了 v-model 和 item-key 的核心概念，探讨了 group, handle, filter, animation 等重要属性，学习了如何监听 @start, @end, @change 等事件，并通过看板和克隆模式的示例展示了如何实现更复杂的拖拽交互。

掌握 Vue.draggable，你就能轻松地在你的 Vue 应用中构建出更具交互性和用户体验的拖拽功能。记住，多实践、多查阅官方文档（vue-draggable-next 或 vuedraggable）是深入学习的最好方式。

希望这篇详细的教程能帮助你快速上手 Vue.draggable，并在你的项目中大显身手！

---