Membuat jenis kolom baru

Sebelum membuat jenis kolom baru, pertimbangkan apakah salah satu metode lain untuk menyesuaikan kolom sesuai dengan kebutuhan Anda. Jika aplikasi Anda perlu menyimpan jenis nilai baru, atau Anda ingin membuat UI baru untuk jenis nilai yang sudah ada, Anda mungkin harus membuat jenis kolom baru.

Untuk membuat kolom baru, lakukan hal berikut:

1. Implementasikan konstruktor.
2. Daftarkan kunci JSON dan terapkan fromJson.
3. Menangani inisialisasi UI on-block dan pemroses peristiwa.
4. Menangani penghapusan pemroses peristiwa (pembuangan UI ditangani untuk Anda).
5. Implementasikan penanganan nilai.
6. Tambahkan representasi teks dari nilai kolom Anda, untuk aksesibilitas.
7. Menambahkan fungsi tambahan seperti:
   • Editor.
   • Pembaruan tampilan blok.
   • Serialisasi.
8. Konfigurasikan aspek tambahan kolom Anda, seperti:
   • Properti yang dapat diedit dan diserialisasi
   • Kursor

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

Untuk contoh kolom kustom, lihat demo Kolom Kustom.

Mengimplementasikan konstruktor

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

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. Nilai ini bersifat opsional, dan jika Anda tidak meneruskan nilai (atau Anda meneruskan nilai yang gagal dalam validasi class), nilai default superclass akan digunakan. Untuk class Field default, nilainya adalah null. Jika Anda tidak menginginkan nilai default tersebut, pastikan untuk meneruskan nilai yang sesuai. Parameter validator hanya ada untuk kolom yang dapat diedit dan biasanya ditandai sebagai opsional. Pelajari validator di dokumen Validator lebih lanjut.

Struktur

Logika di dalam konstruktor Anda harus mengikuti alur ini:

1. Panggil konstruktor super yang diwarisi (semua kolom kustom harus diwarisi dari Blockly.Field atau salah satu subclass-nya) untuk menginisialisasi nilai dengan benar dan menetapkan validator lokal untuk kolom Anda.
2. Jika kolom Anda dapat diserialisasi, tetapkan properti yang sesuai di konstruktor. Kolom yang dapat diedit harus dapat diserialisasi, dan kolom dapat diedit secara default. Jadi, sebaiknya tetapkan properti ini ke benar (true) kecuali Anda tahu bahwa properti tersebut tidak boleh diserialisasi.
3. Opsional: Terapkan penyesuaian tambahan (misalnya, Kolom label memungkinkan class CSS diteruskan, yang kemudian diterapkan ke teks).

JSON dan pendaftaran

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

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

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

Anda juga perlu menentukan fungsi fromJson. Implementasi Anda harus terlebih dahulu membatalkan referensi tabel string menggunakan replaceMessageReferences, lalu meneruskan nilai 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 jika menggunakan definisi JSON. Namun, parameter tersebut dapat diterapkan melalui ekstensi.

Melakukan inisialisasi

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

Layar On-Block

Selama inisialisasi, Anda bertanggung jawab untuk membuat apa pun yang diperlukan untuk tampilan on-block kolom tersebut.

Default, latar belakang, dan teks

Fungsi initView default membuat elemen rect berwarna terang dan elemen text. Jika ingin kolom Anda memiliki keduanya, ditambah beberapa item tambahan, panggil fungsi initView superclass sebelum menambahkan elemen DOM lainnya. Jika ingin kolom memiliki salah satu, tetapi tidak keduanya, Anda dapat menggunakan fungsi createBorderRect_ atau createTextElement_.

Menyesuaikan konstruksi DOM

Jika kolom Anda adalah kolom teks umum (misalnya Text Input), konstruksi DOM akan ditangani untuk Anda. Jika tidak, Anda harus mengganti fungsi initView untuk membuat elemen DOM yang akan diperlukan selama rendering kolom berikutnya.

