JavaScript Drag & Drop 拖拽功能实现详解

方予

发布时间：2026-10-16 | 4人浏览过

原创

在网页开发中，原生拖拽 API 允许开发者在不依赖第三方库的情况下实现复杂的交互效果，如元素排序、拖拽排序列表以及文件上传预览。核心在于启用元素的 draggable 状态，并在正确的时机介入事件流。

启用可拖拽状态

浏览器默认只允许图片、链接和被选中文本被拖拽。若要使普通 HTML 元素（如 <div>）支持拖拽，必须将其 draggable 属性显式设为 true。

<div draggable="true">
  此区域可拖拉
</div>

对于图片和链接，设置 draggable="false" 可用于禁止用户将其拖出页面（例如防止浏览器打开新窗口或开始下载）。需注意，一旦将某元素设为可拖拽，用户将无法再通过鼠标直接选中该元素内的文字或子节点。

核心拖拽事件流

一个完整的拖拽过程涉及多个事件的触发，理解这些事件的时序是编写稳定代码的关键。整个过程分为三个阶段：启动拖拽、拖拽中和释放（Drop）。

第一阶段：启动拖拽 (dragstart)

当用户按下鼠标并开始拖动目标元素时，dragstart 事件在源元素上触发。这是初始化数据的最佳时机。

目的：保存对当前被拖动元素的引用，并初始化 DataTransfer 对象中的数据。
执行动作：记录 event.target，设定视觉效果（如降低透明度），调用 setData() 写入拖拽内容。
完成状态：拖拽图标生成，系统准备追踪鼠标位置。

第二阶段：拖拽轨迹监测 (dragenter, dragover, dragleave)

这些事件在目标容器（放置区）上触发，用于判断是否允许放下。

dragenter：鼠标首次进入目标区域触发。若需接受拖拽，通常在此处改变目标样式（如高亮背景）。如果未处理或阻止默认行为，可能视为不支持放置。
dragover：鼠标在目标区域内持续移动时频繁触发。**关键点**：必须在监听函数中调用 event.preventDefault() 或返回 false，否则浏览器会忽略放置请求，无法触发 drop 事件。
dragleave：鼠标移出目标区域边界时触发。用于恢复目标的初始视觉状态。

第三阶段：结束与释放 (dragend, drop)

dragend：无论拖拽成功与否（中途取消或 ESC 退出也会触发），源元素上的此事件总会执行。用于清理全局变量和临时样式。
drop：在目标区域松开鼠标键触发。若 dragover 未阻止默认行为，则不会触发此事件。监听器负责从 dataTransfer 提取数据并执行 DOM 操作（如移动节点）。

完整流程示例：以下代码演示了将一个 ID 为 draggable 的节点从一个 .dropzone 容器移动到另一个空容器的过程。

// 1. 初始化拖拽数据
var draggedElement;

document.addEventListener('dragstart', function (e) {
  draggedElement = e.target;
  // 保持引用以便后续使用
  e.dataTransfer.effectAllowed = 'move'; 
  e.dataTransfer.setData('text/plain', draggedElement.id);
});

// 2. 阻止默认的放置行为（关键步骤）
document.addEventListener('dragover', function (e) {
  e.preventDefault(); 
  e.dataTransfer.dropEffect = 'move';
}, false);

// 3. 处理放置逻辑
document.addEventListener('drop', function (e) {
  e.preventDefault();
  var targetNode = e.target.closest('.dropzone');
  if (targetNode && draggedElement) {
    // 检查是否为同一个容器以避免无效操作
    if (targetNode !== draggedElement.parentNode) {
      targetNode.appendChild(draggedElement);
    }
  }
});

document.addEventListener('dragend', function (e) {
  draggedElement.style.opacity = '';
});

DataTransfer 接口详解

event.dataTransfer 是拖拽事件的核心对象，用于存储和操作拖拽期间的数据及其表现效果。

设置与获取数据

setData(format, data)：在 dragstart 阶段使用。常用 MIME 类型包括 text/plain（纯文本）、text/html（富文本）和 text/uri-list（URL）。为了兼容性，建议同时添加 text/plain 版本。
getData(format)：在 drop 阶段读取数据。只有当 format 存在于之前设置的列表中时才有效。
clearData([format])：清除指定或所有已存储的数据。

视觉效果控制

这两个属性决定了用户看到的“拖拽阴影”和鼠标光标形状。

effectAllowed：设置在源元素端允许的操作类型。可选值包括 move, copy, link 及它们的组合（如 copyMove）或 all。默认值为 uninitialized（等同于 all）。
dropEffect：设置在目标端的实际期望效果。必须在 dragover 事件中设置。其值必须是 effectAllowed 允许的子集，否则无法触发 drop。

自定义拖拽图标

默认情况下，拖拽图标是被拖元素的截图。可通过 setDragImage(element, x, y) 自定义：

ev.dataTransfer.setDragImage(customImgElement, offsetX, offsetY);

高级特性：文件拖入

除了 DOM 节点，Web 应用程序还可接收操作系统拖入的文件。此时 dataTransfer.files 包含了一个 FileList 对象。

dropZone.addEventListener('drop', function(e) {
  e.preventDefault();
  const files = e.dataTransfer.files;
  for (let i = 0; i < files.length; i++) {
    console.log(files[i].name, files[i].size);
  }
});

要读取文件内容，需结合 FileReader API 异步读取。dataTransfer.items 提供了一种更通用的方式访问拖拽项（文件或字符串）。