使用 DataTransfer API 打破障碍

允许用户在浏览器窗口之外共享数据。

Jorik Tangelder

Thomas Steiner

您可能听说过 DataTransfer API，它是 HTML5 拖放 API 和剪贴板事件的一部分。它可用于在源和接收目标之间传输数据。

拖放和复制粘贴互动通常用于页面内的互动，用于将简单文本从 A 转移到 B。但人们往往忽略的是，这些互动功能还可以用于超越浏览器窗口。

浏览器的内置拖放和复制-粘贴互动都可以与其他应用（网络应用或其他应用）进行通信，并且不受任何来源的约束。该 API 支持多个数据条目，这些数据条目的行为因数据传输到的位置而异。在监听传入事件时，您的 Web 应用可以发送和接收传输的数据。

这项功能可以改变我们对桌面设备上 Web 应用中分享和互操作性的看法。在应用之间传输数据不再需要依赖于紧密耦合的集成。您可以让用户完全掌控数据传输，将数据传输到他们喜欢的任何位置。

传输数据

首先，您需要实现拖放或复制粘贴功能。以下示例展示了拖放互动，但复制粘贴的过程类似。如果您不熟悉拖放 API，可以参阅介绍 HTML5 拖放的优质文章，了解相关详情。

通过提供 MIME 类型的键值对数据，您可以自由地与外部应用交互。大多数 WYSIWYG 编辑器、文本编辑器和浏览器都会响应下例中使用的“原始”MIME 类型。

document.querySelector('#dragSource')
.addEventListener('dragstart', (event) => {
  event.dataTransfer.setData('text/plain', 'Foo bar');
  event.dataTransfer.setData('text/html', '<h1>Foo bar</h1>');
  event.dataTransfer.setData('text/uri-list', 'https://example.com');
});

请注意 event.dataTransfer 属性。这将返回一个 DataTransfer 实例。如您所见，具有其他名称的属性有时也会返回此对象。

接收数据传输的方式与提供数据传输的方式几乎相同。监听接收事件 (drop 或 paste) 并读取按键。在拖动某个元素时，浏览器只能访问数据的 type 键。只有在数据被舍弃后，才能访问数据本身。

document.querySelector('#dropTarget')
.addEventListener('dragover', (event) => {
  console.log(event.dataTransfer.types);
  // Without this, the drop event won't fire.
  event.preventDefault();
});

document.querySelector('#dropTarget')
.addEventListener('drop', (event) => {
  // Log all the transferred data items to the console.
  for (let type of event.dataTransfer.types) {
    console.log({ type, data: event.dataTransfer.getData(type) });
  }
  event.preventDefault();
});

以下三种 MIME 类型在各应用中都广泛受支持：

• text/html：在 contentEditable 元素和富文本（所见即所得）编辑器（例如 Google 文档、Microsoft Word 等）中呈现 HTML 载荷。
• text/plain: 设置输入元素的值、代码编辑器的内容以及 text/html 的回退。
• text/uri-list：将网址拖放到网址栏或浏览器页面时，系统会导航到该网址。将文件拖放到目录或桌面上时，系统会创建一个网址快捷方式。

由于 WYSIWYG 编辑器广泛采用 text/html，因此它非常有用。与 HTML 文档一样，您可以使用数据网址或公开可访问网址嵌入资源。这非常适合将视觉内容（例如从画布）导出到 Google 文档等编辑器。

const redPixel = 'data:image/gif;base64,R0lGODdhAQABAPAAAP8AAAAAACwAAAAAAQABAAACAkQBADs=';
const html = '<img src="' + redPixel + '" width="100" height="100" alt="" />';
event.dataTransfer.setData('text/html', html);

使用复制和粘贴功能进行转移

下面展示了如何将 DataTransfer API 与复制粘贴互动搭配使用。请注意，对于剪贴板事件，DataTransfer 对象由名为 clipboardData 的属性返回。

// Listen to copy-paste events on the document.
document.addEventListener('copy', (event) => {
  const copySource = document.querySelector('#copySource');
  // Only copy when the `activeElement` (i.e., focused element) is,
  // or is within, the `copySource` element.
  if (copySource.contains(document.activeElement)) {
    event.clipboardData.setData('text/plain', 'Foo bar');
    event.preventDefault();
  }
});

document.addEventListener('paste', (event) => {
  const pasteTarget = document.querySelector('#pasteTarget');
  if (pasteTarget.contains(document.activeElement)) {
    const data = event.clipboardData.getData('text/plain');
    console.log(data);
  }
});

自定义数据格式

您可以使用任何键来标识传输的数据，而不限于基元 MIME 类型。这对于应用中的跨浏览器互动很有用。如以下所示，您可以使用 JSON.stringify() 和 JSON.parse() 函数传输更复杂的数据。

document.querySelector('#dragSource')
.addEventListener('dragstart', (event) => {
  const data = { foo: 'bar' };
  event.dataTransfer.setData('my-custom-type', JSON.stringify(data));
});

