Storage API

應用程式開發作業的每個環節，幾乎都牽涉到傳送或接收資料的某些環節。正在啟動 基本概念，建議你運用 MVC 架構設計和實作應用程式， 資料與應用程式的資料檢視畫面完全無關 (請參閱「MVC 架構」)。

您也必須思考應用程式離線時的資料處理方式 (請參閱離線資料)。 本文件將簡單介紹用於在本機傳送、接收及儲存資料的儲存空間選項。這個 請參閱其他說明文件，瞭解如何使用 Chrome 的檔案系統和 Sync File System API (請參閱 fileSystem API 和 syncFileSystem API)。

儲存空間選項

封裝應用程式會使用許多不同機制來傳送及接收資料。外部資料 (資源 網頁)，您必須留意內容安全政策 (CSP)。與 Chrome 類似 擴充功能可讓您使用 cross-origin XMLHttpRequests 與遠端伺服器通訊。個人中心 也可以隔離外部網頁，讓應用程式的其餘部分安全無虞 (請參閱嵌入外部網站 網頁)。

如果將資料儲存在本機，您可以使用 Chrome Storage API 儲存少量字串。 和 IndexedDB 來儲存結構化資料透過 IndexedDB，您可以將 JavaScript 物件保存在 物件儲存，並使用商店的索引查詢資料 (詳情請參閱 HTML5 Rock 的簡易待辦事項一文) 清單教學課程)。至於其他類型的資料 (例如二進位資料)，請使用「檔案系統」和「同步處理」 檔案系統 API。

Chrome 的檔案系統和同步檔案系統 API 是 HTML5 FileSystem API 的延伸功能。Chrome Filesystem API，應用程式可以建立、讀取、瀏覽及寫入使用者的沙箱區塊 本機檔案系統舉例來說，相片分享應用程式可以使用 Filesystem API 讀取及寫入任何檔案 使用者選取的相片

透過 Chrome 的 Sync Filesystem API，應用程式就能儲存及同步處理使用者 Google 雲端硬碟中的資料， 因為不同的用戶端都能取得相同的資料例如，「雲端支援的文字」 編輯器應用程式可自動將新文字檔案同步到使用者的 Google 雲端硬碟帳戶。當 使用者在新用戶端中開啟文字編輯器後，Google 雲端硬碟會將新的文字檔案推送至該執行個體： 找到文字編輯器

使用 Chrome Filesystem API

正在新增檔案系統權限

如要使用 Chrome 的 File System API，請新增「fileSystem」授予資訊清單的權限，因此 以便您向使用者取得權限，以便儲存永久資料。

"permissions": [
  "...",
  "fileSystem"
]

選取檔案的使用者選項

使用者期望使用與平常相同的方式選取檔案。至少要有 檔案」按鈕和標準檔案選擇器如果您的應用程式會大量使用檔案處理，您也應該 實作拖曳功能 (請參閱下文並參考原生 HTML5 拖曳功能)。

取得 fileEntry 的路徑

如要取得使用者所選檔案的完整路徑 (fileEntry)，請呼叫 getDisplayPath()：

function displayPath(fileEntry) {
  chrome.fileSystem.getDisplayPath(fileEntry, function(path) {
    console.log(path)
  });
}

實作拖曳功能

如果您需要實作拖曳選取功能，請在dnd.js filesystem-access 範例是很好的起點。控制器會建立檔案項目 透過拖曳功能從 DataTransferItem 擷取。在此範例中，fileEntry 設定為 捨棄的項目

var dnd = new DnDFileController('body', function(data) {
  var fileEntry = data.items[0].webkitGetAsEntry();
  displayPath(fileEntry);
});

讀取檔案

下列程式碼會開啟檔案 (唯讀)，並使用 FileReader 物件將其讀取為文字。如果 檔案不存在，系統就會擲回錯誤。

var chosenFileEntry = null;

chooseFileButton.addEventListener('click', function(e) {
  chrome.fileSystem.chooseEntry({type: 'openFile'}, function(readOnlyEntry) {

    readOnlyEntry.file(function(file) {
      var reader = new FileReader();

      reader.onerror = errorHandler;
      reader.onloadend = function(e) {
        console.log(e.target.result);
      };

      reader.readAsText(file);
    });
    });
});

寫入檔案

寫入檔案的兩種常見用途是「儲存」和「另存新檔」下列程式碼會建立 從唯讀 chosenFileEntry 匯出 writableEntry，並將選取的檔案寫入其中。

 chrome.fileSystem.getWritableEntry(chosenFileEntry, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = callback;

    chosenFileEntry.file(function(file) {
      writer.write(file);
    });
  }, errorHandler);
});

下列程式碼會建立含有「另存新檔」的新檔案並將新 blob 寫入 透過 writer.write() 方法處理這個檔案

chrome.fileSystem.chooseEntry({type: 'saveFile'}, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = function(e) {
        console.log('write complete');
      };
      writer.write(new Blob(['1234567890'], {type: 'text/plain'}));
    }, errorHandler);
});

使用 Chrome 同步 Filesystem API

使用可同步檔案儲存空間，傳回的資料物件和本機一樣 儲存檔案系統 FileSystem API 中的離線檔案系統，不過再加上自動同步處理該 API 的 將資料匯出至 Google 雲端硬碟

正在新增同步處理檔案系統權限

