允許安裝的網頁應用程式成為檔案處理常式

使用作業系統，將應用程式註冊為檔案處理常式。

Thomas Steiner

網頁應用程式現在可以讀取及寫入檔案，因此下一個合理的步驟就是讓開發人員將這些網頁應用程式宣告為應用程式可建立及處理的檔案檔案處理常式。File Handling API 可以用來達成目的。將文字編輯器應用程式註冊為檔案處理常式，並在安裝完成後，在 macOS 的 .txt 檔案上按一下滑鼠右鍵並選取「Get Info」，即可指示 OS 一律使用這個應用程式開啟 .txt 檔案做為預設值。

File Handling API 的建議用途

以下是可能會使用這個 API 的網站：

• 辦公室應用程式，例如文字編輯器、試算表應用程式和簡報製作工具。
• 圖形編輯器和繪圖工具。
• 電玩遊戲關卡編輯器工具。

如何使用 File Handling API

漸進增強

File Handling API 本身無法進行多重填充。不過，您可以透過其他兩種方式開啟檔案：

• Web Share Target API 可讓開發人員將應用程式指定為共用目標，讓使用者可以透過作業系統的共用工作表開啟檔案。
• File System Access API 可與檔案拖曳功能整合，讓開發人員在已開啟的應用程式中處理已放置的檔案。

瀏覽器支援

特徵偵測

如要檢查是否支援 File Handling API，請使用以下方法：

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  // The File Handling API is supported.
}

File Handling API 的宣告式部分

首先，網頁應用程式需要在網頁應用程式資訊清單中宣告可處理的檔案類型。File Handling API 會透過名為 "file_handlers" 的新屬性擴充網頁應用程式資訊清單，該屬性可接受檔案處理常式的陣列。檔案處理常式是一個物件，具備下列屬性：

• "action" 屬性，指向應用程式範圍內的網址做為值。
• "accept" 屬性，其值包含 MIME 類型的物件，做為索引鍵，並使用副檔名清單做為值。
• "icons" 屬性，其中包含 ImageResource 圖示的陣列。部分作業系統允許檔案類型關聯顯示的圖示不只是關聯應用程式圖示，而是與應用程式使用該檔案類型相關的特殊圖示。
• "launch_type" 屬性，用於定義是否應在單一用戶端或多個用戶端中開啟多個檔案。預設為 "single-client"。如果使用者開啟多個檔案，且檔案處理常式已加上 "multiple-clients" 做為 "launch_type" 註解，就會觸發多個應用程式啟動，且在每次啟動時，LaunchParams.files 陣列 (請參閱「繼續」) 只會有一個元素。

以下範例只顯示網頁應用程式資訊清單的相關摘錄，應力求更清楚明確：

