chrome.syncFileSystem

說明

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

權限

syncFileSystem

類型

ConflictResolutionPolicy

列舉

"last_write_win"

"manual"

FileInfo

屬性

  • 動作

    SyncAction 選用

    同步處理觸發 onFileStatusChanged 事件的動作。動作值可以是 'added'、'updated' 或 'deleted'。只有在狀態為「'synced'」時才能使用。

  • direction

    SyncDirection 選用

    onFileStatusChanged 事件的同步處理方向。同步處理方向值可以是 'local_to_remote' 或 'remote_to_local'。只有在狀態為「'synced'」時才能使用。

  • fileEntry

    項目

    fileEntry。包含已同步檔案的名稱和路徑資訊。刪除檔案後，你仍可存取fileEntry資訊，但檔案會不存在。

  • status

    FileStatus

    在 onFileStatusChanged 事件之後產生的檔案狀態。狀態值可以是 'synced'、'pending' 或 'conflicting'。

FileStatus

列舉

「已同步處理」
未發生衝突，且沒有待處理的本機變更。

"pending"
有一或多個待處理的本機變更尚未同步處理。

"conflicting"
檔案與遠端版本相衝突，必須手動解決。

FileStatusInfo

屬性

  • 錯誤

    字串 選用

    選用錯誤，只有在擷取指定檔案的 FileStatus 時發生問題時，才會傳回此錯誤。

  • fileEntry

    項目

    該項目最初指定為 getFileStatuses。

  • status

    FileStatus

    狀態值可以是 'synced'、'pending' 或 'conflicting'。

ServiceInfo

屬性

ServiceStatus

列舉

"initializing"
正在初始化同步處理服務 (例如從資料庫還原資料、檢查連線能力及驗證服務等)。

"running"
同步處理服務現已啟動且正在執行。

"authentication_required"
必須驗證遠端服務才能繼續操作，同步處理服務不會同步處理檔案。

"temporary_unavailable"
由於某些可復原的錯誤 (例如網路處於離線、遠端服務中斷或無法存取等) 導致遠端服務 (暫時) 無法使用，因此同步處理服務無法同步處理檔案。詳情請參閱 OnServiceInfoUpdated 中的 description 參數 (可能包含服務專屬詳細資料)。

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

StorageInfo

屬性

  • quotaBytes

    號碼

  • usageBytes

    號碼

SyncAction

列舉

SyncDirection

列舉

"local_to_remote"

"remote_to_local"

方法

getConflictResolutionPolicy()

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

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

參數

傳回

  • Chrome 117 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getFileStatus()

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

傳回指定 fileEntry 的 FileStatus。狀態值可以是 'synced'、'pending' 或 'conflicting'。請注意，只有在服務的衝突解決政策設為 'manual' 時，系統才會發生 'conflicting' 狀態。

參數

  • fileEntry

    項目

  • 回呼

    函式選用

    callback 參數如下所示： 

    (status: FileStatus)=>void

傳回

  • Promise<FileStatus>

    Chrome 117 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getFileStatuses()

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

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

參數

傳回

  • Promise<FileStatusInfo[]>

    Chrome 117 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getServiceStatus()

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

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

參數

傳回

  • Promise<ServiceStatus>

    Chrome 117 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getUsageAndQuota()

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

傳回應用程式 'syncable' 檔案儲存空間目前的用量和配額 (以位元組為單位)。

參數

  • fileSystem

    DOMFileSystem

  • 回呼

    函式選用

    callback 參數如下所示： 

    (info: StorageInfo)=>void

傳回

  • Promise<StorageInfo>

    Chrome 117 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

requestFileSystem()

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

傳回 Google 雲端硬碟支援的可同步處理檔案系統。傳回的 DOMFileSystem 執行個體可以採用與臨時和永久檔案系統相同的方式運作 (請參閱 http://dev.w3.org/2009/dap/file-system/file-dir-sys.html)。

從同一個應用程式多次呼叫此方法，會將相同的控制代碼傳回相同的檔案系統。

請注意，這項呼叫會失敗。例如使用者未登入 Chrome 或沒有任何網路操作。為處理這些錯誤，必須在回呼中檢查 chrome.runtime.lastError。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (fileSystem: DOMFileSystem)=>void

    • fileSystem

      DOMFileSystem

傳回

  • Promise<DOMFileSystem>

    Chrome 117 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

setConflictResolutionPolicy()

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

為應用程式的 'syncable' 檔案儲存空間設定預設的衝突解決政策。預設為 'last_write_win'。如果將現有檔案的衝突解決政策設為 'last_write_win'，系統會在檔案下次更新時自動解決相關問題。您可以選擇提供 callback，以便瞭解要求是否成功。

參數

傳回

  • Promise<void>

    Chrome 117 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

活動

onFileStatusChanged

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (detail: FileInfo)=>void

onServiceStatusChanged

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

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

參數