chrome.syncFileSystem

说明

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

权限

syncFileSystem

类型

ConflictResolutionPolicy

枚举

"last_write_win"

"手动"

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

ServiceStatus

枚举

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

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

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

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

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

StorageInfo

属性

• quotaBytes

  number

• usageBytes

  number

SyncAction

枚举

“已添加”

“已更新”

“已删除”

SyncDirection

枚举

"local_to_remote"

"remote_to_local"

方法

getConflictResolutionPolicy()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (policy: ConflictResolutionPolicy) => void

  • 政策

    ConflictResolutionPolicy

返回

• Promise&lt;ConflictResolutionPolicy&gt;

  Chrome 117 及更高版本

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

getFileStatus()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• fileEntry

  条目

• callback

  函数（可选）

  callback 参数如下所示：

  (status: FileStatus) => void

  • 状态

    FileStatus

返回

• Promise&lt;FileStatus&gt;

  Chrome 117 及更高版本

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

getFileStatuses()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• fileEntries

  object[]

• callback

  函数（可选）

  callback 参数如下所示：

  (status: FileStatusInfo[]) => void

  • 状态

    FileStatusInfo[]

返回

• Promise&lt;FileStatusInfo[]&gt;

  Chrome 117 及更高版本

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

getServiceStatus()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (status: ServiceStatus) => void

  • 状态

    ServiceStatus

返回

• Promise&lt;ServiceStatus&gt;

  Chrome 117 及更高版本

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

getUsageAndQuota()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• fileSystem

  DOMFileSystem

• callback

  函数（可选）

  callback 参数如下所示：

  (info: StorageInfo) => void

  • 资讯

    StorageInfo

返回

• Promise&lt;StorageInfo&gt;

  Chrome 117 及更高版本

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

requestFileSystem()

<ph type="x-smartling-placeholder"></ph> 承诺

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&lt;DOMFileSystem&gt;

  Chrome 117 及更高版本

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

setConflictResolutionPolicy()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• 政策

  ConflictResolutionPolicy

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 117 及更高版本

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

事件

onFileStatusChanged

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (detail: FileInfo) => void

  • 详细信息

    FileInfo

onServiceStatusChanged

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (detail: ServiceInfo) => void

  • 详细信息

    ServiceInfo