chrome.syncFileSystem

说明

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

权限

syncFileSystem

类型

ConflictResolutionPolicy

枚举

"last_write_win"

“manual”

FileInfo

属性

  • action

    SyncAction（可选）

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

  • 方向

    SyncDirection（同步方向）可选

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

  • fileEntry

    条目

    状态已更改的目标文件的 fileEntry。包含已同步文件的名称和路径信息。删除文件后，fileEntry 信息仍可用，但文件将不复存在。

  • 状态

    FileStatus

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

FileStatus

枚举

“已同步”
没有冲突，并且没有待处理的本地更改。

“pending”
存在一个或多个尚未同步的待处理本地更改。

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

FileStatusInfo

属性

  • 错误

    字符串（选填）

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

  • fileEntry

    条目

    最初提供给 getFileStatuses 的条目之一。

  • 状态

    FileStatus

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

ServiceInfo

属性

ServiceStatus

枚举

“initializing”（初始化）
同步服务正在初始化（例如从数据库恢复数据、检查连接性和对服务进行身份验证等）。

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

"authentication_required"
同步服务无法同步文件，因为远程服务需要用户进行身份验证才能继续。

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

“disabled”
同步服务已停用，内容将永远不会同步。（例如，当用户在远程服务上没有账号或同步服务出现不可恢复的错误时，就可能会发生这种情况。）

StorageInfo

属性

  • quotaBytes

    数值

  • usageBytes

    数值

SyncAction

枚举

"added"

“updated”

"deleted"

SyncDirection

枚举

"local_to_remote"

"remote_to_local"

方法

getConflictResolutionPolicy()

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

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

参数

返回

  • Chrome 117 及更高版本

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

getFileStatus()

prometido 
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()

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

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

参数

  • fileEntries

    object[]

  • callback

    函数（可选）

    callback 参数如下所示： 

    (status: FileStatusInfo[]) => void

返回

  • Promise<FileStatusInfo[]>

    Chrome 117 及更高版本

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

getServiceStatus()

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

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

参数

返回

  • Promise<ServiceStatus>

    Chrome 117 及更高版本

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

getUsageAndQuota()

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

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

参数

  • fileSystem

    DOMFileSystem

  • callback

    函数（可选）

    callback 参数如下所示： 

    (info: StorageInfo) => void

返回

  • Promise<StorageInfo>StorageInfo

    Chrome 117 及更高版本

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

requestFileSystem()

prometido 
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()

prometido 
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,
)

当同步后端发生错误或其他状态变化时触发（例如，当同步因网络或身份验证错误而暂时停用时）。

参数