Misalnya, kolom dropdown dapat berisi gambar dan teks. Di initView, kode membuat satu elemen gambar dan satu elemen teks. Kemudian, selama render_, metode ini menampilkan elemen aktif dan menyembunyikan elemen lainnya, berdasarkan jenis opsi yang dipilih.

Pembuatan elemen DOM dapat dilakukan menggunakan metode Blockly.utils.dom.createSvgElement, atau menggunakan metode pembuatan DOM tradisional.

Persyaratan untuk menampilkan blok pada kolom adalah:

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

Lihat bagian Rendering untuk detail selengkapnya tentang menyesuaikan dan mengupdate tampilan blok Anda.

Menambahkan Simbol Teks

Jika ingin menambahkan simbol ke teks kolom (seperti simbol derajat kolom Angle), Anda dapat menambahkan elemen simbol (biasanya dimuat dalam <tspan>) langsung ke textElement_ kolom.

Peristiwa input

Secara default, kolom mendaftarkan peristiwa tooltip dan peristiwa mousedown (akan digunakan untuk menampilkan editor). Jika ingin memproses jenis peristiwa lain (misalnya, jika Anda ingin menangani penarikan pada 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 peristiwa, Anda biasanya harus menggunakan fungsi Blockly.utils.browserEvents.conditionalBind. Metode peristiwa binding ini memfilter sentuhan sekunder selama penarikan. Jika Anda ingin pengendali berjalan bahkan di tengah proses tarik yang sedang berlangsung, Anda dapat menggunakan fungsi Blockly.browserEvents.bind.

Pembuangan

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

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

Jika Anda menginisialisasi tampilan kolom dengan benar (dengan menambahkan semua elemen DOM ke fieldGroup_), DOM kolom tersebut akan dihapus secara otomatis.

Penanganan Nilai

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

Urutan validasi

Mengimplementasikan validator class

Kolom hanya boleh menerima nilai tertentu. Misalnya, kolom angka hanya boleh menerima angka, kolom warna hanya boleh menerima warna, dll. Hal ini dipastikan melalui class dan validator lokal. Validator class mengikuti aturan yang sama dengan validator lokal, kecuali bahwa validator juga berjalan di konstruktor dan, dengan demikian, tidak boleh mereferensikan blok sumber.

Untuk menerapkan validator class kolom, ganti fungsi doClassValidation_.

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

Catatan: newValue yang diteruskan ke doClassValidation_ dapat berupa jenis apa pun (tergantung seberapa bertanggung jawab 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 properti isDirty_ ke true.

Jika hanya perlu menyimpan nilai, dan tidak ingin melakukan penanganan kustom, 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 dengan rapi jika 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_ tidak melakukan apa pun. Artinya, nilai yang tidak valid secara default tidak akan ditampilkan. Hal ini juga berarti kolom tidak akan dirender ulang, karena properti isDirty_ tidak akan ditetapkan.

Jika ingin menampilkan nilai yang tidak valid, Anda harus mengganti doValueInvalid_. Dalam sebagian besar situasi, Anda harus menetapkan properti displayValue_ ke nilai tidak valid, menetapkan isDirty_ ke true, dan mengganti render_ agar tampilan pada blok diperbarui 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 berisi nilai multibagian (misalnya, daftar, vektor, objek), Anda mungkin ingin bagian-bagian tersebut 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. Kemudian, di akhir fungsi doClassValidation_, jika ada properti individual yang tidak valid, nilai tersebut akan di-cache ke properti cacheValidatedValue_ sebelum menampilkan null (tidak valid). Menyimpan objek ke dalam cache dengan properti yang divalidasi secara terpisah memungkinkan fungsi doValueInvalid_ menanganinya secara terpisah, hanya dengan melakukan pemeriksaan !this.cacheValidatedValue_.property, bukan memvalidasi ulang setiap properti satu per satu.

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

isDirty_

isDirty_ adalah flag yang digunakan dalam fungsi setValue, serta bagian kolom lainnya, untuk memberi tahu apakah kolom perlu dirender ulang. Jika nilai tampilan kolom telah berubah, isDirty_ biasanya harus ditetapkan ke true.

Teks

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

Jika teks kolom berbeda dengan nilai kolom, Anda harus mengganti 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 klik dan memanggil showEditor_ pada waktu yang tepat. Anda dapat menampilkan HTML apa pun di editor dengan menggabungkannya ke salah satu dari dua div khusus, yang disebut DropDownDiv dan WidgetDiv, yang mengambang di atas UI Blockly lainnya.

Penting: Update pada tampilan editor harus ditangani selama rendering, bukan segera ditangani. Hal ini memungkinkan validator menangkap nilai sebelum diterapkan.

DropDownDiv vs WidgetDiv

DropDownDiv digunakan untuk menyediakan editor yang berada di dalam kotak yang terhubung ke sebuah kolom. Fungsi ini otomatis memosisikan dirinya agar berada di dekat kolom sekaligus tetap dalam batas yang terlihat. Pemilih sudut dan pemilih warna adalah contoh yang baik dari DropDownDiv.

WidgetDiv digunakan untuk menyediakan editor yang tidak ada di dalam kotak. Kolom angka menggunakan WidgetDiv untuk mengisi kolom dengan kotak input teks HTML. Meskipun DropDownDiv menangani pemosisian untuk Anda, WidgetDiv tidak. Elemen harus diposisikan secara manual. Sistem koordinat dalam koordinat piksel yang relatif terhadap bagian kiri atas jendela. Editor input 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 dapat berlangsung lama sehingga tidak disediakan di sini. Untuk contohnya, lihat Demo Kolom Kustom.

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 dapat berlangsung lama sehingga tidak disediakan di sini. Untuk contohnya, lihat penerapan Kolom Input Teks.

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

Pembersihan

DropDownDiv dan WidgetDiv menangani penghapusan elemen HTML widget, tetapi Anda harus membuang pemroses peristiwa secara manual yang telah diterapkan pada 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. Di WidgetDiv, kode ini dipanggil dalam konteks WidgetDiv. Dalam kedua kasus tersebut, sebaiknya gunakan fungsi bind saat meneruskan fungsi pembuangan, seperti yang ditunjukkan pada contoh DropDownDiv dan WidgetDiv di atas.

→ Untuk informasi tentang cara membuang yang tidak khusus untuk membuang editor, lihat Membuang.

Memperbarui tampilan blok

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

Contoh umumnya meliputi:

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

Penting: Kolom tidak boleh memanggil render_ secara langsung. Sebaliknya, rendering ulang harus dipicu dengan menetapkan properti isDirty_ ke true.

Default

Fungsi render_ default menetapkan teks tampilan ke hasil fungsi getDisplayText_. Fungsi getDisplayText_ menampilkan transmisi properti value_ kolom ke string, setelah dipotong agar mengikuti panjang teks maksimum.

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 tampilan on-block kolom Anda memiliki elemen statis tambahan, Anda dapat memanggil fungsi render_ default, tetapi Anda masih perlu menggantinya untuk memperbarui ukuran kolom.

Jika perilaku teks default tidak sesuai untuk kolom Anda, atau tampilan on-block kolom Anda memiliki elemen dinamis tambahan, Anda harus menyesuaikan fungsi render_.

Menyesuaikan rendering

Jika perilaku rendering default tidak sesuai untuk kolom Anda, Anda harus menentukan perilaku rendering kustom. Hal ini dapat melibatkan apa saja, mulai dari menyetel teks tampilan kustom, mengubah elemen gambar, hingga memperbarui warna latar belakang.

Semua perubahan atribut DOM bersifat legal, hanya dua hal yang perlu diingat adalah:

1. Pembuatan DOM harus ditangani selama inisialisasi, karena lebih efisien.
2. Anda harus selalu memperbarui properti size_ agar sesuai dengan ukuran tampilan pada 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 kolom Anda. Hal ini membantu mendukung simbol teks.

Memperbarui ukuran

Memperbarui properti size_ sebuah kolom sangat penting karena dapat menginformasikan kode rendering blok cara memosisikan kolom. Cara terbaik untuk mengetahui persis apa size_ tersebut adalah 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 layout thrashing, jadi sebaiknya periksa cara lain untuk mendapatkan ukuran.

Catatan: Lebar dan tinggi kolom dapat bersifat dinamis dan memperbarui ukuran tidak harus ada dalam fungsinya sendiri. Anda dapat menanganinya di dalam render_. Namun, langkah ini biasanya dipisahkan agar kode lebih teratur.

Warna blok yang cocok

Jika ingin elemen kolom cocok dengan warna blok yang terlampir, Anda harus mengganti metode applyColour. Anda perlu 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 perlu menyimpan warna ke dalam cache di metode applyColour, sehingga Anda dapat menerapkannya ke editor saat sudah diaktifkan.

Memperbarui kemampuan pengeditan

Fungsi updateEditable dapat digunakan untuk mengubah tampilan kolom Anda, bergantung pada apakah kolom tersebut dapat diedit atau tidak. Fungsi default membuatnya sehingga latar belakang memiliki/tidak memiliki respons pengarahan kursor (border) jika dapat/tidak dapat diedit. Layar pada blok tidak boleh berubah ukuran, bergantung pada kemampuan pengeditannya, 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 adalah cara menyimpan status kolom agar dapat dimuat ulang ke ruang kerja nanti.

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

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

Blockly menyediakan dua set hook serialisasi untuk kolom. Satu pasang hook berfungsi dengan sistem serialisasi JSON baru, dan pasangan hook lainnya berfungsi dengan sistem serialisasi XML lama.

saveState dan loadState

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

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

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

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

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

Serialisasi dan pencadangan data lengkap

saveState juga menerima parameter opsional doFullSerialization. Ini digunakan oleh kolom yang biasanya merujuk status yang diserialisasi oleh serializer berbeda (seperti model data pendukung). Parameter ini memberi sinyal bahwa status yang dirujuk tidak akan tersedia saat blok dideserialisasi, sehingga kolom harus melakukan semua serialisasi itu sendiri. Misalnya, hal ini berlaku jika satu blok diserialisasi, atau saat blok disalin-ditempel.

Dua kasus penggunaan umum untuk hal ini adalah:

• Saat satu blok dimuat ke ruang kerja yang tidak memiliki model data pendukung, kolom tersebut memiliki cukup informasi dalam statusnya sendiri untuk membuat model data baru.
• Jika blok disalin-tempel, kolom ini akan selalu membuat model data pendukung baru, bukan mereferensikan model yang sudah ada.

Salah satu kolom yang menggunakan ini adalah kolom variabel built-in. Biasanya kode ini akan melakukan serialisasi ID variabel yang direferensikannya, tetapi jika doFullSerialization bernilai benar, semua status akan diserialisasi.

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 melakukannya untuk memastikan bahwa jika dimuat ke ruang kerja yang tidak memiliki variabelnya, kolom tersebut dapat membuat variabel baru untuk referensi.

toXml dan fromXml

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

Fungsi toXml akan menampilkan node XML yang mewakili status kolom. Dan fungsi fromXml Anda harus menerima node XML yang sama dan menerapkannya ke kolom.

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 bahwa kolom dapat berinteraksi. Nilai defaultnya adalah true.

Properti SERIALIZABLE menentukan apakah kolom harus diserialisasi. Nilai defaultnya adalah false. Jika properti ini adalah true, Anda mungkin perlu 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 alasan kompatibilitas mundur.

Menyesuaikan kursor

Properti CURSOR menentukan kursor yang dilihat pengguna saat mereka mengarahkan kursor ke kolom Anda. Nilainya harus berupa string kursor CSS yang valid. Default-nya adalah kursor yang ditentukan oleh .blocklyDraggable, yang merupakan pengambil kursor.