Membuat jenis kolom baru

Sebelum membuat jenis kolom baru, pertimbangkan apakah salah satu metode untuk menyesuaikan {i>field<i} sesuai dengan kebutuhan Anda. Jika aplikasi Anda perlu menyimpan jenis nilai baru, atau ingin membuat UI baru untuk jenis nilai yang ada, Anda mungkin perlu membuat tipe isian baru.

Untuk membuat kolom baru, lakukan langkah berikut:

1. Implementasikan konstruktor.
2. Daftarkan kunci JSON dan implementasikan fromJson.
3. Menangani inisialisasi peristiwa dan UI on-block pemroses.
4. Menangani pembuangan pemroses peristiwa (pembuangan UI ditangani untuk Anda).
5. Terapkan penanganan nilai.
6. Tambahkan representasi teks dari nilai kolom Anda, untuk aksesibilitas.
7. Tambahkan fungsi tambahan seperti:
   • Editor.
   • Pembaruan tampilan pada pemblokiran.
   • Serialisasi.
8. Konfigurasi aspek tambahan kolom, seperti:
   • Dapat diedit dan diserialisasi properti
   • Kursor

Bagian ini mengasumsikan bahwa Anda telah membaca dan mengetahui konten dalam Anatomi Kolom.

Untuk contoh bidang khusus, lihat Bidang Khusus demo kami.

Mengimplementasikan konstruktor

Konstruktor kolom bertanggung jawab untuk menyiapkan nilai awal kolom dan secara opsional menyiapkan validator. Kustom Konstruktor kolom dipanggil selama inisialisasi blok sumber, terlepas dari apakah blok sumber didefinisikan dalam JSON atau JavaScript. Jadi, kustom tidak memiliki akses ke blok sumber selama pembuatan.

Contoh kode berikut membuat kolom kustom bernama GenericField:

class GenericField extends Blockly.Field {
  constructor(value, validator) {
    super(value, validator);

    this.SERIALIZABLE = true;
  }
}

Tanda tangan metode

Konstruktor kolom biasanya mengambil nilai dan validator lokal. Nilainya adalah opsional, dan jika Anda tidak meneruskan nilai (atau Anda meneruskan nilai yang gagal dalam class validasi) maka nilai default superclass akan digunakan. Untuk class Field default, nilainya adalah null. Jika Anda tidak ingin menggunakan nilai, maka pastikan untuk meneruskan nilai yang sesuai. Parameter validator hanya ada untuk bidang yang dapat diedit dan biasanya ditandai sebagai opsional. Pelajari lebih lanjut validator di kolom Validator dokumen.

Struktur

Logika di dalam konstruktor Anda harus mengikuti alur ini:

1. Panggil konstruktor super yang diwarisi (semua kolom kustom harus mewarisi dari Blockly.Field atau salah satu subclass-nya) untuk menginisialisasi nilai dengan benar dan setel validator lokal untuk kolom Anda.
2. Jika kolom Anda dapat diserialisasi, tetapkan properti yang sesuai di . Kolom yang dapat diedit harus dapat diserialisasi, dan kolom dapat diedit secara {i>default<i}, jadi Anda harus mengatur properti ini ke true kecuali Anda mengetahui data itu tidak boleh diserialisasi.
3. Opsional: Menerapkan penyesuaian tambahan (misalnya, Kolom label meneruskan kelas css, yang kemudian diterapkan ke teks).

JSON dan pendaftaran

Dalam blok JSON definisi, kolom dijelaskan oleh string (misalnya, field_number, field_textinput). Blockly mengelola peta dari string ini ke objek kolom, dan memanggil fromJson pada objek yang sesuai selama konstruksi.

Panggil Blockly.fieldRegistry.register untuk menambahkan jenis kolom Anda ke peta ini, meneruskan class kolom sebagai argumen kedua:

Blockly.fieldRegistry.register('field_generic', GenericField);

Anda juga perlu menentukan fungsi fromJson. Implementasi Anda harus pertama-tama batalkan referensi string tabel referensi menggunakan replaceMessageReferences, dan kemudian teruskan nilai-nilainya ke konstruktor.

GenericField.fromJson = function(options) {
  const value = Blockly.utils.parsing.replaceMessageReferences(
      options['value']);
  return new CustomFields.GenericField(value);
};

