Meningkatkan bidang khusus

Pada Juli 2019 (rilis 2.20190722), API kolom yang lebih terkodifikasi telah ditambahkan. Fitur ini dirancang agar kompatibel dengan versi sebelumnya. Artinya, jika Anda telah membuat kolom kustom sebelum Juli 2019, kolom tersebut kemungkinan besar akan terus berfungsi. Sebelum memutuskan apakah kolom kustom Anda perlu diupgrade, Anda harus membaca bagian Area berbahaya, dan melakukan pengujian menyeluruh untuk kolom Anda.

Karena kurangnya standardisasi antarkolom sebelum Juli 2019, sulit untuk mencakup semua perubahan yang mungkin perlu dilakukan developer. Dokumen ini mencoba mencakup semua perubahan yang mungkin terjadi, tetapi jika dokumen ini tidak mencakup sesuatu yang Anda minati, baca bagian tentang mendapatkan bantuan upgrade.

Catatan: Jika Anda memiliki sedikit kolom kustom, akan lebih mudah jika Anda hanya menulis ulang kolom tersebut menggunakan petunjuk pembuatan kolom kustom, daripada mencoba mengupgradenya secara bertahap.

Area bahaya

Area berbahaya adalah tempat umum di mana API telah berubah, dan kolom Anda bisa rusak.

Blockly.Field.register

Kolom tidak lagi terdaftar melalui Blockly.Field.register();. Kini ada namespace fieldRegistry yang menangani pendaftaran.

Blockly.Field.register('my_field_name', myFieldClass);

Menjadi:

Blockly.fieldRegistry.register('my_field_name', myFieldClass);

setText

Fungsi setText tidak lagi dipanggil oleh inti Blockly, jadi jika fungsi setText berisi logika, fungsi tersebut harus dipindahkan ke rangkaian fungsi penanganan nilai, fungsi getText, dan fungsi rendering (bergantung pada fungsi setText yang sebenarnya).

CustomFields.UpgradeField.prototype.setText = function(newText) {
  // Do validation.
  if (typeof newText != 'string' || newText === this.text_) {
    return;
  }

  // Fire event.
  if (this.sourceBlock_ && Blockly.Events.isEnabled()) {
    Blockly.events.fire(new Blockly.Events.BlockChange(
        this.sourceBlock_, 'field', this.name, this.text_, newText
    ));
  }

  // Update text value.
  this.text_ = 'prefix' + newText;

  // Rerender.
  this.size_.width = 0;
};

Menjadi:

CustomFields.UpgradeField.prototype.doClassValidation_ = function(newValue) {
  if (typeof newValue != 'string') {
    return null;
  }
  return newValue;
};

CustomFields.UpgradeField.prototype.getText = function() {
  return  'prefix' + this.value_;
}

Blockly otomatis menangani:

• Memeriksa apakah nilai baru berbeda dari nilai lama.
• Memperbarui nilai.
• Mengaktifkan peristiwa perubahan.
• Render ulang kolom.

Anda harus menangani:

• Validasi nilai (doClassValidation_).
• Teks kolom (getText).
• UI Kolom

Catatan: Sebaiknya ubah panggilan setText ke panggilan setValue, karena setValue mendukung validasi sedangkan setText tidak.

Upgrade yang direkomendasikan

Upgrade yang direkomendasikan adalah tempat yang API kolomnya telah diubah, tetapi jika Anda memilih untuk tidak membuat perubahan, kolom tersebut kemungkinan besar akan tetap berfungsi.

DAPAT DITERTENTUKAN

Untuk informasi selengkapnya tentang properti EDITABLE dan SERIALIZABLE, lihat Properti yang dapat diedit dan diserialisasi.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

Peringatan di bawah ini dapat diabaikan, tetapi Anda dapat mengatasinya dengan menentukan properti SERIALIZABLE:

Detected an editable field that was not serializable. Please define
SERIALIZABLE property as true on all editable custom fields. Proceeding
with serialization.

Peringatan di atas berarti Blockly yakin bahwa Anda ingin kolom diserialisasi (karena properti EDITABLE bernilai benar), tetapi tidak dapat dipastikan sampai Anda menentukan properti SERIALIZABLE. Jika Anda memilih untuk membiarkannya, semuanya akan berfungsi dengan benar, dan kolom Anda akan diserialisasi, tetapi Anda akan menerima peringatan konsol.

size_.width

this.size_.width = 0;

Menjadi:

this.isDirty_ = true;

Peringatan di bawah dapat diabaikan, tetapi Anda dapat mengatasinya dengan menetapkan properti isDirty_, bukan properti size_.width:

