透過 Web Share Target API 接收共用資料

使用 Web Share Target API，輕鬆在行動裝置和電腦上分享內容

Pete LePage
Joe Medley
Joe Medley
GitHub

在行動裝置或電腦上，分享方式應非常簡單：按一下「Share」按鈕、選擇應用程式和選擇分享對象。舉例來說，您可能會想透過電子郵件將有趣的文章分享給朋友，或透過 Twitter 推文給全世界。

過去，只有特定平台的應用程式才能向作業系統註冊，以便接收來自其他已安裝應用程式的分享次數。但是透過 Web Share Target API，安裝的網頁應用程式可以向基礎作業系統註冊，做為接收共用內容的共用目標。

已開啟「分享方式」導覽匣的 Android 手機。
系統層級與已安裝 PWA 的系統層級共用目標挑選器選項。

查看網頁分享目標實際運作情形

  1. 使用 Android 76 以上版本 Android 版，或是電腦版 Chrome 89 以上版本，開啟網頁分享目標示範。
  2. 出現提示時，按一下「Install」將應用程式新增到主畫面，或使用 Chrome 選單將應用程式新增至主畫面。
  3. 開啟任何支援分享功能的應用程式，或使用試用版應用程式中的「分享」按鈕。
  4. 在目標選擇器中，選擇「Web Share Test」。

分享完成後，您應該會在網路分享目標網頁應用程式中看到所有分享的資訊。

將應用程式註冊為共用目標

應用程式必須符合 Chrome 的安裝條件，才能將應用程式註冊為共用目標。此外，使用者必須將其新增至主畫面，才能分享到您的應用程式。如此可防止網站將自己自動加入使用者的共用意圖選擇器，並確保共用對像想透過您的應用程式進行共用。

更新網頁應用程式資訊清單

如要將應用程式註冊為共用目標，請在應用程式的網頁應用程式資訊清單中加入 share_target 項目。藉此告知作業系統將您的應用程式納入意圖選擇器中。您新增至資訊清單的內容會決定應用程式接受的資料。以下為 share_target 項目的常見情境：

  • 接受基本資訊
  • 正在接受申請變更
  • 接受檔案

接受基本資訊

如果目標應用程式僅接受資料、連結和文字等基本資訊，請在 manifest.json 檔案中加入以下內容：

"share_target": {
  "action": "/share-target/",
  "method": "GET",
  "params": {
    "title": "title",
    "text": "text",
    "url": "url"
  }
}

如果應用程式已有共用網址配置，您可以將 params 值替換為現有的查詢參數。舉例來說，如果您的分享網址配置使用 body 而非 text，您可以將 "text": "text" 替換為 "text": "body"。

如未提供，method 值會預設為 "GET"。未在此範例中顯示的 enctype 欄位代表資料的編碼類型。在 "GET" 方法中，enctype 預設為 "application/x-www-form-urlencoded"，如果設為其他值，系統會忽略該值。

正在接受申請變更

如果共用資料會以某種方式變更目標應用程式 (例如，將書籤儲存在目標應用程式)，請將 method 值設為 "POST" 並加入 enctype 欄位。以下範例會在目標應用程式中建立書籤，因此針對 method 和 "multipart/form-data" 使用 "POST"：enctype

{
  "name": "Bookmark",
  "share_target": {
    "action": "/bookmark",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "url": "link"
    }
  }
}

接受檔案

與應用程式變更一樣，接受檔案時需要 method 為 "POST"，且 enctype 存在。此外，enctype 必須是 "multipart/form-data"，且必須新增 files 項目。

您也必須新增 files 陣列，定義應用程式可接受的檔案類型。陣列元素是包含兩個成員的項目：name 欄位和 accept 欄位。accept 欄位可接受 MIME 類型、副檔名，或包含兩者的陣列。建議您提供同時包含 MIME 類型和副檔名的陣列，因為作業系統各有不同。

