Serialisasi

Serialisasi menyimpan status ruang kerja Anda agar dapat dimuat kembali ke ruang kerja nanti. Hal ini termasuk melakukan serialisasi status blok, variabel, atau plugin yang ingin Anda simpan. Anda dapat mengonversi semua data yang perlu disimpan ke dalam format berbasis teks agar mudah disimpan, lalu memuat kembali data tersebut ke ruang kerja yang berfungsi penuh nanti.

Blockly menyediakan dua format untuk data ini: JSON dan XML. Sebaiknya gunakan sistem JSON untuk project baru, dan dorong project lama menggunakan XML untuk melakukan upgrade. Sistem XML adalah format simpan lama. Kartu ini tidak akan dihapus, tetapi tidak akan menerima fitur baru.

Sistem JSON

Catatan: Untuk mendapatkan informasi tentang cara bermigrasi ke JSON dari XML, lihat panduan migrasi.

Sistem serialisasi JSON terdiri dari beberapa serialisasi. Terdapat serialisasi bawaan untuk blok dan variabel, dan Anda juga dapat mendaftarkan serialisasi tambahan. Setiap serialisasi bertanggung jawab untuk melakukan serialisasi dan deserialisasi status plugin atau sistem tertentu.

Menyimpan dan Memuat

Ruang kerja

Anda dapat melakukan serialisasi atau deserialisasi status seluruh ruang kerja dengan memanggil metode save dan load pada namespace workspaces.

const state = Blockly.serialization.workspaces.save(myWorkspace);
Blockly.serialization.workspaces.load(state, myWorkspace);

Panggilan ini melakukan serialisasi atau deserialisasi semua sistem individual (diwakili oleh penserialisasi) yang terdaftar dengan ruang kerja.

Blok individual

Anda dapat melakukan serialisasi atau deserialisasi blok individual dengan memanggil metode save dan append pada namespace blocks.

const blockJson = Blockly.serialization.blocks.save(myBlock);
const duplicateBlock =
    Blockly.serialization.blocks.append(blockJson, myWorkspace);

Sistem individual

Anda dapat melakukan serialisasi atau deserialisasi setiap sistem (misalnya, blok, variabel, plugin, dll.) dengan membuat serialisasi terkait, serta memanggil metode save dan load.

// Saves only the variables information for the workspace.
const serializer = new Blockly.serialization.variables.VariableSerializer();
const state = serializer.save(myWorkspace);
serializer.load(state, myWorkspace);

Urutan deserialisasi

Sistem JSON memiliki urutan deserialisasi eksplisit, yang memudahkan pencegahan duplikasi status dalam penyimpanan.

Saat Blockly.serialization.workspaces.load dipanggil, penserialisasi diberi status untuk melakukan deserialisasi dalam urutan prioritas. Hal ini dijelaskan lebih lanjut di bagian Penserialisasi, dan tujuannya adalah untuk memungkinkan serialisasi bergantung pada status dari sistem lain.

Urutan deserialisasi serialisasi bawaan adalah:

1. Variabel akan dideserialisasi.
2. Pemblokiran dideserialisasi. Stack atau blok level atas individual dideserialisasi dalam urutan arbitrer.
   1. Jenis dideserialisasi. Tindakan ini akan memicu metode init blok, mencampurkan ekstensi, dll.
   2. Atribut dideserialisasi. Ini mencakup properti yang dapat diterapkan ke blok mana pun. Misalnya: x, y, diciutkan, dinonaktifkan, data, dll.
   3. Status tambahan dideserialisasi. Lihat dokumentasi Ekstensi dan Mutator untuk info selengkapnya.
   4. Pemblokiran terhubung ke induknya (jika ada).
   5. Ikon dideserialisasi. Setiap ikon dideserialisasi dalam urutan arbitrer.
   6. Kolom deserialisasi dilakukan. Setiap kolom dideserialisasi dalam urutan arbitrer.
   7. Blok input dideserialisasi. Ini termasuk blok yang terhubung ke input nilai dan input pernyataan. Tiap input dideserialisasi dalam urutan arbitrer.
   8. Blok berikutnya akan dideserialisasi.

Kapan harus menyimpan status tambahan

Untuk blok, jika Anda memiliki sesuatu yang lebih rendah dalam urutan yang bergantung pada sesuatu yang lebih tinggi dalam urutan, Anda harus menduplikasi data tersebut dan menambahkannya ke status tambahan.

Misalnya, jika Anda memiliki kolom yang hanya ada jika blok berikutnya terhubung, Anda harus menambahkan info tentang blok berikutnya ke status tambahan, sehingga kolom tersebut dapat ditambahkan ke blok Anda sebelum status kolom dideserialisasi.

Namun, jika memiliki input yang hanya ada jika suatu kolom memiliki nilai tertentu, Anda tidak perlu menambahkan info tentang kolom tersebut ke status ekstra. Hal ini karena status kolom Anda akan dideserialisasi terlebih dahulu, dan jika ya, Anda dapat menambahkan input ke blok. Biasanya penambahan input akan dipicu oleh validator.

