HTML元素拖拽需在dragstart中调用dataTransfer.setData()（如'application/json'），否则静默失败；drop区必须同时阻止dragover和drop的默认行为才能触发drop事件；dragend应全局清理.dragging类。
dragstart 事件里必须设置 dataTransfer.setData
浏览器默认只允许拖拽图片、链接和选中文本，HTML 元素要能被拖动，dragstart 中必须调用 dataTransfer.setData()，哪怕只是设个空字符串或占位类型。漏掉这句，拖拽会静默失败，控制台也不报错。
常见错误是只写了 event.preventDefault() 或只加了 draggable="true"，但没设数据：
element.addEventListener('dragstart', (e) => {
// ❌ 错误：没 setData，拖不动
e.target.classList.add('dragging');
});正确写法：
element.addEventListener('dragstart', (e) => {
// ✅ 必须设置，类型名任意，但建议有意义
e.dataTransfer.setData('application/json', JSON.stringify({
type: 'widget',
id: element.dataset.id
}));
e.dataTransfer.effectAllowed = 'move';
e.target.classList.add('dragging');
});-
dataTransfer.effectAllowed设为'move'能让 drop 区域识别意图，影响光标样式和drop事件触发逻辑 - 避免用
'text/plain'类型——某些浏览器（如 Safari）对非文本类型拖拽更严格，application/json兼容性更好 - 不要在
setData里传 DOM 节点或函数，只能传字符串；序列化对象是安全做法
drop 区域必须阻止默认行为才能触发 drop 事件
drop 事件本身不会自动触发，除非 dragover 和 drop 两个事件都调用了 event.preventDefault()。这是最常卡住的点：开发者只在 drop 里阻止，默认行为仍在 dragover 阶段被浏览器拦截，导致 drop 根本不执行。
立即学习“前端免费学习笔记（深入）”；
正确绑定方式：
dropZone.addEventListener('dragover', (e) => {
e.preventDefault(); // ✅ 关键：允许放置
e.dataTransfer.dropEffect = 'move';
});
<p>dropZone.addEventListener('drop', (e) => {
e.preventDefault(); // ✅ 同样需要
const data = e.dataTransfer.getData('application/json');
try {
const payload = JSON.parse(data);
// 插入组件逻辑，比如 appendChild 或更新布局数组
} catch {}
});-
dragover里设dropEffect可控制光标样式（'move'/'copy'），但不影响逻辑 - 如果 drop 区域是空 div，记得设
min-height或伪元素占位，否则高度为 0，拖进去没响应 - 多个嵌套 drop 区（如画布 + 容器组）时，外层
dragover阻止后，内层仍需各自处理，否则事件会冒泡到父级
拖放后清理 dragging 状态和 focus 干扰
拖拽结束（dragend）不一定触发在源元素上——比如用户拖到页面外松手，dragend 仍会触发，但此时源元素可能已从 DOM 移除或重排。直接操作 e.target class 容易报错。
更稳妥的做法是统一用 class 控制视觉反馈，并在 dragend 里清全局状态：
document.addEventListener('dragend', () => {
document.body.classList.remove('is-dragging');
// 清理所有 .dragging 元素，避免残留
document.querySelectorAll('.dragging').forEach(el => {
el.classList.remove('dragging');
});
});- 拖拽过程中焦点可能丢失，尤其 Chrome 下 input 失去 focus；可在
dragstart前缓存 activeElement，dragend后尝试 restore - 移动端不支持原生 drag API，得用
touchstart/move/end模拟，这不是 HTML 拖拽 API 的职责，别混在一起处理 - 若组件带可编辑文本（如标题输入框），拖拽时应禁用其 focus 行为，否则松手瞬间光标跳进输入框，干扰布局逻辑
布局插入位置依赖 dragenter/dragleave 判断边界
可视化工具通常需要“插入到上方/下方/内部”，仅靠 drop 事件无法知道鼠标在目标区域的相对位置。得靠 dragenter + dragover 实时计算坐标，再结合 getBoundingClientRect() 判定插入点。
简单策略：监听 dragover，每 100ms 计算一次鼠标 Y 坐标相对于 drop 区顶部的占比：
let insertPosition = 'inside'; // 'before' | 'after' | 'inside'
dropZone.addEventListener('dragover', (e) => {
const rect = dropZone.getBoundingClientRect();
const y = e.clientY - rect.top;
const mid = rect.height / 2;
insertPosition = y < mid ? 'before' : 'after';
});- 不要在
dragenter里一次性判断——它只触发一次，而用户可能悬停移动 - 如果 drop 区有 padding/border，
getBoundingClientRect()已包含，无需额外减去 - 滚动容器中，
clientY是视口坐标，getBoundingClientRect()也是相对视口，不用转 scrollY - 高频触发下注意节流，但别用防抖——拖拽是连续动作，防抖会导致判定延迟明显
拖放逻辑真正难的不是 API 调用，而是状态同步时机：组件被拖走时是否立即从布局数据中移除？还是等 drop 成功后再改？这两者在撤销、异常中断、跨 iframe 拖拽时表现完全不同。实际项目里，几乎都需要配合一个中间状态管理器，而不是只靠事件回调硬编码。