Deprecated use of setting size_.width to 0 to rerender a field. Set
field.isDirty_ to true instead.

Peringatan di atas berarti Blockly telah mendeteksi bahwa Anda menggunakan metode lama untuk merender ulang kolom, dan ingin Anda menggunakan metode baru.

Untuk informasi selengkapnya tentang properti isDirty_, lihat isDirty_.

init

Fungsi init telah diubah menjadi fungsi template untuk mengurangi kode duplikat dalam subclass.

CustomFields.UpgradeField.prototype.init = function() {
  if (this.fieldGroup_) {
    // Already initialized once.
    return;
  }

  // Call superclass.
  CustomFields.UpgradeField.superClass_.init.call(this);

  // Create DOM elements.
  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);

  // Bind events.
  this.mouseOverWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);

  // Render.
  this.setValue(this.getValue());
};

Menjadi:

CustomFields.UpgradeField.prototype.initView = function() {
  CustomFields.UpgradeField.superClass_.initView.call(this);

  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);
};

CustomFields.UpgradeField.prototype.bindEvents_ = function() {
  CustomFields.UpgradeField.superClass_.bindEvents_.call(this);

  this.mouseOverWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);
};

Ini berarti blockly sekarang otomatis menangani:

• Memeriksa apakah kolom sudah diinisialisasi.
• Membuat fieldGroup_.
• Merender kolom.
• Tooltip binding dan tampilkan peristiwa editor.

Anda harus menangani:

• Menambahkan elemen DOM tambahan (initView).
• Menambahkan binding peristiwa tambahan (bindEvents_).
• Menghapus binding peristiwa (dispose).

Penting: Semua pembuatan DOM harus dilakukan di dalam initView karena cara tersebut paling efisien. Pertimbangkan untuk memfaktorkan ulang jika Anda memiliki pembuatan DOM yang terjadi di dalam konstruktor, setText, setValue, atau render_.

onMouseDown_

CustomFields.UpgradeField.prototype.onMouseDown_ = function(e) {
  // ...
};

Menjadi:

CustomFields.UpgradeField.prototype.showEditor_ = function() {
  // ...
}

Sebaiknya ganti fungsi showEditor_ untuk menangani klik mouse, bukan fungsi onMouseDown_, karena fungsi tersebut memungkinkan input diteruskan melalui sistem gestur.

Untuk mengetahui informasi selengkapnya tentang editor, buka Editor.

setValue

Fungsi setValue kini menjadi fungsi template untuk mengurangi kode duplikat dalam subclass. Jika fungsi setValue Anda berisi logika, pertimbangkan untuk memfaktorkan ulang fungsi tersebut agar sesuai dengan jalur penanganan nilai yang dijelaskan dalam Penanganan nilai.

text_

Sebaiknya jangan pernah mengakses atau memperbarui properti text_ kolom Anda secara langsung. Sebagai gantinya, gunakan fungsi getText untuk mengakses teks kolom yang dapat dibaca pengguna dan fungsi setValue untuk memperbarui nilai kolom yang tersimpan.

Untuk mengetahui informasi selengkapnya tentang nilai kolom vs teksnya, lihat Anatomi kolom.

Mendapatkan bantuan upgrade

Catatan: Sebelum meminta bantuan upgrade, harap lakukan yang terbaik untuk mengupgrade kolom Anda secara independen menggunakan informasi yang diberikan.

Yang harus diberikan

Ketika meminta bantuan, sebaiknya ajukan pertanyaan spesifik:

Tidak direkomendasikan: "Apa yang salah dengan kolom ini?"

Juga tidak direkomendasikan: "Bantu saya mengupgrade kolom ini".

Direkomendasikan: "Teks kolom tidak diperbarui dengan benar".

Anda juga perlu menyediakan referensi kepada orang yang membantu Anda. File ini harus mudah digunakan oleh orang lain.

Tidak direkomendasikan:

• Gambar kode.
• Kode tidak lengkap.

Direkomendasikan:

• Lengkapi kode kolom dalam format teks.
• Gambar gif perilaku kolom yang buruk.
• Langkah-langkah untuk mereproduksi perilaku kolom yang buruk.
• Versi blockly tempat Anda mengupgradenya.

Tempat memposting

Posting pertanyaan tentang upgrade di forum developer blockly.

Jika Anda yakin bahwa masalah tersebut berkaitan dengan inti yang blok, Anda juga dapat memposting masalah di GitHub yang blok-blok. Jika Anda memutuskan untuk memposting masalah, lengkapi semua informasi yang diminta.