Catatan: Validator lokal saat ini tidak didukung saat menggunakan definisi JSON. Namun, aplikasi tersebut dapat diterapkan melalui ekstensi.

Melakukan inisialisasi

Saat dibuat, kolom pada dasarnya hanya berisi nilai. Inisialisasi adalah tempat DOM di-build, model di-build (jika kolom memiliki model), dan peristiwa terikat.

Layar Aktif

Selama inisialisasi, Anda bertanggung jawab untuk membuat apa pun yang Anda perlukan untuk tampilan blok kolom.

Default, latar belakang, dan teks

Fungsi initView default membuat elemen rect berwarna terang dan text. Jika Anda ingin kolom memiliki kedua hal ini, ditambah beberapa tambahan barang, panggil fungsi initView superclass sebelum menambahkan elemen Elemen DOM. Jika Anda ingin {i>field<i} Anda memiliki salah satu, tetapi tidak keduanya, dari Anda dapat menggunakan fungsi createBorderRect_ atau createTextElement_.

Menyesuaikan konstruksi DOM

Jika kolom Anda adalah kolom teks umum (mis. Teks Input), Konstruksi DOM akan ditangani untuk Anda. Jika tidak, Anda harus mengganti fungsi initView untuk membuat elemen DOM yang akan Anda perlukan selama rendering kolom Anda di masa mendatang.

Misalnya, kolom dropdown dapat berisi gambar dan teks. Di initView membuat elemen gambar tunggal dan elemen teks tunggal. Kemudian selama render_ elemen aktif dan menyembunyikan elemen lain, berdasarkan tipe opsi yang dipilih.

Membuat elemen DOM bisa dilakukan menggunakan metode Metode Blockly.utils.dom.createSvgElement, atau menggunakan pembuatan DOM tradisional metode.

Persyaratan tampilan on-block kolom adalah:

• Semua elemen DOM harus merupakan turunan dari fieldGroup_ kolom. Lapangan grup akan dibuat secara otomatis.
• Semua elemen DOM harus tetap berada dalam dimensi kolom yang dilaporkan.

Lihat Rendering untuk detail selengkapnya tentang menyesuaikan dan memperbarui tampilan blok.

Menambahkan Simbol Teks

Jika Anda ingin menambahkan simbol ke teks {i>field<i} (seperti atribut Sudut simbol derajat bidang) Anda dapat menambahkan elemen simbol (biasanya terdapat dalam <tspan>) langsung ke textElement_ kolom.

Peristiwa input

Secara default, kolom mendaftarkan peristiwa tooltip, dan peristiwa mousedown (akan digunakan untuk menampilkan editor). Jika Anda ingin memproses jenis peristiwa lain (mis. jika Anda ingin menangani menarik kolom), Anda harus mengganti fungsi bindEvents_ kolom.

bindEvents_() {
  // Call the superclass function to preserve the default behavior as well.
  super.bindEvents_();

  // Then register your own additional event listeners.
  this.mouseDownWrapper_ =
  Blockly.browserEvents.conditionalBind(this.getClickTarget_(), 'mousedown', this,
      function(event) {
        this.originalMouseX_ = event.clientX;
        this.isMouseDown_ = true;
        this.originalValue_ = this.getValue();
        event.stopPropagation();
      }
  );
  this.mouseMoveWrapper_ =
    Blockly.browserEvents.conditionalBind(document, 'mousemove', this,
      function(event) {
        if (!this.isMouseDown_) {
          return;
        }
        var delta = event.clientX - this.originalMouseX_;
        this.setValue(this.originalValue_ + delta);
      }
  );
  this.mouseUpWrapper_ =
    Blockly.browserEvents.conditionalBind(document, 'mouseup', this,
      function(_event) {
        this.isMouseDown_ = false;
      }
  );
}

Catatan: Saat mengganti bindEvents_, Anda harus selalu memanggil fungsi dasar.

Untuk mengikat ke suatu peristiwa, Anda biasanya harus menggunakan Blockly.utils.browserEvents.conditionalBind . Metode binding peristiwa ini memfilter sentuhan sekunder selama menarik. Jika Anda ingin pengendali berjalan bahkan di tengah proses tarik yang sedang berlangsung Anda dapat menggunakan Blockly.browserEvents.bind .

