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

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

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

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

المناطق الخطرة

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

Blockly.Field.register

لم تعُد الحقول مسجَّلة حتى Blockly.Field.register();. تتوفر أصبحت الآن مساحة اسم حقل السجل التي تعالج التسجيل.

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

يصبح:

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

setText

لم يعُد يتم استدعاء الدالة setText بواسطة وحدة أساسية حظرية، لذا إذا كان 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_;
}

تعالج بشكل تلقائي ما يلي:

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

يجب معالجة ما يلي:

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

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

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

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

قابل للتحويل

لمزيد من المعلومات حول السمتَين 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 إلى نموذج الدالة تقليل التعليمات البرمجية المكررة في الفئات الفرعية.

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

وهذا يعني أنّ ميزة "حظر" تعالج الآن تلقائيًا ما يلي:

• التحقق مما إذا كان قد تم إعداد الحقل من قبل.
• جارٍ إنشاء 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 حول سلوك الحقل السيئ.
• خطوات إعادة إنتاج سلوك الحقل السيئ.
• إصدار الحظر الذي تريد الترقية منه.

مكان النشر

نشر أسئلة الترقية على المطوّر الذي يحظره المنتدى.

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