chrome.fileSystem

说明

使用 chrome.fileSystem API 创建、读取、导航用户的本地文件系统以及向其写入数据。借助此 API，Chrome 应用可以对用户选择的位置执行读写操作。例如，文本编辑器应用可以使用该 API 读取和写入本地文档。所有失败情况都会通过 chrome.runtime.lastError 进行通知。

权限

fileSystem

可用性

仅限前台

类型

AcceptOption

属性

  • 说明

    字符串（可选）

    这是此选项的可选文本说明。如果没有，系统会自动生成说明；通常包含扩展的有效扩展名列表（例如“text/html”可展开为“*.html、*.htm”）。

  • extensions

    string[] 可选

    要接受的扩展名，例如“jpg”、“gif”、“crx”。

  • mimeTypes

    string[] 可选

    要接受的 MIME 类型，例如“image/jpeg”或“audio/*”。其中一个 mimeType 或扩展必须至少包含一个有效元素。

ChooseEntryOptions

属性

  • 接受

    AcceptOption[] 可选

    此文件打开器的接受选项的可选列表。每个选项都会以一个唯一群组展示给最终用户。

  • acceptsAllTypes

    布尔值 选填

    除了在 Accept 参数中指定的选项之外，是否接受所有文件类型。默认值为 true。如果“accept”字段未设置或不包含任何有效条目，则此字段将始终重置为 true。

  • acceptsMultiple

    布尔值 选填

    是否接受多个文件。只有 openFile 和 openWritableFile 支持此操作，如果设置为 true，则通过条目列表调用 chooseEntry 的回调函数。否则，将使用单个条目调用它。

  • suggestedName

    字符串（可选）

    建议文件名，将作为用户要读取或写入的默认名称而显示。这是可选操作。

  • 类型

    ChooseEntryType 可选

    要显示的提示类型。默认值为“openFile”。

ChooseEntryType

枚举

"openFile"
提示用户打开现有文件，并在成功时返回 FileEntry。从 Chrome 31 开始，如果应用在“fileSystem”下具有“写入”权限，则 FileEntry 将处于可写状态；否则，FileEntry 将处于只读状态。

"openWritableFile"
提示用户打开现有文件，并在成功时返回可写的 FileEntry。如果应用在“fileSystem”下没有“写入”权限，则使用此类型的调用将失败，并出现运行时错误。

"saveFile"
提示用户打开现有文件或新文件，并在成功时返回可写的 FileEntry。如果应用在“fileSystem”下没有“写入”权限，则使用此类型的调用将失败，并出现运行时错误。

"openDirectory"
提示用户打开目录并在成功时返回 DirectoryEntry。如果应用在“fileSystem”下没有“directory”权限，则使用此类型的调用将失败，并出现运行时错误。如果应用在“fileSystem”下具有“写入”权限，则返回的 DirectoryEntry 将可写入数据；否则，它将处于只读状态。Chrome 31 中的新功能。

RequestFileSystemOptions

Chrome 44 及更高版本

属性

  • volumeId

    string

    所请求卷的 ID。

  • 可写入

    布尔值 选填

    请求的文件系统是否应可写入。默认为只读。

Volume

Chrome 44 及更高版本

属性

  • volumeId

    string

  • 可写入

    boolean

VolumeListChangedEvent

Chrome 44 及更高版本

属性

方法

chooseEntry()

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

让用户选择文件或目录。

参数

  • 选项

    ChooseEntryOptions 可选

  • callback

    功能

    callback 参数如下所示：

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

    • 入口

      条目可选

    • fileEntries

      FileEntry[] 可选

getDisplayPath()

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

获取 Entry 对象的显示路径。显示路径基于本地文件系统上文件或目录的完整路径，但为了便于显示，可以更易于阅读。

参数

  • 入口

    条目

  • callback

    函数（可选）

    callback 参数如下所示：

    (displayPath: string)=>void

    • displayPath

      string

返回

  • Promise<string>

    Chrome 117 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getVolumeList()

Promise Chrome 44 及更高版本 
chrome.fileSystem.getVolumeList(
  callback?: function,
)

返回适用于 requestFileSystem() 的卷列表。需要 "fileSystem": {"requestFileSystem"} 清单权限。仅适用于在自助服务终端会话中运行的自助服务终端应用。如果发生错误，系统将未定义 volumes，并会设置 chrome.runtime.lastError。

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (volumes?: Volume[])=>void

返回

  • Promise<卷[]|undefined>

    Chrome 117 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getWritableEntry()

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

从其他条目中获取可写条目。如果应用在“fileSystem”下没有“write”权限，则此调用将失败，并出现运行时错误。如果条目是 DirectoryEntry，则当应用在“fileSystem”下没有“directory”权限时，此调用将失败。

参数

  • 入口

    条目

  • callback

    功能

    callback 参数如下所示：

    (entry: Entry)=>void

    • 入口

      条目

isRestorable()

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

返回应用是否有权恢复具有指定 ID 的条目。

参数

  • id

    string

  • callback

    函数（可选）

    callback 参数如下所示：

    (isRestorable: boolean)=>void

    • isRestorable

      boolean

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

isWritableEntry()

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

获取此条目是否可写。

参数

  • 入口

    条目

  • callback

    函数（可选）

    callback 参数如下所示：

    (isWritable: boolean)=>void

    • isWritable

      boolean

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

requestFileSystem()

Promise Chrome 44 及更高版本 
chrome.fileSystem.requestFileSystem(
  options: RequestFileSystemOptions,
  callback?: function,
)

请求访问由 options.volumeId 表示的卷的文件系统。如果 options.writable 设置为 true，则文件系统可写入。否则，它将处于只读状态。writable 选项需要清单中的 "fileSystem": {"write"} 权限。仅适用于在自助服务终端会话中运行的自助服务终端应用。对于手动启动自助服务终端模式，系统会在使用中的应用窗口顶部显示一个确认对话框。如果发生错误，系统将未定义 fileSystem，并会设置 chrome.runtime.lastError。

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (fileSystem?: FileSystem)=>void

    • fileSystem

      FileSystem（可选）

返回

  • Promise<FileSystem|undefined>

    Chrome 117 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

restoreEntry()

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

如果可以恢复，则返回具有指定 ID 的文件条目。否则，此调用将失败，并显示运行时错误。

参数

  • id

    string

  • callback

    功能

    callback 参数如下所示：

    (entry: Entry)=>void

    • 入口

      条目

retainEntry()

chrome.fileSystem.retainEntry(
  entry: Entry,
)

返回一个 ID，您可以将该 ID 传递给 recoveryEntry 以重新获得对给定文件条目的访问权限。仅保留 500 个最近使用的条目，其中对 keepEntry 和 recoveryEntry 的调用会被计为使用。如果应用在“fileSystem”下具有“retainEntries”权限，则系统会无限期保留条目。否则，系统只会在应用运行时以及重启后保留这些条目。

参数

  • 入口

    条目

返回

  • string

活动

onVolumeListChanged

Chrome 44 及更高版本 
chrome.fileSystem.onVolumeListChanged.addListener(
  callback: function,
)

在可用卷列表发生更改时调用。

参数