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

使用 Web Share Target API 簡化行動裝置和電腦上的分享功能

在行動裝置或電腦上,分享應該就像是直接點選「Share」按鈕、選擇應用程式,並選擇要分享內容的對像一樣。舉例來說,您可能想分享一篇有趣的文章,可以透過電子郵件傳送給朋友,或在推特上分享給全世界。

過去,只有特定平台的應用程式可以向作業系統註冊,以便接收來自其他已安裝應用程式的分享內容。不過,透過 Web Share Target API,已安裝的網頁應用程式可以向底層作業系統註冊為分享目標,以便接收分享內容。

Android 手機顯示「分享方式」導覽匣。
將已安裝 PWA 做為選項的系統層級共用目標挑選器。

查看 Web Share Target 的實際應用

  1. 使用 Android 版 Chrome 76 以上版本,或電腦版 Chrome 89 以上版本,開啟 Web Share Target 示範
  2. 系統提示時,請按一下「安裝」將應用程式新增至主畫面,或使用 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 使用 "POST",並為 enctype 使用 "multipart/form-data"

{
  "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 做為電子郵件主旨撰寫新的電子郵件,其中 texturl 會串連為內文。
  • 社交網路應用程式可以使用 text 做為訊息的內文,並新增 url 做為連結,然後草擬一則忽略 title 的新貼文。如果缺少 text,應用程式可能也會在內容中使用 url。如果缺少 url,應用程式可能會掃描 text,尋找網址並將其新增為連結。
  • 相片分享應用程式可以使用 title 做為幻燈片標題、text 做為說明,以及 files 做為幻燈片圖片,建立新的幻燈片。
  • 簡訊應用程式可以使用 texturl 連結在一起,並捨棄 title,以草擬新訊息。

處理 GET 分享

如果使用者選取您的應用程式,且 method"GET" (預設值),瀏覽器會在 action 網址開啟新視窗。瀏覽器會使用資訊清單中提供的網址編碼值,產生查詢字串。舉例來說,如果共用應用程式提供 titletext,則查詢字串為 ?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'));
});

請務必使用服務工作者預先快取 action 頁面,讓網頁能快速載入且可靠運作,即使使用者處於離線狀態也一樣。Workbox 是一項工具,可協助您在 Service Worker 中實作預先快取

處理 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 發送推文給 @ChromiumDev,告訴我們你在何處使用這項功能,以及使用方式。