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/*”。mimeTypes 或 extensions 之一必须包含至少一个有效元素。

ChooseEntryOptions

属性

  • accepts

    AcceptOption[] 可选

    此文件打开器的可选接受选项列表。每个选项都将以唯一群组的形式呈现给最终用户。

  • acceptsAllTypes

    布尔值（可选）

    是否接受所有文件类型，以及 accepts 实参中指定的选项。默认值为 true。如果 accepts 字段未设置或不包含任何有效条目，则系统始终会将其重置为 true。

  • acceptsMultiple

    布尔值（可选）

    是否接受多个文件。仅支持 openFile 和 openWritableFile。如果此属性设置为 true，系统将使用条目列表调用 chooseEntry 回调。否则，系统将使用单个 Entry 调用该方法。

  • suggestedName

    字符串（选填）

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

  • 类型

    ChooseEntryType 可选

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

ChooseEntryType

枚举

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

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

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

“openDirectory”
提示用户打开目录，并在成功时返回 DirectoryEntry。如果应用在“fileSystem”下没有“directory”权限，则使用此类型的调用将因运行时错误而失败。如果应用在“fileSystem”下具有“写入”权限，则返回的 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

    • 入口

      条目 可选

    • fileEntries

      FileEntry[] 可选

getDisplayPath()

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

获取 Entry 对象的显示路径。显示路径基于本地文件系统上文件或目录的完整路径，但为了便于显示，可能会进行调整。

参数

  • 入口

    条目

  • callback

    函数 可选

    callback 参数如下所示： 

    (displayPath: string) => void

    • displayPath

      字符串

返回

  • Promise<string>

    Chrome 117 及更高版本

    仅 Manifest 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 及更高版本

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

getWritableEntry()

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

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

参数

  • 入口

    条目

  • callback

    函数

    callback 参数如下所示： 

    (entry: Entry) => void

    • 入口

      条目

isRestorable()

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

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

参数

  • id

    字符串

  • callback

    函数 可选

    callback 参数如下所示： 

    (isRestorable: boolean) => void

    • isRestorable

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

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

isWritableEntry()

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

获取相应条目是否可写入。

参数

  • 入口

    条目

  • callback

    函数 可选

    callback 参数如下所示： 

    (isWritable: boolean) => void

    • isWritable

      布尔值

返回

  • Promise<boolean>

    Chrome 117 及更高版本

    仅 Manifest 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 及更高版本

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

restoreEntry()

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

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

参数

  • id

    字符串

  • callback

    函数

    callback 参数如下所示： 

    (entry: Entry) => void

    • 入口

      条目

retainEntry()

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

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

参数

  • 入口

    条目

返回

  • 字符串

事件

onVolumeListChanged

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

当可用音量列表发生变化时调用。

参数