API Penyimpanan

Hampir setiap aspek pengembangan aplikasi melibatkan beberapa elemen pengiriman atau penerimaan data. Memulai dengan dasar-dasarnya, Anda harus menggunakan kerangka kerja MVC untuk membantu mendesain dan mengimplementasikan aplikasi sehingga data terpisah sepenuhnya 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; tindakan dokumen ini menunjukkan cara menggunakan API Sistem File dan Sinkronisasi Sistem File Chrome (lihat juga fileSystem API dan syncFileSystem API).

Opsi penyimpanan

Aplikasi terpaket menggunakan berbagai mekanisme untuk mengirim dan menerima data. Untuk data eksternal (sumber daya, halaman web), Anda perlu mengetahui Kebijakan Keamanan Konten (CSP). Mirip dengan Chrome Ekstensi, Anda dapat menggunakan XMLHttpRequests lintas origin untuk berkomunikasi dengan server jarak jauh. Anda juga dapat mengisolasi halaman eksternal, sehingga seluruh aplikasi Anda aman (lihat Menyematkan web eksternal halaman).

Saat menyimpan data secara lokal, Anda dapat menggunakan Chrome Storage API untuk menyimpan string dalam jumlah kecil data dan IndexedDB untuk menyimpan data terstruktur. Dengan BYOD, Anda dapat mempertahankan objek JavaScript ke menyimpan objek dan menggunakan indeks toko untuk mengkueri data (untuk mempelajari lebih lanjut, lihat Simple Todo” HTML5 Rock Daftar Tutorial). Untuk semua jenis data lainnya, seperti data biner, gunakan Filesystem dan Sync API sistem file.

API Sistem File dan Sinkronisasi Filesystem Chrome memperluas HTML5 FileSystem API. Dengan API sistem file, aplikasi bisa membuat, membaca, menavigasi, dan menulis ke bagian dalam sandbox sistem file lokal. 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 bahwa data yang sama dapat tersedia di klien yang berbeda. Misalnya, teks yang didukung cloud Google Drive dapat otomatis menyinkronkan file teks baru ke akun Google Drive pengguna. Jika membuka editor teks di klien baru, Google Drive mendorong file teks baru ke instance editor teks.

Menggunakan Chrome Filesystem API

Menambahkan izin sistem file

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

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

Opsi pengguna untuk memilih file

Pengguna ingin memilih file dengan cara yang sama seperti biasanya. Setidaknya, mereka mengharapkan tindakan file' dan pemilih file standar. Jika aplikasi Anda banyak menggunakan serangan file, Anda juga harus terapkan tarik lalu lepas (lihat di bawah dan juga lihat 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 mengimplementasikan pilihan tarik lalu lepas, pengontrol file tarik lalu lepas (dnd.js) di contoh filesystem-access adalah titik awal yang baik. Pengontrol membuat entri file dari DataTransferItem melalui tarik lalu lepas. Dalam contoh ini, fileEntry disetel ke class pertama item yang ditinggalkan.

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

Membaca file

Kode berikut akan membuka file (hanya baca) dan membacanya sebagai teks menggunakan objek FileReader. Jika file tidak ada, maka akan muncul pesan {i>error<i}.

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 "Save" dan "Simpan sebagai". Kode berikut membuat writableEntry dari chosenFileEntry hanya baca dan menulis file yang dipilih ke sana.

 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 "Save as" fungsionalitasnya, dan menulis blob baru itu 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 dikembalikan dapat dioperasikan dengan cara yang sama seperti sistem file offline di FileSystem API, tetapi dengan sinkronisasi tambahan (dan otomatis) data ke Google Drive.

Menambahkan izin sistem file sinkronisasi

Untuk menggunakan Sync Filesystem API Chrome, Anda perlu menambahkan "syncFileSystem" izin ke manifes, sehingga Anda bisa mendapatkan 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 untuk file saat ini:

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

Nilai status sinkronisasi file dapat berupa salah satu dari nilai berikut: 'synced', 'pending', atau 'conflicting'. 'Disinkronkan' berarti file disinkronkan sepenuhnya; tidak ada perubahan lokal tertunda yang belum disinkronkan ke Google Drive. Namun, mungkin saja ada perubahan yang menunggu keputusan 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 secara lebih terperinci).

syncFileSystem.onFileStatusChanged diaktifkan saat status file berubah menjadi 'conflicting'. 'Bertentangan' berarti ada perubahan yang bertentangan pada penyimpanan lokal dan Google Drive. File dapat berada dalam status ini hanya jika kebijakan resolusi konflik disetel ke 'manual'. Kebijakan defaultnya adalah 'last_write_win' dan konflik akan otomatis diselesaikan oleh kebijakan {i>last-write-win<i} yang sederhana. Kebijakan resolusi konflik sistem dapat diubah dengan 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 tidak disinkronkan dan file akan tetap terlepas dari perubahan jarak jauh yang dilakukan pada klien lain sampai konflik diselesaikan. Cara termudah untuk menyelesaikan konflik adalah dengan menghapus atau mengganti nama file versi lokal. Hal ini memaksa versi jarak jauh untuk disinkronkan, keadaan yang berkonflik telah diselesaikan, dan Peristiwa onFileStatusChanged diaktifkan dengan status 'synced'.

Memproses perubahan status yang disinkronkan

Peristiwa syncFileSystem.onFileStatusChanged diaktifkan saat status sinkronisasi file berubah. Misalnya, asumsikan file memiliki perubahan yang tertunda dan berada dalam status 'tertunda' status. Aplikasi ini mungkin telah dalam kondisi offline sehingga perubahan akan segera disinkronkan. Bila layanan sinkronisasi mendeteksi perubahan lokal yang tertunda dan mengunggah 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 lokal, layanan sinkronisasi dapat mendeteksi perubahan jarak jauh yang dibuat oleh klien lain, dan mengunduh perubahan dari Google Drive ke penyimpanan lokal. Jika remote perubahan adalah 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 konflik kebijakan resolusi disetel ke 'manual', status file diubah menjadi status conflicting, dilepaskan dari layanan sinkronisasi, dan tidak akan disinkronkan hingga konflik diselesaikan. Di sini jika peristiwa dengan nilai berikut 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 Pemutar Musik Chrome mendengarkan musik baru yang disinkronkan dari Google Drive, namun belum disinkronkan diimpor ke penyimpanan lokal pengguna pada klien tertentu. Musik apa pun yang ditemukan akan disinkronkan dengannya klien:

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, lakukan kueri ke direktori 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 adalah yang disimpan di folder Google Drive tersembunyi, Chrome Syncable FileSystem. Folder tidak akan ditampilkan di 'Drive Saya' Anda daftar tetapi dapat diakses dengan mencari nama folder di kotak penelusuran. (Perhatikan bahwa tata letak folder jarak jauh tidak dijamin akan tetap kompatibel dengan versi lama antar-rilis.)