使用 DataTransfer API 打破障碍

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

Jorik Tangelder
Jorik Tangelder
X GitHub 首页
Thomas Steiner

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

浏览器支持

  • Chrome：3.
  • Edge：12。
  • Firefox：3.5。
  • Safari：4.

来源

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

浏览器内置的拖放和复制-粘贴互动都可以与其他应用、网络或其他方式进行通信，并且不与任何源相关联。该 API 支持多个数据条目，并且根据数据的接收位置而具有不同的行为。在监听传入事件时，您的 Web 应用可以发送和接收传输的数据。

此功能可以改变我们对桌面 Web 应用中的共享和互操作性的看法。在应用之间传输数据不再需要依赖紧密耦合的集成。相反，您可以向用户提供完全控制，以将数据转移到他们希望的任何位置。

DataTransfer API 支持的互动示例。（视频不含音频。）

传输数据

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

通过提供 MIME 类型键控数据，您可以自由与外部应用交互。 大多数所见即所得编辑器、文本编辑器和浏览器都会响应以下示例中使用的“原初”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 元素和富文本 (WYSIWYG) 编辑器中（如 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 进行复制和粘贴互动如下所示。请注意，对于剪贴板事件，名为 clipboardData 的属性会返回 DataTransfer 对象。

// 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。