ترقية حقل مخصّص

في تموز (يوليو) 2019 (الإصدار 2.20190722)، تمت إضافة واجهة برمجة تطبيقات أكثر ترميزًا للحقول. وهي مصمَّمة لتكون متوافقة مع الأنظمة القديمة قدر الإمكان. هذا يعني أنّه إذا كنت قد أنشأت حقلًا مخصّصًا قبل يوليو 2019، من المرجّح أن يستمر في العمل. قبل اتخاذ قرار بشأن ما إذا كان يجب ترقية الحقل المخصّص، عليك قراءة قسم المناطق الخطرة وإجراء اختبار شامل للحقل.

بسبب عدم توحيد الحقول قبل تموز (يوليو) 2019، يصعب تغطية جميع التغييرات التي قد يحتاج المطوّر إلى إجرائها. يحاول هذا المستند تغطية جميع التغييرات المحتملة، ولكن إذا لم يتضمّن المستند أي معلومات تهمّك، يُرجى قراءة القسم حول الحصول على مساعدة بشأن الترقية.

ملاحظة: إذا كان لديك عدد صغير من الحقول المخصّصة، قد يكون من الأسهل إعادة كتابتها ببساطة باستخدام تعليمات إنشاء الحقول المخصّصة، بدلاً من محاولة ترقيتها بشكل جزئي.

مناطق الخطر

مناطق الخطر هي أماكن معروفة تم فيها تغيير واجهة برمجة التطبيقات، وقد يتعطّل الحقل.

Blockly.Field.register

لم يعُد يتم تسجيل الحقول من خلال Blockly.Field.register();. تتوفّر الآن مساحة اسم fieldRegistry تتعامل مع عملية التسجيل.

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

يصبح:

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

setText

لم يعُد يتم استدعاء الدالة 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_;
}

يتعامل Blockly تلقائيًا مع ما يلي:

• التحقّق مما إذا كانت القيمة الجديدة مختلفة عن القيمة القديمة
• تعديل القيمة
• إطلاق أحداث التغيير
• إعادة عرض الحقل

عليك التعامل مع ما يلي:

• التحقّق من صحة القيمة (doClassValidation_):
• نص الحقل (getText)
• واجهة مستخدم الحقل

ملاحظة: ننصحك بتغيير أي طلبات setText إلى طلبات setValue، لأنّ setValue يتيح التحقّق من الصحة بينما لا يتيح ذلك setText.

الترقيات المُقترحة

الترقيات المقترَحة هي مواضع تم فيها تغيير واجهة برمجة التطبيقات للحقل، ولكن إذا اخترت عدم إجراء تغييرات، سيظل الحقل يعمل على الأرجح.

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. إذا اخترت عدم إجراء أي تغيير، سيعمل كل شيء بشكل صحيح وسيتم تسلسل الحقل، ولكن ستتلقّى تحذيرات في وحدة التحكّم.

size_.width

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

تم تحويل الدالة 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_.
• عرض الحقل
• ربط تلميح الأدوات وعرض أحداث المحرّر

عليك التعامل مع ما يلي:

• إضافة عناصر DOM إضافية (initView)
• إضافة روابط أحداث إضافية (bindEvents_)
• التخلّص من عمليات ربط الأحداث (dispose)

ملاحظة مهمة: يجب إنشاء جميع عناصر DOM داخل initView لأنّ ذلك هو الأسلوب الأكثر فعالية. ننصحك بإعادة تصميم الرمز إذا كنت تنشئ نموذج DOM داخل الدالة الإنشائية أو setText أو setValue أو render_.

onMouseDown_

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

يصبح:

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

ننصحك بتجاوز الدالة showEditor_ للتعامل مع نقرات الماوس بدلاً من الدالة onMouseDown_، لأنّ ذلك يسمح بتمرير الإدخال عبر نظام الإيماءات.

لمزيد من المعلومات عن المحرّرين، يُرجى الاطّلاع على المحرّرون.

setValue

أصبحت الدالة setValue الآن دالة نموذجية بهدف تقليل التعليمات البرمجية المكرّرة في الفئات الفرعية. إذا كانت الدالة setValue تحتوي على منطق، ننصحك بإعادة هيكلتها لتناسب مسارات معالجة القيم الموضّحة في معالجة القيم.

text_

ننصحك بعدم الوصول إلى السمة text_ الخاصة بالحقل أو تعديلها مباشرةً. بدلاً من ذلك، استخدِم الدالة getText للوصول إلى النص القابل للقراءة الخاص بالحقل، واستخدِم الدالة setValue لتعديل القيمة المخزّنة للحقل.

لمزيد من المعلومات حول قيمة الحقل مقارنةً بنصه، اطّلِع على بنية الحقل.

الحصول على مساعدة في الترقية

ملاحظة: قبل طلب المساعدة في الترقية، يُرجى بذل قصارى جهدك لترقية الحقل بشكل مستقل باستخدام المعلومات المقدَّمة.

المعلومات المطلوب تقديمها

عند طلب المساعدة، من الأفضل طرح أسئلة محدّدة:

غير محبَّذ: "ما المشكلة في هذا الحقل؟"

لا يُنصح أيضًا باستخدام عبارة "ساعدني في ترقية هذا الحقل".

يُفضّل استخدام: "لا يتم تعديل نص الحقل بشكلٍ صحيح".

من الضروري أيضًا توفير الموارد للأشخاص الذين يساعدونك. ويجب أن يسهل على الآخرين استخدام هذه الملفات.

لا يُنصح بما يلي:

• صور للرموز البرمجية
• رمز غير مكتمل

الإعدادات المُوصى بها:

• رمز الحقل الكامل بتنسيق نصي
• صور لملفات GIF تعرض سلوكًا سيئًا في الحقول
• خطوات إعادة إنتاج سلوك الحقل السيئ
• إصدار Blockly الذي تتم الترقية منه

مكان نشر المشاركة

يمكنك نشر أسئلة ما بعد الترقية على منتدى مطوّري Blockly.

إذا كنت متأكدًا من أنّ المشكلة مرتبطة ببرنامج Blockly الأساسي، يمكنك أيضًا نشر مشكلة على GitHub الخاص بـ Blockly. إذا قررت نشر مشكلة، يُرجى ملء جميع المعلومات المطلوبة.