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

属性

  • 接受

    AcceptOption[] 可选

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

  • acceptsAllTypes

    布尔值 （可选）

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

  • acceptsMultiple

    布尔值 （可选）

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

  • suggestedName

    字符串 可选

    建议的文件名，将作为默认保存名称向用户显示。此参数为可选参数，仅适用于“saveFile”。

  • 类型

    ChooseEntryType 可选

    要显示的提示类型。默认值为“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

    • 入口

      条目（可选）

    • 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”权限，此调用将失败并出现运行时错误。如果 entry 是 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,
)

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

参数