HTML5原生拖拽API是一套由浏览器实现的事件机制，允许开发者让页面元素被拖动并放置到其他元素上。它不需要引入任何外部库，核心是通过在元素上设置draggable属性以及监听一系列drag相关事件来完成交互。理解这套机制对于实现文件上传、看板排序、组件布局等场景非常实用。
一、原生拖拽API的核心概念
在HTML5中，并不是所有元素默认可拖拽。文本、图片和链接在部分浏览器中天生可拖，但普通的<div>或<li>必须显式声明draggable="true"才能成为拖拽源。拖拽过程由拖拽源、放置目标和数据携带者三部分组成，其中数据通过DataTransfer对象在事件之间传递。
整个生命周期包含多个事件：dragstart在用户开始拖拽时触发，drag在拖拽移动中连续触发，dragenter和dragover用于进入和悬停放置目标，drop在松开鼠标且目标允许放置时触发，dragend则表示拖拽结束。只有阻止了dragover的默认行为，drop才会被正常触发，这是新手最容易遗漏的一步。
1.1 draggable属性与基本结构
要让一个块级元素可拖，只需在标签上写draggable="true"。放置区域则不需要该属性，但必须在脚本里监听其dragover并调用preventDefault。下面是一段最简结构的HTML示例。
<div id="source" draggable="true">拖我</div> <div id="target">放到这里</div>
上面的代码中，source是拖拽源，target是放置目标。如果不加任何脚本，拖动source时浏览器只会显示默认的半透明残影，无法在target上完成放置，因为target尚未声明接受放置行为。
1.2 DataTransfer的作用
DataTransfer是拖拽事件event.dataTransfer引用的对象，用于在拖拽源和放置目标间传递数据。你可以在dragstart中用setData写入文本或自定义类型，在drop中用getData读取。它还能通过setDragImage自定义拖拽时跟随鼠标显示的图片。
需要注意的是，getData在大多数事件中不可读，仅在drop事件内才能拿到数据，这是浏览器的安全限制。因此在dragover里不要试图读取内容，只需处理样式或阻止默认行为即可。
二、完整拖拽示例：列表项移动
下面用一个常见需求来演示：把左侧列表中的条目拖到右侧列表中。这个例子覆盖事件绑定、数据传递和DOM操作，能体现原生API的完整用法。
// 获取源列表和目标列表
var left = document.getElementById('left');
var right = document.getElementById('right');
// 事件委托：为源列表子项绑定dragstart
left.addEventListener('dragstart', function(e) {
// 将被拖元素的id存入DataTransfer
e.dataTransfer.setData('text/plain', e.target.id);
});
// 目标列表必须阻止dragover默认行为，否则无法触发drop
right.addEventListener('dragover', function(e) {
e.preventDefault();
});
// 在目标列表放下时，移动节点
right.addEventListener('drop', function(e) {
e.preventDefault();
var id = e.dataTransfer.getData('text/plain');
var node = document.getElementById(id);
if (node) {
right.appendChild(node);
}
});
上述脚本中，dragstart把元素id写进数据通道，dragover调用preventDefault打开放置权限，drop读取id并将对应节点追加到右侧列表。这样就实现了无库依赖的列表迁移。
如果希望支持从右拖回左，只需给left也绑定同样的dragover和drop逻辑，并让right在dragstart时写数据。原生API的对称性使得双向拖拽并不复杂，核心仍是阻止默认行为与正确读写DataTransfer。
三、文件拖入上传场景
除了页面内元素，原生拖拽API还能接收操作系统中的文件。当用户把本地文件拖到网页放置区时，drop事件的dataTransfer.files会包含一个FileList，可配合FormData发到服务端。
var zone = document.getElementById('zone');
zone.addEventListener('dragover', function(e) {
e.preventDefault();
zone.style.background = '#eee';
});
zone.addEventListener('dragleave', function(e) {
zone.style.background = '';
});
zone.addEventListener('drop', function(e) {
e.preventDefault();
var files = e.dataTransfer.files;
var fd = new FormData();
for (var i = 0; i < files.length; i++) {
fd.append('file' + i, files[i]);
}
// 此处可使用fetch或XMLHttpRequest发送fd到服务器
});
这段代码展示了如何把拖入的文件收集到FormData中。由于files是浏览器从系统获得的真实文件引用，无需额外的<input type="file">也能完成上传入口，体验比传统点击选择更直观。
要注意的是，文件拖拽时的dragstart不会在页面脚本中触发，因为源头是操作系统。因此所有逻辑都集中在放置区的dragover与drop事件里，并且一定要阻止dragover默认行为，否则浏览器会直接打开文件而非交给脚本处理。
四、常见误区与兼容注意
不少人在写完drop逻辑后发现根本不生效，原因几乎都是忘记在dragover中preventDefault。浏览器默认把放置区当作不可放置，只有显式阻止默认动作，drop才会 firing。另一个误区是试图在drag事件中读取getData，如前文所说，这是被禁止的。
在兼容性方面，现代Chrome、Firefox、Edge均完整支持该API，旧版IE不支持。移动端浏览器大多未实现鼠标拖拽，需要改用touch事件模拟。因此在生产环境中，如果面向移动端，原生拖拽仅能作为增强特性，不能作为唯一交互方式。
4.1 样式反馈提升体验
在dragenter和dragleave中切换放置区的边框或背景，能让用户明确当前可放置位置。这种视觉反馈不需要复杂逻辑，却能显著降低操作迷惑感。
例如给dragenter添加高亮类，dragleave移除类，配合drop后的清理，就能形成清晰的拖拽指引。这类细节往往是衡量拖拽功能是否好用的关键，而非仅仅能否完成数据传递。
五、小结
HTML5原生拖拽API通过draggable属性加drag系列事件，提供了不依赖框架的拖放能力。抓住阻止dragover默认行为、用DataTransfer传数据两个要点，就能实现元素排序与文件拖入等典型功能。在桌面端项目中，优先使用原生方案可以减少包体积并提升可控性。
当业务涉及复杂拖拽态管理或多端适配时，再考虑在此基础上封装或引入专业库。理解底层事件模型后，无论使用什么工具都不会迷失在抽象接口中。
HTML5_drag_and_drop原生拖拽APIDraggable修改时间：2026-08-08 11:09:31