chrome.fileSystem

說明

使用 chrome.fileSystem API 建立、讀取、瀏覽及寫入使用者的本機檔案系統。這個 API 可讓 Chrome 應用程式讀取使用者指定的位置，並寫入其中的資料。例如，文字編輯器應用程式可使用這個 API 讀取及寫入本機文件。所有失敗都會透過 chrome.runtime.lastError 通知。

權限

fileSystem

可用性

僅限前景

類型

AcceptOption

屬性

  • 說明

    string optional

    此為選用選項的文字說明。如未指定，系統會自動產生說明。通常包含有效額外資訊的清單 (例如，「text/html」可能會展開為「*.html, *.htm」)。

  • 擴充功能

    string[] 選填

    接受的擴充功能，例如「jpg」、「gif」、「crx」。

  • mimeTypes

    string[] 選填

    接受的 Mime 類型，例如：「image/jpeg」或「audio/*」。mimeType 或副檔名中的其中一個必須包含至少一個有效元素。

ChooseEntryOptions

屬性

  • 接受

    AcceptOption[] 選用

    這個檔案開啟工具的接受選項清單 (選用)。每個選項都會以專屬群組的形式呈現給使用者。

  • acceptsAllTypes

    布林值 選填

    除了接受引數中指定的選項之外，是否接受所有檔案類型。預設值為 true。如果未設定接受欄位，或未包含有效項目，這個項目將一律重設為 true。

  • acceptsMultiple

    布林值 選填

    是否接受多個檔案。這僅適用於 openFile 和 openWritableFile。如果設為 true，系統會呼叫 chooseEntry 的回呼，並提供項目清單。否則，將只有單一項目呼叫。

  • suggestedName

    string optional

    系統會向使用者顯示這個建議檔案名稱，做為讀取或寫入的預設名稱。。

  • 類型

    ChooseEntryType 選用

    要顯示的提示類型。預設值為「openFile」。

ChooseEntryType

列舉

"openFile"
提示使用者開啟現有檔案，並在成功時傳回 FileEntry。在 Chrome 31 以上版本中，如果應用程式含有「write」指令，系統就會寫入 FileEntry權限；否則 FileEntry 會處於唯讀狀態。

"openWritableFile"
提示使用者開啟現有檔案，並在成功時傳回可寫入的 FileEntry。如果應用程式沒有「寫入」錯誤，使用這種類型的呼叫會失敗，並發生執行階段錯誤權限。

"saveFile"
提示使用者開啟現有檔案或新檔案，並在成功時傳回可寫入的 FileEntry。如果應用程式沒有「寫入」錯誤，使用這種類型的呼叫會失敗，並發生執行階段錯誤權限。

"openDirectory"
提示使用者開啟目錄，並在成功時傳回 DirectoryEntry。如果應用程式沒有「directory」，使用此類型的呼叫會失敗並發生執行階段錯誤權限。如果應用程式含有「write」權限，可寫入傳回的 DirectoryEntry；否則資料會處於唯讀狀態Chrome 31 的新功能。

RequestFileSystemOptions

Chrome 44 以上版本

屬性

  • volumeId

    字串

    所要求磁碟區的 ID。

  • 可寫入

    布林值 選填

    要求的檔案系統是否應可寫入。預設值為唯讀。

Volume

Chrome 44 以上版本

屬性

  • volumeId

    字串

  • 可寫入

    布林值

VolumeListChangedEvent

Chrome 44 以上版本

屬性

方法

chooseEntry()

chrome.fileSystem.chooseEntry(
  options?: ChooseEntryOptions,
  callback: function,
)

請使用者選擇檔案或目錄。

參數

  • 選項

    ChooseEntryOptions 選用

  • 回呼

    函式

    callback 參數如下所示： 

    (entry?: Entry, fileEntries?: FileEntry[]) => void

    • 項目

      報名選填

    • fileEntries

      FileEntry[] 選填

getDisplayPath()

Promise 
chrome.fileSystem.getDisplayPath(
  entry: Entry,
  callback?: function,
)

取得項目物件的顯示路徑。顯示路徑是以本機檔案系統中檔案或目錄的完整路徑為基礎，但可能更易於顯示。

參數

  • 項目

    項目

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (displayPath: string) => void

    • displayPath

      字串

傳回

  • 承諾<字串>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getVolumeList()

Promise Chrome 44 以上版本 
chrome.fileSystem.getVolumeList(
  callback?: function,
)

傳回 requestFileSystem() 可用的磁碟區清單。必須具備 "fileSystem": {"requestFileSystem"} 資訊清單權限。僅適用於在資訊站工作階段中執行的資訊站應用程式。如果發生錯誤，系統會未定義 volumes，並設為 chrome.runtime.lastError。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (volumes?: Volume[]) => void

傳回

  • Promise&lt;Volume[] |未定義>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getWritableEntry()

chrome.fileSystem.getWritableEntry(
  entry: Entry,
  callback: function,
)

從其他項目取得可寫入的項目。如果應用程式沒有「write」指令，則呼叫會失敗並發生執行階段錯誤權限。如果項目是 DirectoryEntry，則若應用程式沒有「目錄」，呼叫就會失敗權限。

參數

  • 項目

    項目

  • 回呼

    函式

    callback 參數如下所示： 

    (entry: Entry) => void

    • 項目

      項目

isRestorable()

Promise 
chrome.fileSystem.isRestorable(
  id: string,
  callback?: function,
)

傳回應用程式是否有權還原具有指定 ID 的項目。

參數

  • id

    字串

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (isRestorable: boolean) => void

    • isRestorable

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

isWritableEntry()

Promise 
chrome.fileSystem.isWritableEntry(
  entry: Entry,
  callback?: function,
)

瞭解此項目是否可寫入。

參數

  • 項目

    項目

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (isWritable: boolean) => void

    • isWritable

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

requestFileSystem()

Promise Chrome 44 以上版本 
chrome.fileSystem.requestFileSystem(
  options: RequestFileSystemOptions,
  callback?: function,
)

要求對 options.volumeId 所代表磁碟區的檔案系統存取權。如果將 options.writable 設為 True，系統就會寫入檔案系統。否則資料會處於唯讀狀態。writable 選項需要資訊清單中的 "fileSystem": {"write"} 權限。僅適用於在資訊站工作階段中執行的資訊站應用程式。如果是手動啟動 Kiosk 模式，使用中的應用程式視窗頂端會顯示確認對話方塊。如果發生錯誤，系統會未定義 fileSystem，並設為 chrome.runtime.lastError。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (fileSystem?: FileSystem) => void

    • fileSystem

      檔案系統 (選用)

傳回

  • Promise&lt;FileSystem |未定義>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

restoreEntry()

chrome.fileSystem.restoreEntry(
  id: string,
  callback: function,
)

如果可以還原含有指定 ID 的檔案項目，則傳回該項目。如果未呼叫，這項呼叫就會失敗，並發生執行階段錯誤。

參數

  • id

    字串

  • 回呼

    函式

    callback 參數如下所示： 

    (entry: Entry) => void

    • 項目

      項目

retainEntry()

chrome.fileSystem.retainEntry(
  entry: Entry,
)

傳回可傳遞至 RestoreEntry 的 ID，以重新取得特定檔案項目的存取權。系統只會保留最近使用過的 500 個項目，其中保留 Entry 和還原 Entry 的呼叫會視為使用。如果應用程式提供「retainEntries」權限，系統會無限期保留項目。否則，系統只會在應用程式執行期間和重新啟動時保留項目。

參數

  • 項目

    項目

傳回

  • 字串

活動

onVolumeListChanged

Chrome 44 以上版本 
chrome.fileSystem.onVolumeListChanged.addListener(
  callback: function,
)

在可用磁碟區清單變更時呼叫。

參數