HTML Academy · 课时

dataTransfer 对象

Q: 「dataTransfer 对象」这节课中我会学到什么？

在拖动源和放置目标之间传输数据 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

在拖动源和放置目标之间传输数据

dataTransfer 对象 是 CoddyKit 上的免费 HTML Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 HTML Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 HTML Academy 课程共包含 4 节课。

dataTransfer 中包含什么

dataTransfer 对象附加在每个拖拽事件上，是源元素与目标之间唯一的通信渠道。它携带载荷数据、文件列表、允许的效果以及选定的放置效果。

setData 与 getData

源元素使用 e.dataTransfer.setData(format, value) 写入带类型的载荷。目标使用 e.dataTransfer.getData(format) 读取载荷。两个参数都是字符串；值在存储前会被强制转换为字符串。

src.addEventListener("dragstart", (e) => {
  e.dataTransfer.setData("text/plain", "hello");
  e.dataTransfer.setData("application/json", JSON.stringify({ id: 42 }));
});

多种 MIME 类型

将同一载荷存储为多种类型，可以让拖拽具备互操作性：纯文本可在任何文本编辑器中使用，统一资源标识符列表会被浏览器识别为 URL，HTML 可在文字处理器中保留格式。目标会选择它能够理解的类型。

放置事件之外的读取限制

出于隐私考虑，浏览器只会通过 e.dataTransfer.types 向拖入和拖拽经过处理程序公开类型列表，而不会公开具体值。只有在接受该操作的目标的放置事件中，才能读取实际数据。

文件列表

用户从桌面拖入内容时，e.dataTransfer.files 是由文件对象组成的 FileList。对于在页面内部发起的拖拽，它为空。请将它视为检测外部文件放置以及访问文件大小、名称和类型的标准方式。

items 集合

e.dataTransfer.items 会将字符串和文件公开为 DataTransferItem 对象。每个项目都有 kind（字符串或文件）、type（MIME）以及 getAsString(cb) / getAsFile()。该集合是 files 加 getData 的现代化、类型感知替代方案。

for (const item of e.dataTransfer.items) {
  if (item.kind === "file") {
    const file = item.getAsFile();
    console.log(file.name);
  } else {
    item.getAsString((s) => console.log(item.type, s));
  }
}

effectAllowed 与 dropEffect

effectAllowed 由源元素在拖拽开始事件中设置，列出源元素支持的操作。dropEffect 由目标元素在拖拽经过事件中设置，用于从这些操作中选择一个。两者不一致时，浏览器会取消放置。

自定义拖拽图像

e.dataTransfer.setDragImage(node, x, y) 会替换默认的 ghost。请传入一个按照需要设置样式、位于屏幕外的 DOM 元素，以及光标相对于该元素的偏移量。此更改仅对当前拖拽有效。

clearData

e.dataTransfer.clearData() 会清除所有格式；clearData("text/plain") 会移除单个格式。由于每次拖拽都会创建新的 dataTransfer，因此通常不需要它，但当您开始填充数据后又决定取消操作时，它会很有用。

跨源行为

从源 A 的页面拖到源 B 的页面的文件仍然会被传递——该接口支持跨源操作。不过，接收页面只能看到源元素明确放入 dataTransfer 的内容，无法获得任意 DOM 访问权限。

从浏览器拖到桌面

通过写入“DownloadURL”类型（setData("DownloadURL", "image/png:filename.png:https://...")），页面可以让用户将文件从浏览器拖到桌面。浏览器支持有限（基于 Chromium 的浏览器），因此请进行检测并优雅地回退。

知识检查

为什么不允许 dataTransfer.getData() 在 dragover 事件期间返回实际存储的值？

总结

dataTransfer 是拖动源与放置目标之间的桥梁。对于带类型的字符串载荷，请使用 setData/getData；对于统一查看文件和字符串，请使用 items；对于从桌面放置的内容，请使用 files；对于自定义预览，请使用 setDragImage；并使用 effectAllowed/dropEffect 协商操作类型。

常见问题解答

「dataTransfer 对象」课时是免费的吗？

是的 — 「dataTransfer 对象」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 HTML Academy 课程的其余内容，请升级到 CoddyKit PRO。 HTML Academy 课程共包含 4 节课。

「dataTransfer 对象」这节课中我会学到什么？

在拖动源和放置目标之间传输数据你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 HTML Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「dataTransfer 对象」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 HTML Academy 课中编写并运行代码吗？

能。每节 HTML Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 HTML Academy