JS实现DOM元素拖拽：Drag and Drop API基础教程

在现代 Web 应用中，拖拽（Drag and Drop）常用于看板任务排序、文件上传、列表调序以及可视化布局编辑器。原生 HTML5 提供了专门的 Drag and Drop API，使开发者无需依赖第三方库或手动监听大量 mousedown、mousemove 和 mouseup 事件，即可让普通 DOM 元素具备完整的拖放交互能力。本文将从原生拖拽的开启方式、生命周期事件序列、DataTransfer 核心载荷对象讲起，并最终完成一个实用的双栏可拖拽任务看板。

一、开启元素拖拽：draggable 属性与环境约定

在 HTML 页面中，文本选区、部分链接（<a href="...">）以及图像（<img>）默认是可以被鼠标抓起拖拽的。但对于常规的容器与块级元素（如 <div>、<li>、<p>），浏览器出于交互安全和默认选区逻辑，默认禁止拖拽。

要让普通 DOM 节点变为可拖拽对象，第一步是在 HTML 标签上显式声明 draggable="true"。这是一个布尔枚举属性，必须设置为 "true" 字符串值。

<!-- 正确：显式开启拖拽 -->
<div id="card-1" class="drag-item" draggable="true">
  任务项：编写单元测试
</div>

<!-- 错误：仅写 draggable 无法在某些浏览器中正确识别枚举值 -->
<div draggable>无效示例</div>

仅声明 draggable="true" 只是赋予了元素“能够被鼠标按住抓取并产生半透明拖拽虚影”的外观表现。如果不对随后的拖拽生命周期事件进行监听和控制，松开鼠标后元素只会弹回原位，页面不会发生任何实质性的 DOM 节点变动。

二、拖拽完整生命周期：事件流与责任划分

理解原生 Drag and Drop API 的核心在于区分两个不同的角色：拖拽源（Drag Source）与放置目标（Drop Target）。这两者在拖拽全生命周期中各自响应完全不同的原生事件。

三、核心数据载体：DataTransfer 对象机制

当一个元素从页面某处被拖起，穿越多个复杂的 DOM 树层级并最终落入另一个容器时，我们如何安全、解耦地传递数据？Drag and Drop API 提供了挂载在拖拽事件对象上的 e.dataTransfer 实例。

DataTransfer 的主要属性和方法包括：

• setData(format, data)：在 dragstart 事件中向剪贴板/数据包中写入数据。通常使用标准 MIME 类型如 'text/plain'、'text/html' 或 'application/json'。
• getData(format)：仅在 drop 事件中允许读取数据。在 dragover 或 dragenter 期间调用将一律返回空字符串（安全保护策略）。
• clearData([format])：清除已存储的特定格式或全部数据。
• effectAllowed：源元素声明允许的操作类型（例如 'none'、'copy'、'move'、'link'、'all'）。
• dropEffect：目标容器控制当前鼠标悬浮下的显示效果（通常与 effectAllowed 配合，展示移动光标或复制加号）。
• setDragImage(imgElement, xOffset, yOffset)：自定义跟随鼠标滑动的拖拽预览图。

四、为什么 drop 不触发？深入理解 dragover 的默认行为拦截

初学者在实现拖拽时，最常遇到的挫折是：明明在目标容器上绑定了 drop 事件监听器，鼠标松开时 drop 回调却完全没有执行，卡片只是直接弹回。这背后的核心原因在于浏览器的默认行为机制。

HTML 规范规定：大部分 DOM 节点在默认状态下都是不允许放置（Drop Not Allowed）的。当被拖拽物掠过任何元素时，浏览器的默认动作是拒绝此次放置。如果要将某个元素转化为合法的放置容器，必须在其 dragover 事件中调用 event.preventDefault()，显式告知浏览器“取消其默认的拒绝逻辑”。

五、实战演练：构建双栏任务看板

为了加深理解，我们来构建一个完整的双栏看板。需求如下：页面包含“待处理（To Do）”与“已完成（Done）”两个列表，卡片可以在两个栏目之间自由拖拽穿梭，且拖拽时原卡片呈现半透明状态，目标栏呈现虚线高亮。

1. HTML 结构

<div class="board">
  <!-- 待处理容器 -->
  <div class="column" id="todo-column">
    <h3>待处理任务</h3>
    <div class="card" id="card-1" draggable="true">1. 完善系统需求说明书</div>
    <div class="card" id="card-2" draggable="true">2. 编写前端拖拽组件逻辑</div>
    <div class="card" id="card-3" draggable="true">3. 对接后端 RESTful 接口</div>
  </div>

  <!-- 已完成容器 -->
  <div class="column" id="done-column">
    <h3>已完成事项</h3>
    <div class="card" id="card-4" draggable="true">4. 评审数据库索引设计</div>
  </div>
