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

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

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

以下列舉可能使用此 API 的網站:

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

如何使用 File Handling API

漸進增強

每個 File Handling API 不能為聚合。不過,您可以透過其他兩種方式開啟檔案:

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

瀏覽器支援

瀏覽器支援

  • Chrome:102。
  • Edge:102。
  • Firefox:不支援。
  • Safari:不支援。

資料來源

特徵偵測

如要檢查系統是否支援 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」來開啟檔案。請參閱原始碼中的實作

顯示 Excalidraw 檔案的 macOS Finder 視窗。
在作業系統的檔案總管中,按兩下或按一下滑鼠右鍵選取檔案。
在檔案上按一下滑鼠右鍵,並且以方框特別標出「開啟方式... 擴展」項目,即可顯示內容選單。
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>FileHandlingGlitch 非常適合用於快速且輕鬆地分享重現內容。

顯示 API 支援

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

實用連結

特別銘謝

File Handling API 是由 Eric WilligersJay HarrisRaymes Khoury 指定。本文由 Joe Medley 審查。