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

في تموز (يوليو) 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 اسم نواة نمط الحظر، لذا إذا كانت الدالة 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.

يشير التحذير أعلاه إلى أنّ Bluely يعتقد أنّك تريد أن يكون الحقل متسلسلاً (لأنّ السمة 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.

يعني التحذير أعلاه أنّ حظر المحتوى قد رصد أنّك تستخدم طريقة قديمة لعرض حقل، ويريد منك استخدام الطريقة الجديدة.

لمزيد من المعلومات حول السمة 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_);
};

ويعني ذلك أنّ حظر التطبيقات يعالج تلقائيًا ما يلي:

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

مكان النشر

انشر أسئلة الترقية على منتدى المطورين المؤقتين.

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