chrome.fileSystem

说明

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

权限

fileSystem

可用性

<ph type="x-smartling-placeholder"></ph> 仅限前台

类型

AcceptOption

属性

• 说明

  字符串（可选）

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

• extensions

  string[] 选填

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

• mimeTypes

  string[] 选填

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

ChooseEntryOptions

属性

• 接受

  AcceptOption[] 可选

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

• acceptsAllTypes

  布尔值（可选）

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

• acceptsMultiple

  布尔值（可选）

  是否接受多个文件。只有 openFile 和 openWritableFile 支持这一操作。如果将此属性设置为 true，则系统会使用条目列表调用对 chooseEntry 的回调。否则，将使用单个条目进行调用。

• suggestedName

  字符串（可选）

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

• 类型

  ChooseEntryType（可选）

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

ChooseEntryType

枚举

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

&quot;openWritableFile&quot;
提示用户打开现有文件，并在成功时返回一个可写 FileEntry。如果应用不具有“写入”选项，则使用此类型的调用将失败并显示运行时错误权限。

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

&quot;openDirectory&quot;
提示用户打开目录，并在成功时返回 DirectoryEntry。如果应用没有“目录”，使用此类型的调用将失败并显示运行时错误权限。如果应用程序具有“写入”权限，则返回的 DirectoryEntry 将可写入；否则会处于只读状态。Chrome 31 中的新功能。

RequestFileSystemOptions

Chrome 44 及更高版本

属性

• volumeId

  字符串

  所请求卷的 ID。

• 可写入

  布尔值（可选）

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

Volume

Chrome 44 及更高版本

属性

• volumeId

  字符串

• 可写入

  布尔值

VolumeListChangedEvent

Chrome 44 及更高版本

属性

• volumes

  音量[]

方法

chooseEntry()

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

让用户选择一个文件或目录。

参数

• 选项

  ChooseEntryOptions 可选

• callback

  函数

  callback 参数如下所示：

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

  • 入口

    条目（选填）

  • fileEntries

    FileEntry[]（可选）

getDisplayPath()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• 入口

  条目

• callback

  函数（可选）

  callback 参数如下所示：

  (displayPath: string) => void

  • displayPath

    字符串

返回

• 承诺<字符串>

  Chrome 117 及更高版本

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

getVolumeList()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 44 及更高版本

chrome.fileSystem.getVolumeList(
  callback?: function,
)

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (volumes?: Volume[]) => void

  • volumes

    Volume[]（可选）

返回

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

  Chrome 117 及更高版本

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

getWritableEntry()

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

从另一个条目获取可写条目。如果应用没有“写入”权限，此调用将失败，并显示运行时错误权限。如果条目是 DirectoryEntry，如果应用不包含“directory”，则此调用将失败。权限。

参数

• 入口

  条目

• callback

  函数

  callback 参数如下所示：

  (entry: Entry) => void

  • 入口

    条目

isRestorable()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• id

  字符串

• callback

  函数（可选）

  callback 参数如下所示：

  (isRestorable: boolean) => void

  • isRestorable

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

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

isWritableEntry()

<ph type="x-smartling-placeholder"></ph> 承诺

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

获取此条目是否可写入。

参数

• 入口

  条目

• callback

  函数（可选）

  callback 参数如下所示：

  (isWritable: boolean) => void

  • isWritable

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

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

requestFileSystem()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 44 及更高版本

chrome.fileSystem.requestFileSystem(
  options: RequestFileSystemOptions,
  callback?: function,
)

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

参数

• 选项

  RequestFileSystemOptions

• callback

  函数（可选）

  callback 参数如下所示：

  (fileSystem?: FileSystem) => void

  • fileSystem

    FileSystem（可选）

返回

• Promise&lt;FileSystem |未定义>

  Chrome 117 及更高版本

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

restoreEntry()

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

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

参数

• id

  字符串

• callback

  函数

  callback 参数如下所示：

  (entry: Entry) => void

  • 入口

    条目

retainEntry()

chrome.fileSystem.retainEntry(
  entry: Entry,
)

返回一个 ID，该 ID 可以传递给 restoreEntry，以重新获得对指定文件条目的访问权限。仅保留最近用过的 500 个条目，其中调用 retainEntry 和 restoreEntry 计为使用。如果应用包含“retainEntries”权限，系统会无限期地保留条目。否则，系统只会在应用运行时以及重启时保留条目。

参数

• 入口

  条目

返回

• 字符串

事件

onVolumeListChanged

Chrome 44 及更高版本

chrome.fileSystem.onVolumeListChanged.addListener(
  callback: function,
)

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

参数

• callback

  函数

  callback 参数如下所示：

  (event: VolumeListChangedEvent) => void

  • 事件

    VolumeListChangedEvent