chrome.fileSystem

說明

使用 chrome.fileSystem API 建立、讀取、瀏覽及寫入使用者的本機檔案系統。Chrome 應用程式可透過這個 API 讀取及寫入使用者選取的位置。舉例來說，文字編輯器應用程式可以使用 API 讀取及寫入本機文件。所有失敗都會透過 chrome.runtime.lastError 通知。

權限

fileSystem

可用性

僅限前景

類型

AcceptOption

屬性

  • 說明

    字串 選填

    這是這個選項的選填文字說明。如果沒有，系統會自動產生說明，通常會包含有效擴充功能的擴充清單 (例如「text/html」可能會擴充為「*.html, *.htm」)。

  • 擴充功能

    字串陣列 選用

    可接受的副檔名，例如「jpg」、「gif」、「crx」。

  • mimeTypes

    字串陣列 選用

    要接受的 MIME 類型，例如「image/jpeg」或「audio/*」。mimeTypes 或 extensions 其中之一必須包含至少一個有效元素。

ChooseEntryOptions

屬性

  • 接受

    AcceptOption[] optional

    這個檔案開啟器可接受的選用選項清單。每個選項都會以獨立群組的形式呈現給使用者。

  • acceptsAllTypes

    布林值 選填

    是否接受所有檔案類型，除了 accepts 引數中指定的選項。預設值為 true。如果未設定 accepts 欄位或不含任何有效項目，系統一律會將此欄位重設為 true。

  • acceptsMultiple

    布林值 選填

    是否接受多個檔案。這項功能僅支援 openFile 和 openWritableFile。如果設為 true，系統會使用項目清單呼叫 chooseEntry 的回呼。否則會使用單一 Entry 呼叫。

  • suggestedName

    字串 選填

    系統會向使用者顯示建議的檔案名稱，做為讀取或寫入的預設名稱。您可以視需要決定是否啟用。

  • 類型

    ChooseEntryType optional

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

ChooseEntryType

列舉

「openFile」
提示使用者開啟現有檔案，並在成功時傳回 FileEntry。從 Chrome 31 開始，如果應用程式在「fileSystem」底下具有「write」權限，FileEntry 就會是可寫入的；否則，FileEntry 就會是唯讀的。

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

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

「openDirectory」
提示使用者開啟目錄，並在成功時傳回 DirectoryEntry。如果應用程式在「fileSystem」底下沒有「directory」權限，使用這類型的呼叫就會失敗，並發生執行階段錯誤。如果應用程式在「fileSystem」底下具有「write」權限，傳回的 DirectoryEntry 將可寫入；否則為唯讀。Chrome 31 的新功能。

RequestFileSystemOptions

Chrome 44 以上版本

屬性

  • volumeId

    字串

    所要求卷冊的 ID。

  • 可寫入

    布林值 選填

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

Volume

Chrome 44 以上版本

屬性

  • volumeId

    字串

  • 可寫入

    布林值

VolumeListChangedEvent

Chrome 44 以上版本

屬性

方法

chooseEntry()

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

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

參數

  • 選項

    ChooseEntryOptions 選用

  • callback

    函式

    callback 參數如下： 

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

    • entry

      項目 (選填)

    • fileEntries

      FileEntry[] 選用

getDisplayPath()

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

取得 Entry 物件的顯示路徑。顯示路徑是根據本機檔案系統中檔案或目錄的完整路徑而定，但為了方便顯示，可能會經過調整。

參數

  • entry

    項目

  • callback

    函式 選用

    callback 參數如下： 

    (displayPath: string) => void

    • displayPath

      字串

傳回

  • Promise<string>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getVolumeList()

Promise Chrome 44 以上版本 
chrome.fileSystem.getVolumeList(
  callback?: function,
): Promise<Volume[] | undefined>

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

參數

  • callback

    函式 選用

    callback 參數如下： 

    (volumes?: Volume[]) => void

傳回

  • Promise<Volume[] | undefined>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getWritableEntry()

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

從另一個 Entry 取得可寫入的 Entry。如果應用程式在「fileSystem」下沒有「write」權限，這項呼叫就會失敗並產生執行階段錯誤。如果項目是 DirectoryEntry，且應用程式在「fileSystem」底下沒有「directory」權限，這項呼叫就會失敗。

參數

  • entry

    項目

  • callback

    函式

    callback 參數如下： 

    (entry: Entry) => void

    • entry

      項目

isRestorable()

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

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

參數

  • id

    字串

  • callback

    函式 選用

    callback 參數如下： 

    (isRestorable: boolean) => void

    • isRestorable

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

isWritableEntry()

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

取得這個項目是否可寫入。

參數

  • entry

    項目

  • callback

    函式 選用

    callback 參數如下： 

    (isWritable: boolean) => void

    • isWritable

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

requestFileSystem()

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

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

參數

  • callback

    函式 選用

    callback 參數如下： 

    (fileSystem?: FileSystem) => void

    • fileSystem

      FileSystem 選用

傳回

  • Promise<FileSystem | undefined>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

restoreEntry()

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

如果可以還原，則傳回具有指定 ID 的檔案項目。否則，這項呼叫會因執行階段錯誤而失敗。

參數

  • id

    字串

  • callback

    函式

    callback 參數如下： 

    (entry: Entry) => void

    • entry

      項目

retainEntry()

chrome.fileSystem.retainEntry(
  entry: Entry,
): string

傳回可傳遞至 restoreEntry 的 ID，以重新取得特定檔案項目的存取權。系統只會保留最近使用的 500 個項目，其中呼叫 retainEntry 和 restoreEntry 會計為使用次數。如果應用程式在「fileSystem」底下具有「retainEntries」權限，系統就會無限期保留項目。否則，系統只會在應用程式執行期間和重新啟動時保留項目。

參數

  • entry

    項目

傳回

  • 字串

事件

onVolumeListChanged

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

可用音量清單變更時呼叫。

參數