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

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

Thomas Steiner

網頁應用程式現在可以讀取及寫入檔案，因此下一個合理的步驟就是讓開發人員將這些網頁應用程式宣告為應用程式可建立及處理的檔案檔案處理常式。您可以使用 File Handling API 執行這項操作。將文字編輯器應用程式註冊為檔案處理常式並安裝後，您可以在 macOS 上按一下 .txt 檔案的滑鼠右鍵，然後選取「取得資訊」，即可指示作業系統，預設情況下應使用此應用程式開啟 .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.
    }
  });
}

開發人員工具支援

在撰寫本文時，DevTools 不支援這項功能，但我已提出功能要求，希望能新增相關支援。

示範

我已為卡通風格的繪圖應用程式 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 授予特定檔案存取權，而非透過網頁應用程式顯示的檔案挑選器。

但使用者仍有可能在開啟檔案時，不小心授予網頁應用程式檔案存取權。不過，一般來說，開啟檔案會讓開啟檔案的應用程式讀取及/或操作該檔案。因此，使用者明確選擇在已安裝的應用程式中開啟檔案 (例如透過「Open with…」內容選單)，可視為對應用程式信任的信號。

預設處理常式的挑戰

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

使用者控制項

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

透明度

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

意見回饋

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

請告訴我們 API 設計

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

• 在對應的 GitHub 存放區中提出規格問題，或在現有問題中加入您的想法。

回報導入問題

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

• 請前往 new.crbug.com 提交錯誤。請務必提供盡可能多的詳細資料、重現問題的簡單操作說明，並在「元件」方塊中輸入 UI>Browser>WebAppInstalls>FileHandling。

顯示 API 支援

您打算使用 File Handling API 嗎？您的公開支持有助於 Chrome 團隊決定功能優先順序，並向其他瀏覽器供應商顯示支援這些功能的重要性。

• 請在 WICG Discourse 討論串中分享您打算如何使用該功能。
• 使用主題標記 #FileHandling 發送推文給 @ChromiumDev，告訴我們你在何處使用這項功能，以及使用方式。

實用連結

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

特別銘謝

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