Perhatikan bahwa aturan tentang status duplikat juga harus memperhitungkan bahwa stack blok, ikon, kolom, dan blok input di-deserialisasi dalam urutan arbitrer. Misalnya, jika Anda memiliki satu kolom B yang hanya ada jika kolom A lain memiliki nilai tertentu, Anda harus menambahkan info tentang A ke status tambahan jika B dideserialisasi sebelum A.

Hook blok

Untuk mengetahui informasi tentang cara menambahkan serialisasi tambahan ke blok, lihat dokumentasi Ekstensi dan Mutator.

Hook lapangan

Untuk mengetahui informasi tentang cara melakukan serialisasi kolom, lihat dokumentasi Kolom kustom.

Hook penserialisasi

Sistem JSON memungkinkan Anda mendaftarkan penserialisasi yang melakukan serialisasi dan melakukan deserialisasi beberapa status. Serializer bawaan Blockly menangani informasi serialisasi tentang blok dan variabel, tetapi jika ingin membuat serialisasi informasi lain, Anda harus menambahkan serializer Anda sendiri. Misalnya, komentar tingkat ruang kerja tidak diserialisasi secara default oleh sistem JSON. Jika ingin melakukan serialisasi, Anda harus mendaftarkan penserialisasi tambahan.

Penserialisasi tambahan sering digunakan untuk melakukan serialisasi dan mendeserialisasi status plugin.

Blockly.serialization.registry.register(
    'workspace-comments',  // Name
    {
      save: saveFn,      // Save function
      load: loadFn,      // Load function
      clear: clearFn,    // Clear function
      priority: 10,      // Priority
    });

Saat mendaftarkan penserialisasi, Anda harus memberikan beberapa hal:

• Nama untuk serialisasi, tempat data juga disimpan.
• Fungsi untuk melakukan save status plugin/sistem yang terkait dengan serializer.
• Fungsi untuk clear status.
• Fungsi untuk load status.

• priority, yang digunakan untuk menentukan urutan deserialisasi.

  Anda dapat mendasarkan prioritas serialisasi pada prioritas bawaan

Saat Blockly.serialization.workspaces.save dipanggil, setiap fungsi save serializer akan dipanggil, dan datanya akan ditambahkan ke output JSON akhir:

{
  "blocks": { ... },
  "workspaceComments": [ // Provided by workspace-comments serializer
    {
      "x": 239,
      "y": 31,
      "text": "Add 2 + 2"
    },
    // etc...
  ]
}

Saat Blockly.serialization.workspaces.load dipanggil, setiap serialisasi akan dipicu sesuai urutan prioritas. Penserialisasi dengan nilai prioritas yang lebih positif akan dipicu sebelum penserialisasi dengan nilai prioritas yang lebih sedikit positif.

Saat serialisasi dipicu, ada dua hal yang akan terjadi:

1. Fungsi clear yang disediakan dipanggil. Cara ini memastikan bahwa status plugin/sistem Anda bersih sebelum lebih banyak status dimuat. Misalnya, penserialisasi komentar workspace-komentar akan menghapus semua komentar yang ada dari ruang kerja.
2. Fungsi load yang disediakan dipanggil.

Sistem XML

Sistem XML memungkinkan Anda melakukan serialisasi ruang kerja ke node XML. Ini adalah sistem serialisasi asli Blockly. Situs tersebut telah dibekukan, yang berarti aplikasi tidak akan menerima fitur baru. Oleh karena itu, sebaiknya gunakan sistem JSON jika memungkinkan.

Catatan: Untuk mendapatkan informasi tentang cara bermigrasi ke JSON, lihat panduan migrasi.

API

Untuk informasi tentang API sistem XML, lihat dokumentasi referensi.

Hook blok

Untuk mengetahui informasi tentang cara menambahkan serialisasi tambahan ke blok, lihat dokumentasi Ekstensi dan Mutator.

Hook lapangan

Untuk mengetahui informasi tentang cara melakukan serialisasi kolom, lihat dokumentasi Kolom kustom.

Memilih antara JSON dan XML

Sebaiknya gunakan serialisasi JSON, bukan XML. Sistem JSON memungkinkan Anda melakukan serialisasi status ruang kerja ke objek JavaScript. Ini menguntungkan karena:

1. JSON mudah dikompresi atau dikonversi ke format lain.
2. JSON mudah digunakan secara terprogram.
3. JSON mudah untuk diperluas dan menambahkan data.

Selain itu, sistem XML tidak akan lagi menerima update, dan sudah tidak memiliki fitur dibandingkan dengan serialisasi JSON. Misalnya, Anda dapat mendaftarkan serializer JSON Anda sendiri untuk menyimpan dan memuat data tambahan dengan mudah, seperti data untuk plugin atau penyesuaian yang telah Anda tambahkan. Hal ini tidak mungkin dilakukan dalam sistem XML.

Jika sebelumnya Anda telah menggunakan serialisasi XML, lihat panduan migrasi untuk mengetahui informasi tentang cara mengupgrade.