高级用法

自定义拖拽手柄

在某些场景下，你可能不希望整个元素都可以拖拽，而是只允许用户通过特定的手柄区域来拖拽元素。

在线演示

⋮⋮

项目一

这是第一个项目的描述

⋮⋮

项目二

这是第二个项目的描述

⋮⋮

项目三

这是第三个项目的描述

基本用法

<template>
  <ul
    v-drag-list="{
      list: items,
      canDrag: true,
      dragItemClass: 'app-item', // 添加拖拽项的类名
      dragHandleClass: 'drag-handle', // 添加拖拽手柄类
    }"
    @drag-mode-end="handleDragEnd"
  >
    <li v-for="item in list" :key="item.id" :data-id="item.id">
      <span class="drag-handle">⋮⋮</span>
      <span>{{ item.name }}</span>
      <button @click="deleteItem(item.id)">删除</button>
    </li>
  </ul>
</template>

指令参数详解

v-drag-list 指令接受一个对象作为参数，该对象可以包含以下属性：

属性	类型	必填	默认值	描述
list	Array	是	-	要拖拽的列表数据
canDrag	Boolean	否	true	是否启用拖拽功能
dragItemClass	String	否	'app-item'	可拖拽项的类名
dragHandleClass	String	否	none	拖拽手柄的类名

嵌套列表

vue3-drag-directive 支持多层级嵌套列表的拖拽功能，让你可以构建复杂的树形结构拖拽界面。

基本概念

嵌套列表拖拽允许你在多层级的列表结构中进行拖拽排序，每个层级都可以独立进行拖拽操作，非常适合项目管理、文件目录、组织架构等场景。

🎬 在线演示

⋮⋮

项目 A

这是项目 A 的描述

⋮⋮

子任务 A-2

这是子任务 A-2 的描述

⋮⋮

子任务 A-1

这是子任务 A-1 的描述

⋮⋮

子子任务 A-1-1

最深层任务

⋮⋮

子子任务 A-1-2

最深层任务

⋮⋮

项目 B

这是项目 B 的描述

⋮⋮

项目 C

这是项目 C 的描述

实现要点

1. 数据结构

嵌套列表需要包含 children 字段来表示子项：

const listData = {
  id: 'unique-id', // 必需：唯一标识符
  title: '项目名称', // 显示内容
  expanded: true, // 展开状态
  children: [], // 子项数组
};

2. 多层级指令配置

每个层级都需要独立的 v-drag-list 指令：

<!-- 主列表 -->
<div v-drag-list="{ list: mainList, ... }">
  <!-- 子列表 -->
  <div v-drag-list="{ list: item.children, ... }">
    <!-- 更深层级... -->
  </div>
</div>

3. 事件处理

不同层级需要不同的事件处理函数：

// 主列表拖拽结束
const onMainListDragEnd = (e) => {
  mainList.value = e.detail.updatedData;
};

// 子列表拖拽结束
const onChildListDragEnd = (e, parentItem) => {
  parentItem.children = e.detail.updatedData;
};

配置选项

所有基础配置选项都适用于嵌套列表，每个层级可以有不同的配置：

const dragConfig = {
  list: listData, // 当前层级的数据
  canDrag: true, // 是否允许拖拽
  dragItemClass: 'app-item', // 拖拽项的类名
  dragHandleClass: 'drag-handle', // 拖拽手柄的类名
};