API Penyimpanan

Hampir setiap aspek pengembangan aplikasi melibatkan beberapa elemen pengiriman atau penerimaan data. Mulai dari dasar-dasarnya, Anda harus menggunakan framework MVC untuk membantu mendesain dan mengimplementasikan aplikasi sehingga data benar-benar terpisah dari tampilan aplikasi pada data tersebut (lihat Arsitektur MVC).

Anda juga perlu memikirkan cara penanganan data saat aplikasi sedang offline (lihat Offline Pertama). Dokumen ini secara singkat memperkenalkan opsi penyimpanan untuk mengirim, menerima, dan menyimpan data secara lokal; bagian lainnya dari dokumen ini menunjukkan cara menggunakan API Sistem File dan Sinkronisasi File Chrome (lihat juga fileSystem API dan syncFileSystem API).

Opsi penyimpanan

Aplikasi terpaket menggunakan berbagai mekanisme untuk mengirim dan menerima data. Untuk data eksternal (referensi, halaman), Anda harus memahami Kebijakan Keamanan Konten (CSP). Serupa dengan Ekstensi Chrome, Anda dapat menggunakan XMLHttpRequests lintas origin untuk berkomunikasi dengan server jarak jauh. Anda juga dapat mengisolasi halaman eksternal, sehingga bagian lain aplikasi Anda tetap aman (lihat Menyematkan halaman web eksternal).

Saat menyimpan data secara lokal, Anda dapat menggunakan Chrome Storage API untuk menyimpan sejumlah kecil data string dan IndexedDB untuk menyimpan data terstruktur. Dengan IndexedDB, Anda dapat mempertahankan objek JavaScript ke penyimpanan objek dan menggunakan indeks toko untuk membuat kueri data (untuk mempelajari lebih lanjut, lihat Tutorial Daftar Tugas Sederhana HTML5 Rock). Untuk semua jenis data lainnya, seperti data biner, gunakan Filesystem dan Sync Filesystem API.

API Sistem File dan Sinkronisasi File Chrome memperluas API Sistem File HTML5. Dengan Filesystem API Chrome, aplikasi dapat membuat, membaca, membuka, dan menulis ke bagian yang di-sandbox pada sistem file lokal pengguna. Misalnya, aplikasi berbagi foto dapat menggunakan Filesystem API untuk membaca dan menulis foto yang dipilih pengguna.

Dengan Sync Filesystem API Chrome, aplikasi dapat menyimpan dan menyinkronkan data di Google Drive pengguna, sehingga data yang sama dapat tersedia di berbagai klien yang berbeda. Misalnya, aplikasi editor teks yang didukung cloud dapat secara otomatis menyinkronkan file teks baru ke akun Google Drive pengguna. Saat pengguna membuka editor teks di klien baru, Google Drive akan mengirim file teks baru ke instance editor teks tersebut.

Menggunakan Chrome Filesystem API

Menambahkan izin sistem file

Untuk menggunakan File System API Chrome, Anda perlu menambahkan izin "fileSystem" ke manifes, sehingga Anda dapat memperoleh izin dari pengguna untuk menyimpan data persisten.

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

Opsi pengguna untuk memilih file

Pengguna ingin memilih file dengan cara yang sama seperti biasanya. Setidaknya, mereka mengharapkan tombol 'pilih file' dan pemilih file standar. Jika aplikasi Anda banyak menggunakan penyerahan file, Anda juga harus menerapkan fitur tarik lalu lepas (lihat di bawah ini dan lihat juga Tarik lalu Lepas HTML5 Native).

Mendapatkan jalur fileEntry

Untuk mendapatkan jalur lengkap file yang dipilih pengguna, fileEntry, panggil getDisplayPath():

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

Menerapkan tarik lalu lepas

Jika Anda perlu menerapkan pemilihan tarik lalu lepas, pengontrol file tarik lalu lepas (dnd.js) dalam contoh akses sistem file adalah titik awal yang baik. Pengontrol membuat entri file dari DataTransferItem melalui tarik lalu lepas. Dalam contoh ini, fileEntry disetel ke item pertama yang dilepas.

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

Membaca file

Kode berikut membuka file (hanya baca) dan membacanya sebagai teks menggunakan objek FileReader. Jika file tidak ada, error akan muncul.

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);
    });
    });
});

Menulis file

Dua kasus penggunaan umum untuk menulis file adalah "Simpan" dan "Simpan sebagai". Kode berikut membuat writableEntry dari chosenFileEntry hanya baca dan menulis file yang dipilih ke dalamnya.

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

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

Kode berikut membuat file baru dengan fungsi "Save as" dan menulis blob baru ke file menggunakan metode 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);
});

Menggunakan Chrome Sync Filesystem API

Dengan menggunakan penyimpanan file yang dapat disinkronkan, objek data yang ditampilkan dapat dioperasikan dengan cara yang sama seperti sistem file offline lokal di FileSystem API, tetapi dengan sinkronisasi tambahan (dan otomatis) dari data tersebut ke Google Drive.

Menambahkan izin sistem file sinkronisasi

Untuk menggunakan Sync Filesystem API Chrome, Anda perlu menambahkan izin "syncFileSystem" ke manifes, sehingga Anda dapat memperoleh izin dari pengguna untuk menyimpan dan menyinkronkan data persisten.

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

