HTML5拖拽API是一套由浏览器原生提供的事件机制，允许开发者通过少量代码让页面元素支持鼠标拖拽与释放。与早期使用mousemove模拟拖拽相比，原生Drag and Drop不需要手动计算坐标偏移，也不会在快速拖动时丢失鼠标捕捉，同时在移动端触屏上也能借助浏览器自身逻辑获得基本兼容。理解这套API的核心，在于搞清楚拖拽生命周期中各事件的触发时机，以及如何利用dataTransfer在源元素和目标元素之间传递数据。
一、拖拽API的基础事件与属性
要让一个元素可被拖动，第一步是在HTML标签上设置draggable="true"。对于大部分块级元素，默认是不可拖拽的，如果不显式声明，即使绑定了drag事件也不会生效。文本输入框和图片在部分浏览器中默认可拖拽，但我们在做自定义交互时仍建议统一加上该属性以避免差异。需要注意的是，draggable是一个枚举属性，值应为true或false，写成draggable不带值在某些旧版浏览器中会被当作无效。
拖拽过程会依次触发一系列事件：在源元素上先触发dragstart，随后是多次drag，当指针移入潜在目标时目标元素触发dragenter和dragover，离开时触发dragleave，释放时源元素触发dragend而目标元素触发drop。其中最关键的是dragover的默认行为会阻止drop，因此必须在目标容器的dragover处理器中调用event.preventDefault()，否则drop事件永远不会发生。很多初学者拖拽没反应，根本原因就是漏掉了这行代码。
下面是一段最小可用的结构示例，展示如何声明可拖拽块和放置区：
<div id="source" draggable="true">拖我</div> <div id="target">放到这里</div>
对应的脚本只需监听几个事件即可完成基础联动，不需要任何第三方库。这种原生方式的性能优势在于浏览器自行管理拖拽影像（drag image），开发者无需用绝对定位元素去跟随鼠标。
二、dataTransfer对象的数据传递机制
dataTransfer是拖拽事件对象上的一个属性，用于在拖拽源和放置目标之间传递数据。在dragstart中调用setData(format, data)写入内容，在drop中通过getData(format)读取。格式参数推荐使用标准MIME如text/plain，也可以使用自定义类型如application/x-myapp，但某些浏览器只支持小写且对自定义类型有限制，生产环境建议优先使用text/plain或text/html。
一个常见误区是试图在dragover里读取data，这是不被允许的，因为出于安全考虑浏览器在拖动过程中不会把数据暴露给目标，只能在drop时获取。此外setData可以多次调用不同格式，但同一格式后一次会覆盖前一次。我们可以通过effectAllowed和dropEffect来约束操作类型，比如设成move表示移动，copy表示复制，这样光标会显示不同图标，提升用户体验。
以下代码演示了如何在源元素写入id，在目标中读取并移动节点：
var src = document.getElementById('source');
var tar = document.getElementById('target');
src.addEventListener('dragstart', function(e) {
e.dataTransfer.setData('text/plain', e.target.id);
e.dataTransfer.effectAllowed = 'move';
});
tar.addEventListener('dragover', function(e) {
e.preventDefault();
e.dataTransfer.dropEffect = 'move';
});
tar.addEventListener('drop', function(e) {
e.preventDefault();
var id = e.dataTransfer.getData('text/plain');
var node = document.getElementById(id);
tar.appendChild(node);
});
这种写法把数据传递与DOM操作解耦，即使以后有多个源元素，也只需在drop里根据id统一处理。相比把整个对象塞进全局变量，dataTransfer更符合沙箱安全模型，也避免了跨组件状态污染。
三、完整拖拽功能实现与常见坑点
实际项目中往往不止一个放置区，而是列表排序或看板卡片移动。此时需要给每个容器绑定同样的dragover和drop逻辑，并在dragstart时记录源节点，在drop时判断插入位置。如果希望拖拽时显示半透明效果，可以在dragstart给源元素加class，在dragend移除。注意dragend无论成功失败都会触发，适合做样式清理。
另一个坑是拖拽图片或链接时浏览器默认会启动自身的资源拖动，比如拖图片去新标签页打开。如果要把图片作为自定义拖拽源，除了设draggable，还应在dragstart里setData并preventDefault掉默认行为，否则drop里拿到的可能是图片地址而非我们设的数据。对于文件拖入页面，需监听drop并用e.dataTransfer.files读取，这时要阻止默认打开文件的行为。
下面给出一个多容器卡片拖拽的较完整示例：
<div class="board"> <div class="card" draggable="true" id="c1">任务一</div> <div class="card" draggable="true" id="c2">任务二</div> </div> <div class="board" id="done"></div>
var cards = document.querySelectorAll('.card');
cards.forEach(function(c) {
c.addEventListener('dragstart', function(e) {
e.dataTransfer.setData('text/plain', c.id);
});
});
var boards = document.querySelectorAll('.board');
boards.forEach(function(b) {
b.addEventListener('dragover', function(e) {
e.preventDefault();
});
b.addEventListener('drop', function(e) {
e.preventDefault();
var id = e.dataTransfer.getData('text/plain');
var el = document.getElementById(id);
b.appendChild(el);
});
});
上述代码让两个看板区域都能接收卡片，实现最基础的敏捷看板交互。若需要进一步插入到特定位置而非追加末尾，可在dragover时通过document.elementFromPoint或遍历子节点计算鼠标相对位置，再用insertBefore精确定位。整体来看，HTML5拖拽API用很少的代码即可覆盖绝大多数交互需求，远比手写mouse事件稳定，是现代前端实现拖拽的首选方案。
HTML5_Drag_APIDrag_and_Drop元素拖拽修改时间：2026-08-16 20:06:16