Membuang

Jika Anda mendaftarkan pemroses peristiwa kustom di dalam bindEvents_ kolom fungsi tersebut harus dibatalkan pendaftarannya dalam fungsi dispose.

Catatan: Saat mengganti dispose, Anda harus selalu memanggil fungsi dasar.

Jika Anda melakukan inisialisasi dengan benar lihat kolom Anda (dengan menambahkan semua elemen DOM ke fieldGroup_), lalu DOM bidang akan dibuang secara otomatis.

Penanganan Nilai

→ Untuk informasi tentang nilai kolom vs teksnya, lihat Anatomi kolom kolom.

Urutan validasi

Mengimplementasikan validator kelas

Kolom hanya boleh menerima nilai tertentu. Misalnya, bidang angka seharusnya hanya menerima angka, isian warna hanya boleh menerima warna dll. Hal ini dipastikan melalui class dan lokal validator. Kelas validator mengikuti aturan yang sama seperti validator lokal kecuali bahwa validator juga dijalankan di konstruktor dan, oleh karena itu, seharusnya tidak merujuk ke blok sumber.

Untuk menerapkan validator class kolom, ganti doClassValidation_ .

doClassValidation_(newValue) {
  if (typeof newValue != 'string') {
    return null;
  }
  return newValue;
};

Catatan: newValue yang diteruskan ke doClassValidation_ dapat berupa jenis apa pun (bergantung pada seberapa bertanggung jawabnya sesama developer), jadi bersiaplah untuk menangani kasus ekstrem.

Menangani nilai yang valid

Jika nilai yang diteruskan ke kolom dengan setValue valid, Anda akan menerima Callback doValueUpdate_. Secara default, fungsi doValueUpdate_:

• Menetapkan properti value_ ke newValue.
• Menetapkan isDirty_ menjadi true.

Jika Anda hanya perlu menyimpan nilai, dan tidak ingin melakukan penanganan khusus, Anda tidak perlu mengganti doValueUpdate_.

Atau, jika Anda ingin melakukan hal-hal seperti:

• Penyimpanan kustom newValue.
• Ubah properti lain berdasarkan newValue.
• Simpan apakah nilai saat ini valid atau tidak.

Anda harus mengganti doValueUpdate_:

doValueUpdate_(newValue) {
  super.doValueUpdate_(newValue);
  this.displayValue_ = newValue;
  this.isValueValid_ = true;
}

Perhatian: Jika kolom Anda perlu mengakses properti blok atau ruang kerja saat menetapkan nilai, Anda harus membuat doValueUpdate_ gagal bersih jika nilai tidak tersedia.

Menangani nilai yang tidak valid

Jika nilai yang diteruskan ke kolom dengan setValue tidak valid, Anda akan menerima Callback doValueInvalid_. Secara default, fungsi doValueInvalid_ melakukan tidak terjadi apa-apa. Artinya, nilai yang tidak valid secara default tidak akan ditampilkan. Ini juga berarti kolom tidak akan dirender ulang, karena isDirty_ tidak akan ditetapkan.

Jika Anda ingin menampilkan nilai yang tidak valid, Anda harus mengganti doValueInvalid_. Dalam sebagian besar situasi, Anda harus menetapkan properti displayValue_ ke bagian nilai tidak valid, tetapkan isDirty_ ke true, dan timpa render_ agar tampilan on-block diupdate berdasarkan displayValue_, bukan value_.

doValueInvalid_(newValue) {
  this.displayValue_ = newValue;
  this.isDirty_ = true;
  this.isValueValid_ = false;
}

Peringatan: Jangan pernah menetapkan properti value_ ke nilai yang tidak valid. Nilai kolom harus selalu valid untuk digunakan dalam pembuatan kode.

Nilai multi-bagian

Jika kolom Anda berisi nilai multibagian (mis. daftar, vektor, objek) mungkin ingin bagian-bagian itu ditangani seperti nilai individual.

doClassValidation_(newValue) {
  if (FieldTurtle.PATTERNS.indexOf(newValue.pattern) == -1) {
    newValue.pattern = null;
  }

  if (FieldTurtle.HATS.indexOf(newValue.hat) == -1) {
    newValue.hat = null;
  }

  if (FieldTurtle.NAMES.indexOf(newValue.turtleName) == -1) {
    newValue.turtleName = null;
  }

  if (!newValue.pattern || !newValue.hat || !newValue.turtleName) {
    this.cachedValidatedValue_ = newValue;
    return null;
  }
  return newValue;
}