Memulai penyimpanan file yang dapat disinkronkan

Untuk memulai penyimpanan file yang dapat disinkronkan di aplikasi Anda, cukup panggil syncFileSystem.requestFileSystem. Metode ini menampilkan sistem file yang dapat disinkronkan dan didukung oleh Google Drive, misalnya:

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

Tentang status sinkronisasi file

Gunakan syncFileSystem.getFileStatus untuk mendapatkan status sinkronisasi file saat ini:

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

Nilai status sinkronisasi file dapat berupa salah satu dari berikut ini: 'synced', 'pending', atau 'conflicting'. 'Disinkronkan' berarti file disinkronkan sepenuhnya; tidak ada perubahan lokal yang tertunda yang belum disinkronkan ke Google Drive. Namun, mungkin ada perubahan tertunda di sisi Google Drive yang belum diambil.

'Tertunda' berarti file memiliki perubahan dalam proses yang belum disinkronkan ke Google Drive. Jika aplikasi berjalan secara online, perubahan lokal (hampir) segera disinkronkan ke Google Drive, dan peristiwa syncFileSystem.onFileStatusChanged diaktifkan dengan status 'synced' (lihat di bawah untuk detail selengkapnya).

syncFileSystem.onFileStatusChanged diaktifkan saat status file berubah menjadi 'conflicting'. 'Konflik' berarti ada perubahan yang bertentangan pada penyimpanan lokal dan Google Drive. File dapat berada dalam status ini hanya jika kebijakan resolusi konflik ditetapkan ke 'manual'. Kebijakan defaultnya adalah 'last_write_win' dan konflik akan otomatis diselesaikan dengan kebijakan last-write-win yang sederhana. Kebijakan resolusi konflik sistem dapat diubah melalui syncFileSystem.setConflictResolutionPolicy.

Jika kebijakan resolusi konflik disetel ke 'manual' dan file menghasilkan status 'conflicting', aplikasi masih dapat membaca dan menulis file sebagai file offline lokal, tetapi perubahan tersebut tidak disinkronkan dan file akan tetap terpisah dari perubahan jarak jauh yang dibuat pada klien lain hingga konflik diselesaikan. Cara termudah untuk menyelesaikan konflik adalah dengan menghapus atau mengganti nama file versi lokal. Hal ini memaksa versi jarak jauh untuk disinkronkan, status yang bertentangan akan diselesaikan, dan peristiwa onFileStatusChanged diaktifkan dengan status 'synced'.

Memproses perubahan dalam status yang disinkronkan

Peristiwa syncFileSystem.onFileStatusChanged diaktifkan saat status sinkronisasi file berubah. Misalnya, anggaplah file memiliki perubahan dalam proses dan berada dalam status 'tertunda'. Aplikasi mungkin dalam keadaan offline sehingga perubahan akan disinkronkan. Saat layanan sinkronisasi mendeteksi perubahan lokal yang tertunda dan mengupload perubahan tersebut ke Google Drive, layanan akan mengaktifkan peristiwa onFileStatusChanged dengan nilai berikut: { fileEntry:a fileEntry for the file, status: 'synced', action: 'updated', direction: 'local_to_remote' }.

Demikian pula, terlepas dari aktivitas lokalnya, layanan sinkronisasi mungkin mendeteksi perubahan jarak jauh yang dilakukan oleh klien lain, dan mendownload perubahan tersebut dari Google Drive ke penyimpanan lokal. Jika perubahan jarak jauh dimaksudkan untuk menambahkan file baru, peristiwa dengan nilai berikut akan diaktifkan: { fileEntry: a fileEntry for the file, status: 'synced', action: 'added', direction: 'remote_to_local' }.

Jika sisi lokal dan jarak jauh memiliki perubahan yang bertentangan untuk file yang sama dan jika kebijakan resolusi konflik disetel ke 'manual', status file akan diubah menjadi status conflicting, dilepas dari layanan sinkronisasi, dan tidak akan disinkronkan hingga konflik diselesaikan. Dalam hal ini, peristiwa dengan nilai berikut akan diaktifkan: { fileEntry: a fileEntry for the file, status: 'conflicting', action: null, direction: null }.

Anda dapat menambahkan pemroses untuk peristiwa ini yang merespons setiap perubahan status. Misalnya, aplikasi Chrome Music Player akan memproses musik baru yang disinkronkan dari Google Drive, tetapi belum diimpor ke penyimpanan lokal pengguna pada klien tertentu. Setiap musik yang ditemukan akan disinkronkan ke klien tersebut:

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);
      }
    }
  }
});

Memeriksa penggunaan API

Untuk memeriksa jumlah data yang digunakan oleh API, buat kueri direktori dengan sandbox lokal aplikasi atau byte penggunaan yang ditampilkan oleh syncFileSystem.getUsageAndQuota:

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

Anda juga dapat melihat penyimpanan layanan backend sinkronisasi pengguna (di Google Drive). File yang disinkronkan disimpan di folder Google Drive tersembunyi, Chrome Syncable FileSystem. Folder tersebut tidak akan ditampilkan dalam daftar 'Drive Saya', tetapi dapat diakses dengan mencari namanya di kotak penelusuran. (Perhatikan bahwa tata letak folder jarak jauh tidak dijamin akan tetap kompatibel dengan versi lama di antara rilis.)