運用 DataTransfer API 打破藩籬

允許使用者在瀏覽器視窗外分享資料。

Jorik Tangelder
Jorik Tangelder
X GitHub 首頁
Thomas Steiner

您可能聽過 DataTransfer API，這是 HTML5 Drag and Drop API 和 Clipboard 事件的一部分。可用於在來源和接收目標之間轉移資料。

Browser Support

  • Chrome: 3.
  • Edge: 12.
  • Firefox: 3.5.
  • Safari: 4.

Source

拖曳和複製貼上互動通常用於頁面內的互動，可將簡單文字從 A 轉移至 B。但往往會被忽略的是，這些互動也能用於瀏覽器視窗以外的用途。

瀏覽器的內建拖曳功能和複製貼上互動可與其他應用程式 (無論是網路或其他應用程式) 通訊，且不受任何來源限制。API 支援多個資料項目，並根據資料傳輸目的地提供不同行為。網路應用程式在監聽傳入事件時，可以傳送及接收轉移的資料。

這項功能可能會改變我們對桌機網頁應用程式分享和互通性的想法。應用程式之間傳輸資料時，不再需要緊密整合。您可以改為讓使用者完全控管資料，並將資料轉移到任何位置。

以下是可透過 DataTransfer API 進行互動的範例。(影片不含聲音。)

轉移資料

如要開始使用，請先實作拖曳或複製貼上功能。以下範例顯示拖曳互動，但複製貼上的程序類似。如果您不熟悉 Drag and Drop 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 元素和 RTF (所見即所得) 編輯器 (例如 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 整合，因為所有必要資訊都包含在轉移的資料中。

您可以盡情發揮創意，在任何 (網頁) 應用程式之間轉移資料，完全不受限制：將日曆中的活動分享到您喜愛的待辦事項應用程式、將虛擬檔案附加到電子郵件，以及分享聯絡人。這樣不是很棒嗎？這一切就從你開始！🙌

疑慮

雖然 DataTransfer API 現已推出，但整合前請注意下列事項。

瀏覽器相容性

電腦版瀏覽器都非常支援上述技術，但行動裝置不支援。這項技術已在所有主流瀏覽器 (Chrome、Edge、Firefox、Safari) 和作業系統 (Android、ChromeOS、iOS、macOS、Ubuntu Linux 和 Windows) 上測試，但很遺憾的是，Android 和 iOS 未通過測試。雖然瀏覽器持續發展，但目前這項技術僅限於桌機瀏覽器。

爭取曝光機會

在桌上型電腦上作業時，拖曳和複製貼上是系統層級的互動，其根源可追溯至 40 多年前的第一個 GUI。想想您使用這些互動整理檔案的次數。這在網路上還不常見。

您需要向使用者說明這項新互動方式，並設計使用者體驗模式，讓使用者能辨識這項功能，尤其是過去只使用過行動裝置的人。

無障礙設定

拖曳並非非常容易存取的互動方式，但 DataTransfer API 也適用於複製及貼上。 請務必監聽複製貼上事件。這項作業不會增加太多工作量，而且使用者會感謝您新增這項功能。

安全性和隱私權

使用這項技術時，請注意一些安全性與隱私權考量。

  • 使用者裝置上的其他應用程式可以存取剪貼簿資料。
  • 拖曳的網頁應用程式可存取型別鍵，但無法存取資料。資料只會在放置或貼上時提供。
  • 收到的資料應視為任何其他使用者輸入內容，使用前請先清除及驗證。

開始使用 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。