Pada contoh di atas, setiap properti newValue divalidasi satu per satu. Selanjutnya di akhir fungsi doClassValidation_, jika ada properti individual tidak valid, nilainya di-cache ke properti cacheValidatedValue_ sebelum menampilkan null (tidak valid). Menyimpan cache objek dengan divalidasi secara individual memungkinkan doValueInvalid_ untuk menanganinya secara terpisah, cukup dengan melakukan Pemeriksaan !this.cacheValidatedValue_.property, bukan memvalidasi ulang satu per satu satu per satu.

Pola untuk memvalidasi nilai multi-bagian ini juga dapat digunakan di kolom lokal validator tetapi saat ini tidak ada cara untuk menerapkan pola ini.

isDirty_

isDirty_ adalah flag yang digunakan dalam setValue serta bagian lain dari ruang isian, untuk mengetahui apakah {i>field<i} tersebut perlu dirender ulang. Jika nilai tampilan kolom telah berubah, isDirty_ biasanya akan ditetapkan ke true.

Teks

→ Untuk mengetahui informasi tentang tempat teks kolom digunakan dan perbedaannya dari nilai kolom, lihat Anatomi kolom kolom.

Jika teks {i>field<i} Anda berbeda dengan nilai {i>field<i}, Anda harus ganti Fungsi getText untuk memberikan teks yang benar.

getText() {
  let text = this.value_.turtleName + ' wearing a ' + this.value_.hat;
  if (this.value_.hat == 'Stovepipe' || this.value_.hat == 'Propeller') {
    text += ' hat';
  }
  return text;
}

Membuat editor

Jika Anda menentukan fungsi showEditor_, Blockly akan otomatis memproses mengklik dan memanggil showEditor_ di waktu yang tepat. Anda dapat menampilkan HTML apa pun di editor Anda dengan menggabungkannya ke salah satu dari dua div khusus, yang disebut DropDownDiv dan WidgetDiv, yang mengambang di atas UI Blockly lainnya.

Penting: Pembaruan pada tampilan editor harus ditangani selama rendering, alih-alih segera ditangani. Hal ini memungkinkan validator mencegat sebelum diterapkan.

DropDownDiv vs WidgetDiv

DropDownDiv digunakan untuk menyediakan editor yang aktif di dalam kotak yang terhubung ke suatu kolom. Perangkat tersebut secara otomatis memposisikan dirinya dekat dengan lapangan tanpa bergerak dalam batas-batas yang terlihat. Pemilih sudut dan {i>color picker<i} adalah contoh yang baik dari DropDownDiv.

WidgetDiv digunakan untuk menyediakan editor yang tidak ada dalam kotak. Kolom angka menggunakan kolom WidgetDiv untuk menutupi kolom dengan kotak input teks HTML. Sementara DropDownDiv menangani pemosisian untuk Anda, sedangkan WidgetDiv tidak. Elemen-elemen harus diposisikan secara manual. Sistem koordinat dalam koordinat piksel yang sesuai dengan kiri atas jendela. Editor {i>input <i}teks adalah contoh yang baik dari WidgetDiv.

Kode contoh DropDownDiv

showEditor_() {
  // Create the widget HTML
  this.editor_ = this.dropdownCreate_();
  Blockly.DropDownDiv.getContentDiv().appendChild(this.editor_);

  // Set the dropdown's background colour.
  // This can be used to make it match the colour of the field.
  Blockly.DropDownDiv.setColour('white', 'silver');

  // Show it next to the field. Always pass a dispose function.
  Blockly.DropDownDiv.showPositionedByField(
      this, this.disposeWidget_.bind(this));
}

Catatan: Membuat HTML secara terprogram membutuhkan waktu yang cukup lama sehingga yang disediakan di sini. Untuk contohnya, lihat Bidang Khusus Demo .

Kode contoh WidgetDiv

showEditor_() {
  // Show the div. This automatically closes the dropdown if it is open.
  // Always pass a dispose function.
  Blockly.WidgetDiv.show(
    this, this.sourceBlock_.RTL, this.widgetDispose_.bind(this));

  // Create the widget HTML.
  var widget = this.createWidget_();
  Blockly.WidgetDiv.getDiv().appendChild(widget);
}