{
  "file_handlers": [
    {
      "action": "/open-csv",
      "accept": {
        "text/csv": [".csv"]
      },
      "icons": [
        {
          "src": "csv-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-svg",
      "accept": {
        "image/svg+xml": ".svg"
      },
      "icons": [
        {
          "src": "svg-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-graf",
      "accept": {
        "application/vnd.grafr.graph": [".grafr", ".graf"],
        "application/vnd.alternative-graph-app.graph": ".graph"
      },
      "icons": [
        {
          "src": "graf-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "multiple-clients"
    }
  ]
}

這適用於假設的應用程式，可處理 /open-csv 中的逗號分隔值 (.csv) 檔案、/open-svg 中的可調整向量圖形 (.svg) 檔案，以及 /open-graf 中以 .grafr、.graf 或 .graph 為副檔名的虛構 Grafr 檔案格式。前兩個會在單一用戶端中開啟；如果處理多個檔案，最後一個用戶端會在多個用戶端中開啟。

File Handling API 是必備部分

理論上，應用程式已宣告可在哪個範圍內的網址處理哪些檔案，因此在實際操作中，它必須對傳入的檔案執行某些操作。這時 launchQueue 就能派上用場。如要存取已啟動的檔案，網站必須為 window.launchQueue 物件指定消費者。啟動作業會排入佇列，直到指定的使用者處理為止，每次啟動時只會叫用一次。無論消費者何時指定，每個啟動作業都會處理。

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  launchQueue.setConsumer((launchParams) => {
    // Nothing to do when the queue is empty.
    if (!launchParams.files.length) {
      return;
    }
    for (const fileHandle of launchParams.files) {
      // Handle the file.
    }
  });
}

開發人員工具支援

撰寫本文時，我們不提供開發人員工具支援，但我已提出功能要求，支援新增支援。

示範

我已為卡通風格的繪圖應用程式 Excalidraw 新增檔案處理支援功能。如要測試，您必須先安裝 Excalidraw。當您之後使用該檔案建立檔案並將其儲存在檔案系統的其他位置時，可以透過按兩下或按一下滑鼠右鍵，在內容選單中選取「Excalidraw」。您可以查看原始碼中的實作。

安全性

Chrome 團隊根據「控管強大網路平台功能的存取權」一文中定義的核心原則，設計並實作 File Handling API，包括使用者控制、透明度和人體工學。

權限、權限持續性和檔案處理常式更新

為確保使用者信任，並保護使用者的檔案安全，當 File Handling API 開啟檔案時，系統會先顯示權限提示，然後才允許 PWA 查看檔案。使用者選取 PWA 來開啟檔案後，系統就會顯示這則權限提示，讓權限與使用 PWA 開啟檔案的動作緊密結合，讓使用者更容易瞭解並與其相關。

直到使用者點選「允許」或「封鎖」網站檔案處理，或是忽略提示三次 (之後 Chromium 就會禁止使用這項權限)，這項權限都會一再顯示。所選設定會在 PWA 關閉及重新開啟時保留。

一旦偵測到資訊清單更新和 "file_handlers" 部分的變更，權限就會重設。

檔案相關挑戰

允許網站存取檔案會開啟多種攻擊媒介。請參閱 File System Access API 相關文章，瞭解這些權限。File Handling API 比 File System Access API 提供更多安全相關功能，例如透過作業系統內建的 UI 授予特定檔案存取權，而非透過網頁應用程式顯示的檔案挑選器。

但使用者仍有可能在開啟檔案時，不小心授予網頁應用程式檔案存取權。但是，通常知道開啟檔案會允許用來開啟檔案的應用程式讀取和/或操控該檔案。因此，對於在已安裝的應用程式中開啟檔案 (例如透過「使用...開啟...」內容選單) 的明確選擇，系統可以視為在應用程式中具有充分的信任信號。

預設處理常式驗證問題

例外狀況是，在主機系統上沒有特定檔案類型的應用程式時。在這種情況下，部分主機作業系統可能會自動將新註冊的處理常式提升為該檔案類型的預設處理常式，且不會在使用者未干預設的情況下執行。也就是說，如果使用者雙擊這類檔案，系統會自動在已註冊的網路應用程式中開啟該檔案。在這種主機作業系統上，如果使用者代理程式判斷該檔案類型沒有現有的預設處理常式，可能就需要顯示明確的權限提示，以免在未經使用者同意的情況下，不小心將檔案內容傳送至網路應用程式。

使用者控制項

這項規格要求瀏覽器不應註冊所有可將檔案做為檔案處理常式的網站註冊。相反地，檔案處理註冊應在安裝後才會啟用，且必須經過使用者明確確認才會生效，特別是如果網站要成為預設處理常式時。網站應考慮自行建立擴充功能，而非劫持現有的擴充功能 (例如 .json)，因為使用者可能已為該擴充功能註冊預設處理常式。

透明度

所有作業系統都允許使用者變更目前的檔案關聯。這不在瀏覽器的範圍內。

意見回饋

Chrome 團隊希望瞭解您使用 File Handling API 的體驗。

請說明 API 設計

API 是否有任何部分無法正常運作？或者，您是否缺少實作想法所需的方法或屬性？您對安全性模型有疑問或意見嗎？

• 在對應的 GitHub 存放區上提出規格問題，或將您的想法新增至現有問題。

回報實作問題

你是否發現 Chrome 實作項目有錯誤？或者實作方式與規格不同？

• 請前往 new.crbug.com 提交錯誤。請務必提供盡可能多的詳細資料、簡單的重現操作說明，並在「元件」方塊中輸入 UI>Browser>WebAppInstalls>FileHandling。Glitch 非常適合用於快速且輕鬆地分享重現內容。

顯示 API 支援

您打算使用 File Handling API 嗎？您的公開支援可協助 Chrome 團隊優先採用特定功能，以及向其他瀏覽器廠商說明支援這些功能的重要性。

• 歡迎前往 WICG Discourse 討論串，說明這項工具的運用方式。
• 使用主題標記 #FileHandling 將推文傳送到 @ChromiumDev，並告訴我們您在哪裡使用它。

實用連結

• 公開說明
• File Handling API 示範 | File Handling API 示範來源
• Chromium 追蹤錯誤
• ChromeStatus.com 項目
• 閃爍元件：UI>Browser>WebAppInstalls>FileHandling
• TAG 審查
• Mozilla 標準定位

特別銘謝

File Handling API 是由 Eric Willigers、Jay Harris 和 Raymes Khoury 指定。本文由 Joe Medley 審查。