chrome.syncFileSystem

说明

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

权限

syncFileSystem

类型

ConflictResolutionPolicy

枚举

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

枚举

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

“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"

方法

getConflictResolutionPolicy()

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

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

参数

返回

  • Promise<ConflictResolutionPolicy>

    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

    对象 []

  • callback

    函数（可选）

    callback 参数如下所示： 

    (status: FileStatusInfo[]) => void

返回

  • Promise<FileStatusInfo[]>

    Chrome 117 及更高版本

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

getServiceStatus()

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

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

参数

返回

  • Promise&lt;ServiceStatus&gt;

    Chrome 117 及更高版本

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

getUsageAndQuota()

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

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

参数

  • fileSystem

    DOMFileSystem

  • callback

    函数（可选）

    callback 参数如下所示： 

    (info: StorageInfo) => void

返回

  • Promise&lt;StorageInfo&gt;

    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，以了解请求是否成功。

参数

返回

  • 承诺<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,
)

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

参数