Catatan: Membuat HTML widget secara terprogram membutuhkan waktu yang cukup lama sehingga tidak disediakan di sini. Untuk contohnya, lihat implementasi Input Teks Kolom .

Catatan: Jika Anda membuat widget yang dimaksudkan untuk berfungsi seperti input, tetapi menggunakan elemen khusus, Anda dapat menambahkan data-is-text-input='true' ke elemen untuk memberi tahu Secara blok untuk memperlakukan elemen sebagai input.

Pembersihan

DropDownDiv dan WidgetDiv menangani menghancurkan HTML widget tetapi Anda perlu membuang secara manual pemroses kejadian apa pun yang Anda miliki diterapkan pada elemen-elemen tersebut.

widgetDispose_() {
  for (let i = this.editorListeners_.length, listener;
      listener = this.editorListeners_[i]; i--) {
    Blockly.browserEvents.unbind(listener);
    this.editorListeners_.pop();
  }
}

Fungsi dispose dipanggil dalam konteks null di DropDownDiv. Aktif WidgetDiv yang dipanggil dalam konteks WidgetDiv. Dalam kedua kasus sebaiknya gunakan pengikatan saat meneruskan fungsi dispose, seperti yang ditunjukkan dalam DropDownDiv di atas dan WidgetDiv.

→ Untuk informasi tentang penghapusan yang tidak spesifik terkait penghapusan editor, lihat Membuang.

Memperbarui tampilan aktif blok

Fungsi render_ digunakan untuk mengupdate tampilan on-block kolom agar cocok nilai internalnya.

Contoh umumnya meliputi:

• Mengubah teks (dropdown)
• Mengubah warna (warna)

Penting: Kolom tidak boleh memanggil render_ secara langsung. Sebagai gantinya, merender ulang harus dipicu dengan menyetel atribut isDirty_ properti ke true.

Default

Fungsi render_ default menetapkan teks tampilan ke hasil getDisplayText_ . Fungsi getDisplayText_ menampilkan properti value_ kolom transmisi ke string, setelah dipotong untuk mematuhi ukuran teks maksimum paruh.

Jika Anda menggunakan tampilan on-block default, dan perilaku teks default berfungsi untuk kolom Anda, Anda tidak perlu mengganti render_.

Jika perilaku teks default berfungsi untuk kolom Anda, tetapi aturan pemblokiran kolom memiliki elemen statis tambahan, Anda dapat memanggil render_ default , namun Anda masih harus menggantinya untuk memperbarui ukuran.

Jika perilaku teks default tidak berfungsi untuk kolom Anda, atau perilaku tampilan blok memiliki elemen dinamis tambahan, Anda harus menyesuaikan render_ fungsi.

Menyesuaikan rendering

Jika perilaku rendering default tidak sesuai untuk kolom Anda, Anda harus menentukan perilaku rendering kustom. Proses ini dapat melibatkan apa pun, mulai dari mengatur menampilkan teks, mengubah elemen gambar, hingga memperbarui warna latar belakang.

Semua perubahan atribut DOM sah, dua hal yang perlu diingat adalah:

1. Pembuatan DOM harus ditangani selama inisialisasi, karena lebih efisien.
2. Anda harus selalu mengupdate size_ agar sesuai dengan ukuran layar di blok.

render_() {
  switch(this.value_.hat) {
    case 'Stovepipe':
      this.stovepipe_.style.display = '';
      break;
    case 'Crown':
      this.crown_.style.display = '';
      break;
    case 'Mask':
      this.mask_.style.display = '';
      break;
    case 'Propeller':
      this.propeller_.style.display = '';
      break;
    case 'Fedora':
      this.fedora_.style.display = '';
      break;
  }

  switch(this.value_.pattern) {
    case 'Dots':
      this.shellPattern_.setAttribute('fill', 'url(#polkadots)');
      break;
    case 'Stripes':
      this.shellPattern_.setAttribute('fill', 'url(#stripes)');
      break;
    case 'Hexagons':
      this.shellPattern_.setAttribute('fill', 'url(#hexagons)');
      break;
  }

  this.textContent_.nodeValue = this.value_.turtleName;

  this.updateSize_();
}