{
  "name": "Aggregator",
  "share_target": {
    "action": "/cgi-bin/aggregate",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "title": "name",
      "text": "description",
      "url": "link",
      "files": [
        {
          "name": "records",
          "accept": ["text/csv", ".csv"]
        },
        {
          "name": "graphs",
          "accept": "image/svg+xml"
        }
      ]
    }
  }
}

處理收到的內容

您可以自行決定如何處理傳入的共用資料，並視應用程式而定。例如：

  • 電子郵件用戶端可以使用 title 做為電子郵件主旨草擬新的電子郵件草稿，並以 text 和 url 串連為主體。
  • 社群網路應用程式可使用 text 做為訊息內文，並新增 url 做為連結，草擬包含 title 的新訊息。如果缺少 text，應用程式也可以在主體中使用 url。如果缺少 url，應用程式可能會掃描 text 尋找網址，並將該網址新增為連結。
  • 相片共享應用程式可以使用 title 做為投影播放標題、text 做為說明，以及使用 files 做為投影播放圖片，以建立新的投影播放。
  • 文字訊息應用程式可使用 text 和 url 串連 title，草擬新訊息。

處理 GET 股份

如果使用者選取您的應用程式，且 method 為 "GET" (預設值)，瀏覽器會在 action 網址中開啟新視窗。然後，瀏覽器會使用資訊清單中提供的網址編碼值產生查詢字串。例如，如果分享應用程式提供 title 和 text，查詢字串為 ?title=hello&text=world。如要處理這種情況，請在前景頁面中使用 DOMContentLoaded 事件監聽器並剖析查詢字串：

window.addEventListener('DOMContentLoaded', () => {
  const parsedUrl = new URL(window.location);
  // searchParams.get() will properly handle decoding the values.
  console.log('Title shared: ' + parsedUrl.searchParams.get('title'));
  console.log('Text shared: ' + parsedUrl.searchParams.get('text'));
  console.log('URL shared: ' + parsedUrl.searchParams.get('url'));
});

請務必使用 Service Worker 預先快取 action 頁面，這樣即使使用者離線，網頁也能快速載入並穩定運作。Workbox 這項工具可協助您在服務工作站中實作預先快取。

正在處理 POST 分享要求

如果 method 為 "POST"，就像目標應用程式接受儲存的書籤或共用檔案一樣，傳入的 POST 要求主體會包含分享應用程式傳遞的資料，並以資訊清單中提供的 enctype 值進行編碼。

前景頁面無法直接處理這項資料。由於頁面會將資料當做要求查看，因此頁面會將資料傳送至 Service Worker，方便您使用 fetch 事件監聽器攔截資料。在此之後，您可以使用 postMessage() 將資料傳回前景頁面，或將資料傳送至伺服器：

self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  // If this is an incoming POST request for the
  // registered "action" URL, respond to it.
  if (event.request.method === 'POST' &&
      url.pathname === '/bookmark') {
    event.respondWith((async () => {
      const formData = await event.request.formData();
      const link = formData.get('link') || '';
      const responseUrl = await saveBookmark(link);
      return Response.redirect(responseUrl, 303);
    })());
  }
});

驗證共用內容

一部 Android 手機顯示內含分享內容的試用版應用程式。
共用目標應用程式範例。

請務必驗證傳入的資料。可惜的是，無法保證其他應用程式會透過正確的參數分享適當的內容。

舉例來說，在 Android 上，url 會空白，因為 Android 的共用系統不支援這個欄位。反而通常會出現在 text 欄位中，有時也會出現在 title 欄位中。

瀏覽器支援

下列是支援 Web Share Target API 的功能：

在所有平台上，您的網頁應用程式必須先安裝，然後才會顯示為接收共用資料的潛在目標。

範例應用程式

展現對 API 的支援

你打算使用 Web Share Target API 嗎？您的公開支援可協助 Chromium 團隊決定功能的優先順序，以及向其他瀏覽器廠商說明這項功能有多重要。

請使用主題標記 #WebShareTarget 將 Tweet 訊息傳送至 @ChromiumDev，並告訴我們您的使用地點和方式。