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

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

Thomas Steiner

現在網頁應用程式可以讀取及寫入檔案，因此接下來的合理步驟是讓開發人員將這些網頁應用程式宣告為檔案處理常式，以便處理應用程式可建立及處理的檔案。File Handling API 正好能做到這一點。將文字編輯器應用程式註冊為檔案處理常式並安裝後，您可以在 macOS 上對 .txt 檔案按一下滑鼠右鍵，然後選取「取得資訊」，指示作業系統一律以這個應用程式開啟 .txt 檔案。

File Handling API 的建議用途

可能使用這項 API 的網站包括：

Office 應用程式，例如文字編輯器、試算表應用程式和投影片製作工具。
圖像編輯器和繪圖工具。
電玩遊戲關卡編輯器工具。

如何使用 File Handling API

漸進增強

File Handling API 本身無法進行 Polyfill。不過，您還是可以透過其他兩種方式，使用網路應用程式開啟檔案：

開發人員可透過 Web Share Target API 將應用程式指定為分享目標，以便從作業系統的分享工作表開啟檔案。
File System Access API 可與檔案拖曳功能整合，因此開發人員可以在已開啟的應用程式中處理拖曳的檔案。

瀏覽器支援

Browser Support

Source

特徵偵測

如要檢查是否支援 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 類型物件做為鍵，副檔名清單做為值。
含有 ImageResource 圖示陣列的 "icons" 屬性。部分作業系統允許檔案類型關聯顯示的圖示，不只是相關聯的應用程式圖示，而是與該檔案類型搭配應用程式使用相關的特殊圖示。
"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 檔案格式，副檔名為 .grafr、.graf 或 .graph。前兩個檔案會開啟在單一用戶端中，最後一個檔案則會開啟在多個用戶端中 (如果處理多個檔案)。

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」。您可以在原始碼中查看實作項目。

macOS Finder 視窗，內含 Excalidraw 檔案。 — 在作業系統的檔案總管中，按兩下或按一下滑鼠右鍵。

在檔案上按一下滑鼠右鍵時顯示的內容選單，並醒目顯示「Open with… Excalidraw」項目。 — Excalidraw 是 `.excalidraw` 檔案的預設檔案處理常式。

安全性

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

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

為確保使用者信任度及使用者檔案安全，File Handling API 開啟檔案時，系統會先顯示權限提示，PWA 才能查看檔案。使用者選取 PWA 開啟檔案後，系統會立即顯示這項權限提示，因此權限與使用 PWA 開啟檔案的動作緊密相關，更容易瞭解且切合需求。

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

系統偵測到資訊清單更新和 "file_handlers" 區段的變更時，權限就會重設。

檔案相關挑戰

允許網站存取檔案會開啟許多類別的攻擊向量。如需相關資訊，請參閱這篇文章。相較於 File System Access API，File Handling API 提供額外的安全性相關功能，可透過作業系統的內建 UI 授予特定檔案的存取權，而非透過網頁應用程式顯示的檔案挑選器。

使用者開啟檔案時，仍可能不慎授予網頁應用程式存取權。不過，一般來說，開啟檔案會允許開啟檔案的應用程式讀取和/或操控該檔案。因此，使用者明確選擇在已安裝的應用程式中開啟檔案 (例如透過「選擇開啟工具...」內容選單)，可視為對該應用程式的信任訊號。

預設處理常式挑戰

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

使用者控制項

規格指出，瀏覽器不應將每個可處理檔案的網站註冊為檔案處理常式。因此，檔案處理註冊應在安裝後進行，且絕不能在沒有使用者明確確認的情況下發生，尤其是網站要成為預設處理常式時。網站應考慮自行製作擴充功能，而不是劫持現有擴充功能，例如使用者可能已為其註冊預設處理常式的 .json。

透明度

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

意見回饋

Chrome 團隊很想瞭解您使用 File Handling API 的體驗。

介紹 API 設計

API 是否有任何功能無法如預期運作？或者，是否有缺少的屬性或方法需要實作，才能實現您的想法？對安全模型有任何問題或意見嗎？

在對應的 GitHub 存放區中提出規格問題，或在現有問題中新增想法。

回報導入問題

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

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

支援 API

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

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

實用連結

特別銘謝

File Handling API 由 Eric Willigers、 Jay Harris 和 Raymes Khoury 指定。本文由喬伊·梅德利審查。