Penting: Selalu gunakan this.textContent_.nodeValue untuk memperbarui teks tampilan bidang Anda. Hal ini membantu mendukung teks simbol.

Memperbarui ukuran

Memperbarui properti size_ suatu kolom sangat penting karena dapat menginformasikan memblokir kode rendering cara memposisikan bidang. Cara terbaik untuk mengetahui inilah yang seharusnya menjadi size_ dengan bereksperimen.

updateSize_() {
  const bbox = this.movableGroup_.getBBox();
  let width = bbox.width;
  let height = bbox.height;
  if (this.borderRect_) {
    width += this.constants_.FIELD_BORDER_RECT_X_PADDING * 2;
    height += this.constants_.FIELD_BORDER_RECT_X_PADDING * 2;
    this.borderRect_.setAttribute('width', width);
    this.borderRect_.setAttribute('height', height);
  }
  // Note how both the width and the height can be dynamic.
  this.size_.width = width;
  this.size_.height = height;
}

Perhatian: Memanggil getBBox selama rendering dapat menyebabkan thrashing tata letak, sehingga Anda mungkin ingin menyelidiki cara lain untuk mendapatkan ukuran.

Catatan: Lebar dan tinggi kolom bisa bersifat dinamis, sedangkan memperbarui ukurannya akan tidak harus terkandung dalam fungsinya sendiri; data tersebut dapat ditangani di dalam render_. Namun, kode ini biasanya dipisahkan agar kode lebih teratur.

Mencocokkan warna balok

Jika Anda ingin elemen {i>field<i} Anda sesuai dengan warna blok mereka yang dilampirkan, Anda harus mengganti metode applyColour. Anda mungkin ingin mengakses warna melalui properti gaya blok.

applyColour() {
  const sourceBlock = this.sourceBlock_;
  if (sourceBlock.isShadow()) {
    this.arrow_.style.fill = sourceBlock.style.colourSecondary;
  } else {
    this.arrow_.style.fill = sourceBlock.style.colourPrimary;
  }
}

Catatan: Anda mungkin ingin meng-cache warna dalam metode applyColour agar dapat menerapkannya ke editor saat diaktifkan.

Memperbarui kemampuan pengeditan

Fungsi updateEditable dapat digunakan untuk mengubah tampilan kolom Anda tergantung pada apakah data dapat diedit atau tidak. Fungsi {i>default<i} membuatnya latar belakang tidak memiliki respons pengarahan kursor (batas) jika tidak dapat diedit. Tampilan di blok tidak boleh berubah ukuran tergantung pada kemampuan editnya, tetapi semua perubahan lain diizinkan.

updateEditable() {
  if (!this.fieldGroup_) {
    // Not initialized yet.
    return;
  }
  super.updateEditable();

  const group = this.getClickTarget_();
  if (!this.isCurrentlyEditable()) {
    group.style.cursor = 'not-allowed';
  } else {
    group.style.cursor = this.CURSOR;
  }
}

Perhatian: Mengotak-atik kursor kolom bersifat rapuh.

Serialisasi

Serialisasi berarti menyimpan status kolom Anda agar nanti dapat dimuat ulang.

Status ruang kerja Anda selalu mencakup nilai kolom, tetapi juga bisa menyertakan status lain, seperti status UI kolom Anda. Misalnya, jika adalah peta yang dapat di-zoom yang memungkinkan pengguna memilih negara, Anda bisa juga melakukan serialisasi tingkat zoom.

Jika kolom dapat diserialisasi, Anda harus menetapkan properti SERIALIZABLE ke true.

Blockly menyediakan dua set hook serialisasi untuk kolom. Sepasang hook berfungsi dengan sistem serialisasi JSON yang baru, sedangkan pasangan lainnya berfungsi dengan sistem serialisasi XML lama.

saveState dan loadState

saveState dan loadState adalah hook serialisasi yang berfungsi dengan JSON baru sistem serialisasi.

Dalam beberapa kasus, Anda tidak perlu menyediakannya, karena setelan implementasi yang tepat. Jika (1) kolom Anda merupakan subclass langsung dari dasar Class Blockly.Field, (2) nilai Anda adalah JSON yang dapat diserialisasi jenis, dan (3) Anda hanya perlu serialisasi nilai, maka implementasi default akan berfungsi dengan baik.

