یک فیلد سفارشی را ارتقا دهید

در ژوئیه ۲۰۱۹ ( نسخه ۲.۲۰۱۹۰۷۲۲ ) یک API فیلدهای مدون‌تر اضافه شد. این API طوری طراحی شده است که تا حد امکان با نسخه‌های قبلی سازگار باشد. این بدان معناست که اگر قبل از ژوئیه ۲۰۱۹ یک فیلد سفارشی ایجاد کرده‌اید، به احتمال زیاد به کار خود ادامه خواهد داد. قبل از تصمیم‌گیری در مورد نیاز به ارتقاء فیلد سفارشی خود، باید بخش « مناطق خطرناک» را مطالعه کنید و فیلد خود را به طور کامل آزمایش کنید.

از آنجا که قبل از ژوئیه ۲۰۱۹ استانداردسازی بین فیلدها وجود نداشت، پوشش دادن تمام تغییراتی که یک توسعه‌دهنده ممکن است نیاز به انجام آن داشته باشد، دشوار است. این سند سعی دارد تمام تغییرات احتمالی را پوشش دهد، اما اگر این سند چیزی را که شما به آن علاقه دارید پوشش نمی‌دهد، لطفاً بخش مربوط به دریافت کمک برای ارتقاء را مطالعه کنید.

مناطق خطرناک

مناطق خطرناک، مکان‌های شناخته‌شده‌ای هستند که API در آن‌ها تغییر کرده است و فیلد شما می‌تواند دچار مشکل شود.

فیلد مسدود شده را ثبت کنید

فیلدها دیگر از طریق Blockly.Field.register(); ثبت نمی‌شوند. اکنون یک فضای نام fieldRegistry وجود دارد که ثبت را مدیریت می‌کند.

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

می‌شود:

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

متن تنظیم شده

تابع setText دیگر توسط هسته Blockly فراخوانی نمی‌شود، بنابراین اگر تابع setText شما حاوی منطق باشد، باید به مجموعه توابع مدیریت مقدار ، تابع getText و توابع رندر (بسته به اینکه تابع 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;
};

می‌شود:

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

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

به طور خودکار موارد زیر را مدیریت می‌کند:

  • بررسی اینکه آیا مقدار جدید با مقدار قدیمی متفاوت است یا خیر.
  • به‌روزرسانی مقدار.
  • اخراج، رویدادها را تغییر می‌دهد.
  • رندر مجدد فیلد.

شما باید موارد زیر را مدیریت کنید:

ارتقاءهای پیشنهادی، مواردی هستند که API فیلد تغییر کرده است، اما اگر تصمیم به ایجاد تغییرات نداشته باشید، فیلد شما به احتمال زیاد همچنان کار خواهد کرد.

قابل سریال‌سازی

برای اطلاعات بیشتر در مورد ویژگی‌های EDITABLE و SERIALIZABLE به بخش ویژگی‌های Editable و serializable مراجعه کنید.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

هشدار زیر قابل چشم‌پوشی نیست، اما می‌توانید با تعریف ویژگی SERIALIZABLE آن را برطرف کنید:

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

هشدار بالا به این معنی است که Blockly معتقد است که شما می‌خواهید فیلد سریال‌سازی شود (زیرا ویژگی EDITABLE درست است)، اما تا زمانی که ویژگی SERIALIZABLE را تعریف نکنید، نمی‌تواند مطمئن باشد. اگر این مورد را به حال خود رها کنید، همه چیز به درستی کار خواهد کرد و فیلد شما سریال‌سازی می‌شود، اما هشدارهای کنسول را دریافت خواهید کرد.

اندازه_عرض 

this.size_.width = 0;

می‌شود:

this.isDirty_ = true;

هشدار زیر قابل چشم‌پوشی نیست، اما می‌توانید با تنظیم ویژگی isDirty_ به جای ویژگی size_.width آن را برطرف کنید:

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

هشدار بالا به این معنی است که Blockly تشخیص داده است که شما از یک روش قدیمی برای رندر مجدد یک فیلد استفاده می‌کنید و می‌خواهد که شما از روش جدید استفاده کنید.

برای اطلاعات بیشتر در مورد ویژگی isDirty_ به isDirty_ مراجعه کنید.

اولیه

تابع init به یک تابع الگو تبدیل شده است تا کدهای تکراری در زیرکلاس‌ها کاهش یابد. 

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

می‌شود: 

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

این یعنی که blockly حالا به طور خودکار موارد زیر را مدیریت می‌کند:

  • بررسی اینکه آیا فیلد از قبل مقداردهی اولیه شده است یا خیر.
  • ایجاد fieldGroup_ .
  • رندر کردن فیلد.
  • راهنمای ابزار اتصال و نمایش رویدادهای ویرایشگر.

شما باید موارد زیر را مدیریت کنید:

onMouseDown_ 

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

می‌شود: 

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

توصیه می‌کنیم برای مدیریت کلیک‌های ماوس، به جای تابع onMouseDown_ تابع showEditor_ را بازنویسی کنید، زیرا این تابع اجازه می‌دهد ورودی از طریق سیستم اشاره‌ای عبور کند.

برای اطلاعات بیشتر در مورد ویراستاران، به بخش ویراستاران مراجعه کنید.

مقدار را تنظیم کنید

تابع setValue اکنون یک تابع الگو برای کاهش کدهای تکراری در زیرکلاس‌ها است. اگر تابع setValue شما حاوی منطق است، آن را طوری تغییر دهید که با مسیرهای مدیریت مقدار شرح داده شده در بخش مدیریت مقدار مطابقت داشته باشد.

متن_

توصیه می‌کنیم هرگز مستقیماً به ویژگی text_ فیلد خود دسترسی پیدا نکنید یا آن را به‌روزرسانی نکنید. در عوض، از تابع getText برای دسترسی به متن قابل خواندن توسط کاربر در فیلد خود و از تابع setValue برای به‌روزرسانی مقدار ذخیره شده در فیلد خود استفاده کنید.

برای اطلاعات بیشتر در مورد مقدار یک فیلد در مقابل متن آن، به آناتومی یک فیلد مراجعه کنید.

دریافت کمک برای ارتقاء

چه چیزی ارائه دهیم

هنگام درخواست کمک، بهتر است سوالات مشخصی بپرسید:

توصیه نمی‌شود: «مشکل این فیلد چیست؟»

همچنین توصیه نمی‌شود: "به من در ارتقاء این فیلد کمک کنید."

توصیه شده: "متن فیلد به درستی به‌روزرسانی نمی‌شود."

همچنین لازم است منابعی را در اختیار افرادی که به شما کمک می‌کنند قرار دهید. این فایل‌ها باید برای استفاده دیگران آسان باشند.

توصیه نمی‌شود:

  • تصاویری از کدها
  • کد ناقص.

توصیه شده:

  • کد فیلد را در قالب متن کامل کنید.
  • تصاویر گیف از رفتار بد در میدان.
  • مراحلی برای بازتولید رفتار میدان بد.
  • نسخه blockly که از آن ارتقا می‌دهید.

کجا پست بگذاریم

سوالات مربوط به ارتقا را در انجمن توسعه‌دهندگان blockly مطرح کنید.

اگر مطمئن هستید که مشکل از هسته blockly است، می‌توانید آن را در گیت‌هاب blockly نیز ارسال کنید . اگر تصمیم به ارسال مشکل دارید، لطفاً تمام اطلاعات درخواستی را پر کنید.