Meningkatkan bidang khusus

Pada Juli 2019 (rilis 2.20190722) API bidang yang lebih terkodifikasi telah ditambahkan. Hal ini dimaksudkan untuk kompatibel dengan versi sebelumnya. Ini berarti bahwa jika Anda telah membuat sebelum Juli 2019, kolom kustom tersebut kemungkinan besar akan terus berfungsi. Sebelum memutuskan apakah bidang khusus perlu ditingkatkan, Anda harus membaca melalui bagian Area berbahaya, dan lakukan pengujian menyeluruh untuk bidang Anda.

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

Catatan: Jika Anda memiliki sedikit kolom kustom, mungkin akan lebih mudah untuk menulisnya ulang menggunakan petunjuk pembuatan kolom kustom, daripada mencoba mengupgradenya secara bertahap.

Area bahaya

Area bahaya adalah tempat yang diketahui di mana API telah berubah, dan {i>field <i}Anda bisa rusak.

Blockly.Field.register

Kolom tidak lagi terdaftar melalui Blockly.Field.register();. Ada sekarang menjadi 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 Blockly core, jadi jika setText berisi logika yang harus dipindahkan ke penanganan nilai rangkaian fungsi, yaitu getText fungsi, dan fungsi rendering (bergantung pada apa yang sebenarnya dilakukan fungsi setText).

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 dengan nilai lama.
• Memperbarui nilai.
• Mengaktifkan peristiwa perubahan.
• Merender ulang kolom.

Anda harus menangani:

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

Catatan: Sebaiknya ubah panggilan setText menjadi Panggilan setValue, karena setValue mendukung validasi dan setText tidak.

Upgrade yang direkomendasikan

Upgrade yang direkomendasikan adalah tempat API kolom telah diubah, tetapi jika Anda memilih untuk tidak membuat perubahan pada {i>field<i} Anda kemungkinan besar masih akan berfungsi.

DAPAT DI SERIALISASI

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

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

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

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 bahwa Blockly yakin bahwa Anda menginginkan kolom untuk diserialisasi (karena properti EDITABLE bernilai benar), tetapi Anda tidak dapat memastikannya hingga Anda menentukan properti SERIALIZABLE. Jika Anda memilih untuk membiarkannya, semuanya akan berfungsi dengan baik, dan {i>field<i} Anda akan diserialisasi, tetapi Anda akan menerima peringatan konsol.

size_.width

this.size_.width = 0;

Menjadi:

this.isDirty_ = true;

Peringatan di bawah tidak dapat diabaikan, tetapi Anda dapat mengatasinya dengan menyetel isDirty_ properti, 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 bahwa Blockly mendeteksi Anda menggunakan metode lama untuk merender ulang , dan ingin Anda menggunakan metode baru.

Untuk informasi selengkapnya tentang properti isDirty_, lihat isDirty_.

init

Fungsi init telah dibuat menjadi template fungsi ke mengurangi kode duplikat di 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 blok-blok sekarang otomatis menangani:

• Memeriksa apakah kolom sudah diinisialisasi atau belum.
• Membuat fieldGroup_.
• Merender kolom.
• Tooltip binding dan menampilkan peristiwa editor.

Anda harus menangani:

• Menambahkan Elemen DOM (initView).
• Menambahkan binding peristiwa (bindEvents_).
• Pembuangan binding peristiwa (dispose).

Penting: Semua pembuatan DOM harus dilakukan di dalam initView karena tindakan tersebut adalah yang paling efisien. Pertimbangkan pemfaktoran 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 mouse klik, bukan fungsi onMouseDown_, karena memungkinkan input untuk meneruskan melalui sistem gestur.

Untuk mengetahui informasi selengkapnya tentang editor, lihat Editor.

setValue

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

text_

Sebaiknya jangan pernah mengakses atau memperbarui properti text_ properti secara langsung. Sebagai gantinya, gunakan Fungsi getText untuk mengakses teks yang dapat dibaca pengguna pada {i>field <i}Anda dan Fungsi setValue untuk memperbarui nilai yang disimpan pada {i>field<i} Anda.

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

Mendapatkan bantuan upgrade

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

Yang harus disediakan

Saat 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 sumber daya kepada orang yang membantu Anda. Ini file harus mudah digunakan oleh orang lain.

Tidak direkomendasikan:

• Gambar kode.
• Kode tidak lengkap.

Direkomendasikan:

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

Tempat memposting

Posting pertanyaan upgrade pada pengembang blockly forum ini.

Jika Anda yakin bahwa masalahnya adalah masalah dengan inti blok, Anda dapat juga posting masalah di GitHub yang sangat terbuka. Jika Anda memutuskan untuk memposting masalah, lengkapi semua informasi yang diminta.