Jika tidak, fungsi saveState akan menampilkan JSON yang dapat diserialisasi objek/nilai yang mewakili status kolom. Dan loadState Anda harus menerima objek/nilai yang dapat diserialisasi JSON yang sama, dan menerapkannya ke bidang Anda.

saveState() {
  return {
    'country': this.getValue(),  // Value state
    'zoom': this.getZoomLevel(), // UI state
  };
}

loadState(state) {
  this.setValue(state['country']);
  this.setZoomLevel(state['zoom']);
}

Serialisasi lengkap dan data cadangan

saveState juga menerima parameter opsional doFullSerialization. Ini adalah digunakan oleh bidang yang biasanya mereferensikan status yang diserialisasi oleh serializer (seperti model data pendukung). Parameter tersebut menandakan bahwa status yang direferensikan tidak akan tersedia ketika blok dideserialisasi, sehingga harus melakukan semua serialisasi itu sendiri. Misalnya, hal ini berlaku ketika blok individu yang diserialisasi, atau ketika blok itu disalin-tempel.

Dua kasus penggunaan umum untuk hal ini adalah:

• Saat blok individual dimuat ke ruang kerja tempat data pendukung model tidak ada, bidang itu memiliki cukup informasi dalam statusnya sendiri untuk membuat model data baru.
• Jika suatu blok disalin dan ditempel, bidangnya akan selalu membuat dukungan baru alih-alih mereferensikan model yang sudah ada.

Satu kolom yang menggunakan ini adalah kolom variabel built-in. Biasanya, DHCP akan diserialisasi ID variabel yang dirujuknya, tetapi jika doFullSerialization benar ia menserialisasi semua statusnya.

saveState(doFullSerialization) {
  const state = {'id': this.variable_.getId()};
  if (doFullSerialization) {
    state['name'] = this.variable_.name;
    state['type'] = this.variable_.type;
  }
  return state;
}

loadState(state) {
  const variable = Blockly.Variables.getOrCreateVariablePackage(
      this.getSourceBlock().workspace,
      state['id'],
      state['name'],   // May not exist.
      state['type']);  // May not exist.
  this.setValue(variable.getId());
}

Kolom variabel melakukan ini untuk memastikan bahwa jika dimuat ke ruang kerja jika variabelnya tidak ada, ia dapat membuat variabel baru sebagai referensi.

toXml dan fromXml

toXml dan fromXml adalah hook serialisasi yang berfungsi dengan XML lama sistem serialisasi. Hanya gunakan hook ini jika perlu (misalnya, Anda sedang bekerja pada codebase lama yang belum dimigrasikan), jika tidak, gunakan saveState dan loadState.

Fungsi toXml Anda akan menampilkan node XML yang mewakili status bidang Anda. Dan fungsi fromXml Anda harus menerima node XML yang sama dan menerapkan ke lapangan.

toXml(fieldElement) {
  fieldElement.textContent = this.getValue();
  fieldElement.setAttribute('zoom', this.getZoomLevel());
  return fieldElement;
}

fromXml(fieldElement) {
  this.setValue(fieldElement.textContent);
  this.setZoomLevel(fieldElement.getAttribute('zoom'));
}

Properti yang dapat diedit dan diserialisasi

Properti EDITABLE menentukan apakah kolom harus memiliki UI untuk menunjukkan yang dapat berinteraksi dengannya. Defaultnya adalah true.

Properti SERIALIZABLE menentukan apakah kolom harus diserialisasi. Ini nilai defaultnya adalah false. Jika properti ini adalah true, Anda mungkin harus memberikan fungsi serialisasi dan deserialisasi (lihat Serialisasi).

Penting: Jika EDITABLE adalah true untuk kolom Anda, SERIALIZABLE juga harus ditetapkan ke true. Secara default, hal ini tidak berlaku untuk kompatibilitas mundur alasan.

Menyesuaikan kursor

Properti CURSOR menentukan kursor yang dilihat pengguna saat mereka mengarahkan kursor ke bidang Anda. Harus berupa string kursor CSS yang valid. Setelan default ini adalah kursor ditentukan oleh .blocklyDraggable, yang merupakan kursor ambil.