Özel alanları yükseltme

Temmuz 2019'da (2.20190722 sürümü) daha fazla kodlanmış alan API'si eklendi. Mümkün olduğunca geriye dönük uyumlu olması amaçlanmıştır. Bu nedenle, Temmuz 2019'dan önce oluşturduğunuz özel alanlar büyük olasılıkla çalışmaya devam edecektir. Özel alanınızın yükseltilmesi gerekip gerekmediğine karar vermeden önce Tehlikeli alanlar bölümünü okumalı ve alanınızı kapsamlı bir şekilde test etmelisiniz.

Temmuz 2019'dan önce alanlar arasında standartlaştırma yapılmadığından, geliştiricilerin yapması gereken tüm değişiklikleri kapsamak zordur. Bu belgede olası tüm değişiklikler ele alınmaya çalışılmıştır. Ancak bu belgede ilgilendiğiniz bir konu yer almıyorsa lütfen yükseltme yardımı alma bölümünü okuyun.

Not: Az sayıda özel alanınız varsa bunları tek tek yükseltmeye çalışmak yerine özel alan oluşturma talimatlarını kullanarak yeniden yazmanız daha kolay olabilir.

Tehlikeli bölgeler

Tehlikeli alanlar, API'nin değiştiği ve alanınızın bozulabileceği bilinen yerlerdir.

Blockly.Field.register

Alanlar artık Blockly.Field.register(); üzerinden kaydedilmiyor. Kayıt işlemini gerçekleştiren bir fieldRegistry ad alanı vardır.

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

Şu olur:

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

setText

setText işlevi artık Blockly çekirdeği tarafından çağrılmıyor. Bu nedenle, setText işleviniz mantık içeriyorsa bu mantığın setText işlevinin tam olarak ne yaptığına bağlı olarak değer işleme işlevleri paketi, getText işlevi ve oluşturma işlevlerine taşınması gerekir.

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;
};

Şu olur:

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

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

Blockly, aşağıdakileri otomatik olarak işler:

• Yeni değerin eski değerden farklı olup olmadığını kontrol etme
• Değer güncelleniyor.
• Değişiklik etkinliklerini tetikleme.
• Alanı yeniden oluşturma.

Şunları yapmanız gerekir:

• Değer doğrulama (doClassValidation_).
• Alan metni (getText).
• Alan kullanıcı arayüzü

Not: setValue doğrulama özelliğini desteklediği, setText ise desteklemediği için setText çağrılarını setValue çağrılarına değiştirmenizi öneririz.

Önerilen yükseltmeler

Önerilen yükseltmeler, alan API'sinin değiştirildiği yerlerdir. Ancak değişiklik yapmamayı tercih ederseniz alanınız büyük olasılıkla çalışmaya devam eder.

SERILEŞTIRILEBILIR

EDITABLE ve SERIALIZABLE özellikleri hakkında daha fazla bilgi için Düzenlenebilir ve serileştirilebilir özellikler başlıklı makaleyi inceleyin.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

Aşağıdaki uyarıyı yoksayabilirsiniz ancak SERIALIZABLE özelliğini tanımlayarak uyarıyı çözebilirsiniz:

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

Yukarıdaki uyarı, Blockly'nin EDITABLE özelliği doğru olduğundan alanın serileştirilmesini istediğinizi düşündüğü ancak SERIALIZABLE özelliğini tanımlayana kadar bundan emin olamayacağı anlamına gelir. Bu alanı olduğu gibi bırakırsanız her şey düzgün çalışır ve alanınız serileştirilir ancak konsol uyarıları alırsınız.

size_.width

this.size_.width = 0;

Şu olur:

this.isDirty_ = true;

Aşağıdaki uyarı yoksayılabilir ancak size_.width özelliği yerine isDirty_ özelliği ayarlanarak çözülebilir:

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