如要使用 Chrome 的 Sync Filesystem API，請先新增「syncFileSystem」授予「 資訊清單，方便您向使用者取得權限，以便儲存及同步處理永久資料。

"permissions": [
  "...",
  "syncFileSystem"
]

正在啟動可同步處理的檔案儲存空間

如要在應用程式中啟動可同步處理的檔案儲存空間，只要呼叫 syncFileSystem.requestFileSystem 即可。 這個方法會傳回由 Google 雲端硬碟支援的可同步檔案系統，例如：

chrome.syncFileSystem.requestFileSystem(function (fs) {
   // FileSystem API should just work on the returned 'fs'.
   fs.root.getFile('test.txt', {create:true}, getEntryCallback, errorCallback);
});

關於檔案同步處理狀態

使用 syncFileSystem.getFileStatus 取得目前檔案的同步處理狀態：

chrome.syncFileSystem.getFileStatus(entry, function(status) {...});

檔案同步處理狀態可能是下列其中一種：'synced'、'pending' 或 'conflicting'。 「已同步」代表檔案已完全同步。沒有尚未處理的本機變更 已同步到 Google 雲端硬碟但 Google 雲端硬碟可能有待變更項目 如果是尚未擷取的內容

待處理表示檔案有待變更項目尚未同步到 Google 雲端硬碟。如果應用程式 在本機執行時，本機變更會 (幾乎) 立即同步到 Google 雲端硬碟，而 syncFileSystem.onFileStatusChanged 事件就會以 'synced' 狀態觸發 (請參閱下方說明 瞭解詳情)。

檔案的狀態變更為 syncFileSystem.onFileStatusChanged 時，就會觸發 'conflicting'。「衝突」就表示本機儲存空間和本機儲存空間 Google 雲端硬碟。只有在衝突解決政策設為 'manual'。預設政策為 'last_write_win'，衝突會自動解決 簡單的最終寫入政策系統的衝突解決政策可在以下時間點變更： syncFileSystem.setConflictResolutionPolicy.

如果將衝突解決政策設為 'manual'，且檔案導致 'conflicting' 狀態， 應用程式仍可在本機離線檔案中讀取及寫入檔案，但系統不會同步處理變更內容 檔案會從其他用戶端的遠端變更加以卸離，直到衝突發生為止 均已解決。解決衝突最簡單的方法，就是刪除或重新命名本機檔案。 這會強制同步處理遠端版本、解決衝突狀態，然後 onFileStatusChanged 事件會以 'synced' 狀態觸發。

監聽同步狀態的變更

檔案的同步狀態變更時，會觸發 syncFileSystem.onFileStatusChanged 事件。 舉例來說，假設檔案有待處理的變更，且在「待處理」時間。應用程式可能是 離線狀態，因此系統將要同步處理變更。同步處理服務偵測到 待本機變更並將變更上傳到 Google 雲端硬碟後，服務會觸發 onFileStatusChanged 事件，包含下列值： { fileEntry:a fileEntry for the file, status: 'synced', action: 'updated', direction: 'local_to_remote' }。

同樣地，無論本機活動為何，同步服務都可以偵測 ，然後將變更從 Google 雲端硬碟下載至本機儲存空間。如果遙控器 change 是新增檔案，會觸發包含下列值的事件： { fileEntry: a fileEntry for the file, status: 'synced', action: 'added', direction: 'remote_to_local' }。

如果本機和遠端端對同一個檔案所做的變更相互衝突 解析度政策設為「'manual'」，檔案狀態變更為 conflicting 狀態， 從同步處理服務中卸離，直到衝突解決為止。在本 會發生下列情況： { fileEntry: a fileEntry for the file, status: 'conflicting', action: null, direction: null }。

您可以為這個事件新增事件監聽器，以回應狀態的任何變更。舉例來說， Chrome 音樂播放器應用程式會聆聽從 Google 雲端硬碟同步的新音樂，但尚未監聽 會經由特定用戶端匯入使用者的本機儲存空間。發現的任何音樂都會同步處理至該位置 用戶端：

chrome.syncFileSystem.onFileStatusChanged.addListener(function(fileInfo) {
  if (fileInfo.status === 'synced') {
    if (fileInfo.direction === 'remote_to_local') {
      if (fileInfo.action === 'added') {
        db.add(fileInfo.fileEntry);
      } else if (fileInfo.action === 'deleted') {
        db.remove(fileInfo.fileEntry);
      }
    }
  }
});

檢查 API 使用情況

如要查看 API 使用的資料量，請查詢應用程式的本機沙箱目錄，或 syncFileSystem.getUsageAndQuota 傳回的用量位元組數：

chrome.syncFileSystem.getUsageAndQuota(fileSystem, function (storageInfo) {
   updateUsageInfo(storageInfo.usageBytes);
   updateQuotaInfo(storageInfo.quotaBytes);
});

您也可以查看使用者的同步處理後端服務儲存空間 (位於 Google 雲端硬碟中)。同步的檔案為 儲存在隱藏的 Google 雲端硬碟資料夾中，也就是 Chrome 可同步檔案系統。該資料夾不會顯示在下列位置： 您的「我的雲端硬碟」但只要搜尋搜尋框中的資料夾名稱即可存取。(請注意， 遠端資料夾的版面配置不保證可在發布後維持回溯相容性)。