</div>

2. CSS 交互状态样式

.board {
  display: flex;
  gap: 24px;
}
.column {
  flex: 1;
  background-color: #f7f6f2;
  border: 2px dashed #ded8cb;
  border-radius: 8px;
  padding: 16px;
  min-height: 280px;
  transition: all 0.2s ease;
}
/* 鼠标拖拽悬浮时的目标容器高亮样式 */
.column.drag-over {
  border-color: #ad8b58;
  background-color: #faf5eb;
}
.card {
  background-color: #ffffff;
  border: 1px solid #e2ded5;
  border-radius: 6px;
  padding: 12px 16px;
  margin-bottom: 12px;
  cursor: grab;
  box-shadow: 0 2px 4px rgba(0,0,0,0.03);
  transition: opacity 0.2s ease;
}
.card:active {
  cursor: grabbing;
}
/* 正在被拖拽的源节点样式 */
.card.dragging {
  opacity: 0.4;
  border-color: #ad8b58;
}

3. JavaScript 核心实现

document.addEventListener('DOMContentLoaded', () => {
  const cards = document.querySelectorAll('.card');
  const columns = document.querySelectorAll('.column');

  // 1. 为所有可拖拽卡片绑定源生命周期事件
  cards.forEach(card => {
    card.addEventListener('dragstart', (e) => {
      // 记录源元素ID到 DataTransfer 载荷中
      e.dataTransfer.setData('text/plain', e.target.id);
      e.dataTransfer.effectAllowed = 'move';
      
      // 延迟微任务修改样式，确保生成的拖拽虚影不受 opacity: 0.4 的影响
      setTimeout(() => {
        card.classList.add('dragging');
      }, 0);
    });

    card.addEventListener('dragend', () => {
      // 拖拽终结时复原样式
      card.classList.remove('dragging');
    });
  });

  // 2. 为所有列容器绑定放置目标生命周期事件
  columns.forEach(column => {
    column.addEventListener('dragover', (e) => {
      // 核心：阻止默认行为以激活放置
      e.preventDefault();
      e.dataTransfer.dropEffect = 'move';
    });

    column.addEventListener('dragenter', (e) => {
      e.preventDefault();
      column.classList.add('drag-over');
    });

    column.addEventListener('dragleave', (e) => {
      // 防止子元素冒泡导致误触发 leave
      if (!column.contains(e.relatedTarget)) {
        column.classList.remove('drag-over');
      }
    });

    column.addEventListener('drop', (e) => {
      e.preventDefault();
      column.classList.remove('drag-over');

      // 从传输载荷中取出卡片 ID 并抓取对应 DOM 节点
      const cardId = e.dataTransfer.getData('text/plain');
      const draggingElement = document.getElementById(cardId);

      if (draggingElement) {
        // 直接 appendChild 将节点从原容器移动至新容器末尾
        column.appendChild(draggingElement);
      }
    });
  });
});

六、开发全流程核对与边界限制

为了在实际业务中稳定运用原生拖拽，最后我们总结出完整的开发实施清单以及原生 API 的边界条件。

常见边界与注意点：

1. Firefox 浏览器的硬性限制：在火狐浏览器中，如果未在 dragstart 中显式调用 e.dataTransfer.setData() 写入任何载荷，即便配置了 draggable="true"，元素也不会启动拖拽行为。因此始终写入至少一个空字符串或键值。
2. 父子元素事件冒泡：当目标容器内部含有子标题或图标时，拖拽经过子元素会重复触发容器的 dragleave 和 dragenter。可以通过 e.currentTarget.contains(e.relatedTarget) 进行过滤判断，或者对子元素设置 CSS pointer-events: none。
3. 移动端支持限制：HTML5 Drag and Drop API 本质上是针对鼠标指针设备设计的规范。在触控屏移动设备（如 iOS 与 Android）上，原生并不响应 draggable 触控拖拽。如需兼容移动端，需借助 Pointer Events 监听 pointerdown、pointermove、pointerup 自行计算坐标，或引入专门的 Polyfill 垫片库。

掌握了原生 Drag and Drop API 的生命周期链条与 DataTransfer 机制后，开发者不仅能够独立完成轻量级看板、卡片调序等日常需求，在阅读和定制复杂第三方拖拽库（如 SortableJS、React DnD）的底层源码时，也能迅速定位其实现机制。