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

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

Thomas Steiner

既然網頁應用程式現在能夠讀取及寫入檔案，下一步就是允許開發人員將這些極少數的網頁應用程式宣告為檔案處理常式，供應用程式建立和處理的檔案。File Handling API 可讓您進行這項操作。將文字編輯器應用程式註冊為檔案處理常式後，您可以在安裝之後，在 macOS 的 .txt 檔案上按一下滑鼠右鍵並選取「Get Info」，指示 OS 應一律以這個應用程式開啟 .txt 檔案做為預設值。

File Handling API 建議用途

可能使用此 API 的網站範例包括：

• Office 應用程式，例如文字編輯器、試算表應用程式和投影播放建立者。
• 圖形編輯器和繪圖工具：
• 電玩遊戲關卡編輯器工具。

如何使用 File Handling API

漸進式增強

無法以折線形式處理「File Handling API」但是，使用網頁應用程式開啟檔案的功能可透過另外兩種方式完成：

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

瀏覽器支援

瀏覽器支援

• 102
• 102
• x
• x

資料來源

功能偵測

如要查看是否支援 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) 檔案，以及經建構的 Grafr 檔案格式，且 .grafr、.graf 或 .graph 做為 /open-graf 的副檔名。前兩個用戶端會在單一用戶端中開啟，如果處理多個檔案，則前兩個用戶端中的最後一個用戶端會開啟。

注意：此宣告必須安裝應用程式。您可以參閱這個網站系列文章，進一步瞭解如何將應用程式設為可安裝。

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

在作業系統的檔案總管中，按兩下檔案或在檔案上按一下滑鼠右鍵。

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 將 Tweet 訊息傳送至 @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 審查。