chrome.syncFileSystem

說明

使用 chrome.syncFileSystem API 儲存及同步處理 Google 雲端硬碟中的資料。這個 API「無法」存取儲存在 Google 雲端硬碟中的任意使用者文件。這項服務提供應用程式專用的可同步儲存空間，供離線和快取使用，因此相同資料可在不同用戶端上使用。如要進一步瞭解如何使用這項 API，請參閱「管理資料」。

權限

syncFileSystem

類型

ConflictResolutionPolicy

列舉

"last_write_win"

「manual」

FileInfo

屬性

  • 動作

    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

列舉

「正在初始化」
正在初始化同步服務 (例如從資料庫還原資料、檢查連線及向服務驗證等)。

「running」
同步服務已啟動並正常運作。

「authentication_required」
同步服務未同步處理檔案，因為使用者必須驗證遠端服務才能繼續。

「temporary_unavailable」
同步服務未同步處理檔案，因為遠端服務暫時無法使用 (由於某些可復原的錯誤，例如網路離線、遠端服務停止運作或無法連線等)。OnServiceInfoUpdated 中的 description 參數應提供更多詳細資料 (可能包含服務專屬詳細資料)。

「disabled」
同步服務已停用，內容不會同步。(舉例來說，如果使用者在遠端服務中沒有帳戶，或是同步服務發生無法復原的錯誤，就可能發生這種情況)。

StorageInfo

屬性

  • quotaBytes

    數字

  • usageBytes

    數字

SyncAction

列舉

「added」

「updated」

「deleted」

SyncDirection

列舉

「local_to_remote」

「remote_to_local」

方法

getConflictResolutionPolicy()

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

取得目前的衝突解決政策。

參數

傳回

  • Chrome 117 以上版本

    只有資訊清單 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 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getFileStatuses()

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

傳回指定 fileEntry 陣列的每個 FileStatus。通常會使用 dirReader.readEntries() 的結果呼叫。

參數

傳回

  • Promise<FileStatusInfo[]>

    Chrome 117 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getServiceStatus()

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

傳回目前的同步後端狀態。

參數

傳回

  • Promise<ServiceStatus>

    Chrome 117 以上版本

    只有資訊清單 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 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

requestFileSystem()

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

傳回由 Google 雲端硬碟支援的可同步處理檔案系統。傳回的 DOMFileSystem 執行個體可與 Temporary 和 Persistant 檔案系統以相同方式運作 (請參閱 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 以上版本

    只有資訊清單 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 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onFileStatusChanged

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

當背景同步服務更新檔案時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (detail: FileInfo) => void

onServiceStatusChanged

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

當同步後端發生錯誤或其他狀態變更時 (例如，因網路或驗證錯誤而暫時停用同步功能)，就會觸發這個事件。

參數