File System Access API 的永久權限

現在不必重複授予權限,就能取得檔案和資料夾的永久讀取和寫入權限。本文說明這項功能的運作方式。在深入探討細節之前,讓我們先快速回顧一下現狀和目前解決的問題。

目前方法的挑戰

File System Access API 可讓開發人員以讀取和 (選擇性) 寫入方式,存取使用者本機硬碟上的檔案。Visual Studio Code (VS Code) 是能直接在瀏覽器中執行的 Microsoft IDE,也是其他許多應用程式的熱門應用程式。當您開啟 VS Code 時,系統會顯示「Welcome」(歡迎) 畫面,您可以在畫面中建立新檔案,或是開啟現有檔案或資料夾。

Visual Studio Code 的歡迎畫面。

如果您點選「Open Folder」(開啟資料夾),然後選擇硬碟上的其中一個資料夾,瀏覽器就會詢問您是否要讓 VS Code 擁有這個資料夾的「檢視」存取權。

Visual Studio Code 要求檢視存取權。

授予存取權後,您可以瀏覽資料夾階層,並在 VS Code 的編輯器中開啟檔案。如果您要修改任何檔案,瀏覽器會詢問您是否要將該資料夾的「編輯」權限授予該資料夾。

Visual Studio Code 要求編輯權限。

如果允許,網址列中的檔案圖示就會變更,並新增一個小型向下箭頭,表示應用程式具有讀取和寫入權限。如要變更權限,請依序按一下圖示和「移除存取權」,應用程式就無法再編輯檔案。

含有網址列圖示提示的 Visual Studio Code。

存取權會持續到來源的最後一個分頁關閉。如果您關閉應用程式並再次開啟,VS Code 的「種類」可讓您接續上次中斷的地方。只要點選「Open Recent」,VS Code 會提供之前開啟的資料夾來重新開啟。

Visual Studio Code 會提供最近開啟的檔案。

但即使您先前已授予資料夾寫入權限,現在仍須再次授予存取權。這很快就會停滯不前在深入探討解決方案前,File System Access API 的永久權限。VS Code 甚至如何管理最近的資料夾?

Visual Studio Code 會在重新載入後要求編輯權限。

在 File System Access API 中,檔案和資料夾的存取權是透過 FileSystemHandle 物件管理:FileSystemFileHandle 物件,以及資料夾的 FileSystemDirectoryHandle 物件 (目錄)。兩者都可以儲存在 IndexedDB 中,這就是 VS Code 的功能。如要查看這項資訊,請開啟 Chrome 開發人員工具,然後在「Application」分頁中前往「IndexedDB」區段,然後在 vscode-web-db 資料庫中選取相關資料表 vscode-filehandles-store

Chrome 開發人員工具偵錯 Visual Studio 程式碼,顯示「IndexedDB」部分以及儲存的 FileSystemHandle。

新功能:異動項目與時間

Chrome 推出了新行為,讓使用者可選擇是否永久授予檔案和資料夾的存取權,這樣他們就不必不斷重新提示使用者。 自 Chrome 122 開始,您可以觀察到新行為。如要提早測試,請從 Chrome 120 版開始,將 chrome://flags/#file-system-access-persistent-permissionchrome://flags/#one-time-permission 這兩個標記切換為「Enabled」

首先,新行為包含新的三向權限提示,可選擇讓使用者在每次造訪時,授予應用程式對所選檔案和資料夾的存取權。

顯示三向權限提示的 Visual Studio Code。

新的三向提示有以下選項:

  • 這次允許:允許應用程式存取目前工作階段的檔案。(這與現有的行為相符)。
  • 每次造訪時允許:允許應用程式擁有無限期存取權,除非存取權遭到撤銷。應用程式獲得永久存取權後,同樣可以永久存取新開啟的檔案和資料夾。
  • 不允許:禁止應用程式存取檔案。(這對應到現有的行為)。

其次,新行為需在網站設定中新增一個部分,使用者可以透過「檔案編輯」切換按鈕旁邊的啟動圖示前往該部分。

含有檔案編輯圖示的 Visual Studio Code 網站設定。

使用者點選這個啟動圖示後,即可開啟該應用程式的「隱私權和安全性」設定,當中會列出應用程式可存取的所有檔案和資料夾的項目清單。按一下垃圾桶圖示,即可撤銷個別項目的存取權。移除個別項目的存取權,代表應用程式大致上仍可存取檔案。一般來說,如要撤銷存取權,使用者可以按一下網址列中的圖示,如上所述。

vscode.dev 網站的 Chrome 隱私權和安全性設定。

如何觸發新行為

File System Access API 沒有任何開發人員的相關變更。如要透過永久權限觸發新行為,有三種方式需要滿足不同的先決條件:

  1. 使用者上次造訪來源時,必須授予檔案或資料夾 (或多個檔案或資料夾) 的權限,而且應用程式必須將對應的 FileSystemHandle 物件儲存在 IndexedDB 中。下次造訪來源時,應用程式必須從 IndexedDB 擷取任何已儲存的 FileSystemHandle 物件,然後呼叫其 FileSystemHandle.requestPermission() 方法。如果符合這些先決條件,系統就會顯示新的三向提示。
  2. 來源必須在先前授予的 FileSystemHandle 上呼叫 FileSystemHandle.requestPermission() 方法,但由於分頁已背景一陣子,存取權已自動撤銷。(自動撤銷權限的運作邏輯與「Chrome 中的一次性權限」一文所述的邏輯相同)。如果符合這些先決條件,系統就會顯示新的三向提示。
  3. 使用者必須安裝應用程式。使用者授予存取權後,已安裝的應用程式會自動保留權限。在此情況下,系統不會顯示三向提示,而應用程式預設會取得新的行為。

在第一種和第二種情況中,提示會列出應用程式先前可存取的所有 FileSystemHandle 物件,而不僅僅列出系統呼叫 requestPermission() 方法的物件。如果與一次性權限的運作方式一致,如果使用者拒絕或關閉提示三次以上,則不會再觸發提示,而是改為顯示一般權限提示。

試試新行為

如果您有支援的 Chrome 版本,或已設定必要的標記,則可以在網路上測試 VS Code 中的新行為。開啟資料夾並授予存取權,然後關閉分頁再重新開啟,然後按一下「開啟最近開啟的項目」。請注意,立即重新載入功能無法觸發提示,所有分頁都必須關閉。選擇前一個資料夾後,畫面上會顯示新的提示。如果想要減少測試案例,請查看永久檔案系統存取權示範,並查看其原始碼

結論

File System Access API 的永久權限是最常要求的 API 功能之一,實作錯誤也相當普及,許多開發人員都加上星號。開放開發人員使用這項功能後,使用者就認為與平台專屬應用程式相比,現在的功能缺陷十分重要。

特別銘謝

本文由 Christine HollingsworthAustin SullivanRachel Andrew 審查。