document.querySelector('#dropTarget')
.addEventListener('dragover', (event) => {
  // Only allow dropping when our custom data is available.
  if (event.dataTransfer.types.includes('my-custom-type')) {
    event.preventDefault();
  }
});

document.querySelector('#dropTarget')
.addEventListener('drop', (event) => {
  if (event.dataTransfer.types.includes('my-custom-type')) {
    event.preventDefault();
    const dataString = event.dataTransfer.getData('my-custom-type');
    const data = JSON.parse(dataString);
    console.log(data);
  }
});

连接网络

虽然自定义格式非常适合您控制的应用之间进行通信，但在将数据传输到不使用您格式的应用时，也会限制用户。如果您想与网络上的第三方应用建立连接，则需要使用通用数据格式。

JSON-LD（链接数据）标准非常适合此用途。它体积轻巧，易于在 JavaScript 中读取和写入。Schema.org 包含许多可用的预定义类型，您也可以选择使用自定义架构定义。

const data = {
  '@context': 'https://schema.org',
  '@type': 'ImageObject',
  contentLocation: 'Venice, Italy',
  contentUrl: 'venice.jpg',
  datePublished: '2010-08-08',
  description: 'I took this picture during our honey moon.',
  name: 'Canal in Venice',
};
event.dataTransfer.setData('application/ld+json', JSON.stringify(data));

使用 Schema.org 类型时，您可以先使用通用的 Thing 类型，也可以使用更贴近您用例的类型，例如 Event、Person、MediaObject、Place，甚至在需要时使用 MedicalEntity 等极其具体的类型。使用 TypeScript 时，您可以使用 schema-dts 类型定义中的接口定义。

通过传输和接收 JSON-LD 数据，您将支持构建更具连通性和开放性的网络。通过使用同一种语言的应用，您可以与外部应用实现深度集成。无需进行复杂的 API 集成；所需的所有信息都包含在传输的数据中。

想象一下在任何（网络）应用之间无限制地传输数据的所有可能性：将日历中的活动分享到您喜爱的 ToDo 应用、将虚拟文件附加到电子邮件、分享联系人。这样就太棒了，对吗？这一切都始于您！🙌

问题

虽然 DataTransfer API 现已推出，但在集成之前，您需要注意以下事项。

浏览器兼容性

桌面浏览器都非常支持上述技术，而移动设备则不支持。我们已在所有主流浏览器（Chrome、Edge、Firefox、Safari）和操作系统（Android、ChromeOS、iOS、macOS、Ubuntu Linux 和 Windows）上测试过此技术，但遗憾的是，Android 和 iOS 未通过测试。虽然浏览器在不断发展，但目前此技术仅适用于桌面浏览器。

曝光度

拖放和复制粘贴是桌面计算机上的工作系统级交互，其渊源可追溯到 40 多年前的第一个 GUI。想想您使用这些互动来整理文件的次数。这种情况在 Web 上还不常见。

您需要向用户介绍这种新交互方式，并设计出用户体验模式来让用户能够识别这种交互方式，尤其是对于目前仅使用移动设备的用户。

无障碍

拖放操作的易用性不高，但 DataTransfer API 也支持复制和粘贴。请务必监听复制-粘贴事件。添加此信息不需要额外的工作，您的用户会感谢您添加此信息。

安全和隐私设置

在使用该技术时，您应注意一些安全和隐私注意事项。

• 剪贴板数据可供用户设备上的其他应用使用。
• 您拖动过来的 Web 应用可以访问类型键，但无法访问数据。只有在拖放或粘贴时，数据才会显示。
• 应将收到的数据视为任何其他用户输入；在使用前进行排错和验证。

Transmat 辅助库使用入门

您是否很期待在应用中使用 DataTransfer API？不妨考虑查看 GitHub 上的 Transmat 库。此开源库可统一浏览器差异、提供 JSON-LD 实用程序，包含用于响应传输事件以突出显示拖放区域的观察器，并让您能够在现有拖放实现中集成数据传输操作。

import { Transmat, TransmatObserver, addListeners } from 'transmat';

// Send data on drag/copy.
addListeners(myElement, 'transmit', (event) => {
  const transmat = new Transmat(event);
  transmat.setData({
    'text/plain': 'Foobar',
    'application/json': { foo: 'bar' },
  });
});

// Receive data on drop/paste.
addListeners(myElement, 'receive', (event) => {
  const transmat = new Transmat(event);
  if (transmat.hasType('application/json') && transmat.accept()) {
    const data = JSON.parse(transmat.getData('application/json'));
  }
});

// Observe transfer events and highlight drop areas.
const obs = new TransmatObserver((entries) => {
  for (const entry of entries) {
    const transmat = new Transmat(entry.event);
    if (transmat.hasMimeType('application/json')) {
      entry.target.classList.toggle('drag-over', entry.isTarget);
      entry.target.classList.toggle('drag-active', entry.isActive);
    }
  }
});
obs.observe(myElement);

致谢

主打图片由 Luba Ertel 提供，来自 Unsplash。