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

枚举

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

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

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

FileStatusInfo

属性

  • 错误

    字符串（选填）

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

  • fileEntry

    条目

    最初提供给 getFileStatuses 的 Entry 之一。

  • 状态

    FileStatus

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

ServiceInfo

属性

ServiceStatus

枚举

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

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

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

“temporary_unavailable”
同步服务未同步文件，因为远程服务因某些可恢复的错误（例如网络离线、远程服务关闭或无法访问等）而暂时不可用。有关更多详细信息，请参阅 OnServiceInfoUpdated 中的 description 参数（可能包含特定于服务的详细信息）。

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

StorageInfo

属性

  • quotaBytes

    数值

  • usageBytes

    数值

SyncAction

枚举

“添加”

“更新”

“已删除”

SyncDirection

枚举

"local_to_remote"

"remote_to_local"

方法

getConflictResolutionPolicy()

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

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

参数

返回

  • Chrome 117 及更高版本

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

getFileStatus()

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

返回给定 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,
): Promise<FileStatusInfo[]>

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

参数

返回

  • Promise<FileStatusInfo[]>

    Chrome 117 及更高版本

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

getServiceStatus()

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

返回当前同步后端状态。

参数

返回

  • Promise<ServiceStatus>

    Chrome 117 及更高版本

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

getUsageAndQuota()

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

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

参数

  • fileSystem

    DOMFileSystem

  • callback

    函数 可选

    callback 参数如下所示： 

    (info: StorageInfo) => void

返回

  • Promise<StorageInfo>

    Chrome 117 及更高版本

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

requestFileSystem()

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

返回由 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,
): Promise<void>

为应用的 '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,
)

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

参数