Yukarıdaki uyarı, Blockly'nin bir alanı yeniden oluşturmak için eski bir yöntem kullandığınızı algıladığı ve yeni yöntemi kullanmanızı istediği anlamına gelir.

isDirty_ özelliği hakkında daha fazla bilgi için isDirty_ başlıklı makaleyi inceleyin.

init

init işlevi, alt sınıflardaki yinelenen kodu azaltmak için şablon işlevi haline getirildi.

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());
};

Şu olur:

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_);
};

Bu sayede Blockly artık otomatik olarak şunları işler:

• Alanın zaten başlatılıp başlatılmadığını kontrol etme.
• fieldGroup_ oluşturuluyor.
• Alan oluşturuluyor.
• Bağlama ipucu ve düzenleyici etkinliklerini gösterme.

Şunları yapmanız gerekir:

• Ek DOM öğeleri (initView) ekleme.
• Ek etkinlik bağlamaları (bindEvents_) ekleme.
• Etkinlik bağlamalarının kaldırılması (dispose).

Önemli: Tüm DOM oluşturma işlemleri en verimli yöntem olduğu için initView içinde yapılmalıdır. Yapıcı, setText, setValue veya render_ içinde DOM oluşturma işlemi yapıyorsanız yeniden düzenlemeyi düşünebilirsiniz.

onMouseDown_

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

Şu olur:

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

Fare tıklamalarını işlemek için showEditor_ işlevi yerine onMouseDown_ işlevini geçersiz kılmanızı öneririz. Bu sayede girişin hareket sisteminden geçmesine izin verilir.

Düzenleyiciler hakkında daha fazla bilgi için Düzenleyiciler başlıklı makaleyi inceleyin.

setValue

setValue işlevi, alt sınıflardaki yinelenen kodu azaltmak için artık şablon işlevi olarak kullanılıyor. setValue işleviniz mantık içeriyorsa Değer işleme bölümünde açıklanan değer işleme yollarına uyacak şekilde yeniden düzenlemeyi düşünebilirsiniz.

text_

Alanınızın text_ özelliğine asla doğrudan erişmemenizi veya bu özelliği doğrudan güncellememenizi öneririz. Bunun yerine, alanınızın kullanıcı tarafından okunabilir metnine erişmek için getText işlevini, alanınızın depolanan değerini güncellemek için ise setValue işlevini kullanın.

Bir alanın değeri ile metni arasındaki fark hakkında daha fazla bilgi için Bir alanın yapısı başlıklı makaleyi inceleyin.

Yükseltme konusunda yardım alma

Not: Yükseltme konusunda yardım istemeden önce lütfen sağlanan bilgileri kullanarak alanınızı bağımsız olarak yükseltmek için elinizden geleni yapın.

Sağlanması gerekenler

Yardım isterken belirli sorular sormanız en iyisidir:

Önerilmeyen: "Bu alanda ne gibi sorunlar var?"

Ayrıca şu istem de önerilmez: "Bu alanı yükseltmeme yardım et."

Önerilen: "Alan metni düzgün şekilde güncellenmiyor."

Ayrıca, size yardımcı olan kişilere kaynak sağlamanız da gerekir. Bu dosyaların diğer kullanıcılar tarafından kolayca kullanılabilmesi gerekir.

Önerilmeyenler:

• Kod resimleri
• Kod eksik.

Önerilen:

• Metin biçiminde tam alan kodu.
• Kötü saha davranışının GIF görüntüleri
• Kötü alan davranışını yeniden oluşturma adımları.
• Yükseltme yaptığınız Blockly sürümü.

Nerede yayınlanır?

Yükseltme sonrası sorularınızı Blockly geliştirici forumunda paylaşın.

Sorunun Blockly çekirdeğiyle ilgili olduğundan eminseniz Blockly GitHub'da sorun bildirebilirsiniz. Bir sorun yayınlamaya karar verirseniz lütfen istenen tüm bilgileri girin.