chrome.syncFileSystem

说明

您可以使用 chrome.syncFileSystem API 在 Google 云端硬盘中保存和同步数据。此 API 不适用于访问存储在 Google 云端硬盘中的任意用户文档。它提供应用专属的可同步存储空间，以供离线使用和缓存使用，从而在不同的客户端中提供相同的数据。如需详细了解如何使用此 API，请参阅管理数据。

权限

syncFileSystem

类型

ConflictResolutionPolicy

枚举

"last_write_win"

"manual"

FileInfo

属性

  • action

    SyncAction（可选）

    已触发 onFileStatusChanged 事件的同步操作。操作值可以是 'added'、'updated' 或 'deleted'。仅在状态为 'synced' 时才适用。

  • direction

    SyncDirection（可选）

    onFileStatusChanged 事件的同步方向。同步方向值可以是 'local_to_remote' 或 'remote_to_local'。仅在状态为 'synced' 时才适用。

  • fileEntry

    条目

    针对状态已更改的目标文件的 fileEntry。包含同步文件的名称和路径信息。文件删除后，fileEntry信息仍会显示，但文件将不再存在。

  • status

    FileStatus

    发生 onFileStatusChanged 事件后生成的文件状态。状态值可以是 'synced'、'pending' 或 'conflicting'。

FileStatus

枚举

"synced"
没有冲突，没有待处理的本地更改。

"pending"
有一项或多项待处理的本地更改尚未同步。

"conflicting"
文件与远程版本冲突，必须手动解决。

FileStatusInfo

属性

  • error

    字符串（可选）

    可选错误，仅当检索指定文件的 FileStatus 时出现问题时才会返回。

  • fileEntry

    条目

    最初为 getFileStatuses 指定的条目之一。

  • status

    FileStatus

    状态值可以是 'synced'、'pending' 或 'conflicting'。

ServiceInfo

属性

ServiceStatus

枚举

"initializing"
正在初始化同步服务（例如，从数据库恢复数据、检查连接性以及向服务进行身份验证等）。

"running"
同步服务已启动并正在运行。

"authentication_required"
同步服务不会同步文件，因为远程服务需要经过用户身份验证才能继续。

"temporary_unavailable"
同步服务未同步文件，因为远程服务因某些可恢复的错误（例如网络离线、远程服务已中断或无法访问等）而（暂时）不可用。更多详细信息应通过 OnServiceInfoUpdated 中的 description 参数（可能包含服务特定详细信息）提供。

"disabled"
同步服务已停用，内容永远不会同步。（例如，如果用户在远程服务上没有帐号，或者同步服务发生了不可恢复的错误，就可能发生这种情况。）

StorageInfo

属性

  • quotaBytes

    number

  • usageBytes

    number

SyncAction

枚举

SyncDirection

枚举

"local_to_remote"

"remote_to_local"

方法

getConflictResolutionPolicy()

Promise 
chrome.syncFileSystem.getConflictResolutionPolicy(
  callback?: function,
)

获取当前的冲突解决政策。

参数

返回

  • Chrome 117 及更高版本

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

getFileStatus()

Promise 
chrome.syncFileSystem.getFileStatus(
  fileEntry: Entry,
  callback?: function,
)

返回指定 fileEntry 的 FileStatus。状态值可以是 'synced'、'pending' 或 'conflicting'。请注意，仅当服务的冲突解决政策设置为 'manual' 时，'conflicting' 状态才会发生。

参数

  • fileEntry

    条目

  • callback

    函数（可选）

    callback 参数如下所示：

    (status: FileStatus)=>void

返回

  • Promise<FileStatus>

    Chrome 117 及更高版本

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

getFileStatuses()

Promise 
chrome.syncFileSystem.getFileStatuses(
  fileEntries: object[],
  callback?: function,
)

返回指定 fileEntry 数组的每个 FileStatus。通常通过来自 dirReader.readEntries() 的结果进行调用。

参数

返回

  • Promise<FileStatusInfo[]>

    Chrome 117 及更高版本

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

getServiceStatus()

Promise 
chrome.syncFileSystem.getServiceStatus(
  callback?: function,
)

返回当前的同步后端状态。

参数

返回

  • Promise<ServiceStatus>

    Chrome 117 及更高版本

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

getUsageAndQuota()

Promise 
chrome.syncFileSystem.getUsageAndQuota(
  fileSystem: DOMFileSystem,
  callback?: function,
)

返回应用的 'syncable' 文件存储空间的当前用量和配额（以字节为单位）。

参数

  • fileSystem

    DOMFileSystem

  • callback

    函数（可选）

    callback 参数如下所示：

    (info: StorageInfo)=>void

返回

  • Promise<StorageInfo>

    Chrome 117 及更高版本

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

requestFileSystem()

Promise 
chrome.syncFileSystem.requestFileSystem(
  callback?: function,
)

返回由 Google 云端硬盘支持的可同步文件系统。返回的 DOMFileSystem 实例可以按照与临时和持久性文件系统相同的方式进行操作（请参阅 http://dev.w3.org/2009/dap/file-system/file-dir-sys.html）。

从同一应用多次调用此方法会向同一文件系统返回相同的句柄。

请注意，此调用可能会失败。例如，如果用户未登录 Chrome 或无网络操作。为了处理这些错误，请务必在回调中检查 chrome.runtime.lastError。

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (fileSystem: DOMFileSystem)=>void

    • fileSystem

      DOMFileSystem

返回

  • Promise<DOMFileSystem>

    Chrome 117 及更高版本

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

setConflictResolutionPolicy()

Promise 
chrome.syncFileSystem.setConflictResolutionPolicy(
  policy: ConflictResolutionPolicy,
  callback?: function,
)

为应用的 'syncable' 文件存储空间设置默认的冲突解决政策。默认情况下，该政策设置为 'last_write_win'。如果冲突解决政策设为“'last_write_win'”，现有文件的冲突解决方式会在文件下次更新时自动解决。可以选择性地指定 callback，以了解请求是否成功。

参数

返回

  • Promise<void>

    Chrome 117 及更高版本

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

活动

onFileStatusChanged

chrome.syncFileSystem.onFileStatusChanged.addListener(
  callback: function,
)

在后台同步服务更新文件时触发。

参数

  • callback

    功能

    callback 参数如下所示：

    (detail: FileInfo)=>void

onServiceStatusChanged

chrome.syncFileSystem.onServiceStatusChanged.addListener(
  callback: function,
)

当同步后端出现错误或其他状态更改时触发（例如，由于网络或身份验证错误暂时停用同步）。

参数