إنشاء نوع حقل جديد

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

لإنشاء حقل جديد، اتّبِع الخطوات التالية:

  1. تنفيذ دالة إنشاء:
  2. سجِّل مفتاح JSON ونفِّذ fromJson.
  3. التعامل مع إعداد واجهة المستخدم والحدث على الكتلة المستمعين.
  4. التعامل مع التخلص من أدوات معالجة الأحداث (يتم التعامل مع التخلص من عناصر معالجة الأحداث في هويتك).
  5. تنفيذ معالجة القيمة:
  6. أضِف تمثيلاً نصيًا لقيمة الحقل لتسهيل الاستخدام.
  7. يمكنك إضافة المزيد من الوظائف، مثل:
  8. يمكنك إعداد جوانب إضافية لحقلك، مثل:

يفترض هذا القسم أنك قد قرأت محتوى الصفحة في تشريح الحقل.

للحصول على مثال لحقل مخصص، راجع الحقول المخصصة إصدار تجريبي .

تنفيذ دالة إنشائية

تكون الدالة الإنشائية للحقل مسؤولة عن إعداد القيمة الأولية للحقل ولإعداد نموذج محلي المدقق. مخصّص يتم استدعاء الدالة الإنشائية للحقل أثناء تهيئة حظر المصدر بغض النظر عن لتحديد ما إذا كانت حزمة المصدر محددة في JSON أو JavaScript. لذلك، فإن التخصيص لا يمكن للحقل الوصول إلى مجموعة المصدر أثناء الإنشاء.

ينشئ نموذج الرمز البرمجي التالي حقلاً مخصّصًا باسم "GenericField":

class GenericField extends Blockly.Field {
  constructor(value, validator) {
    super(value, validator);

    this.SERIALIZABLE = true;
  }
}

توقيع الطريقة

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

البنية

يجب أن يتبع المنطق داخل الدالة الإنشائية هذا التدفق:

  1. استدعِ الدالة الإنشائية المتميزة الموروثة (يجب أن تكتسب جميع الحقول المخصصة من Blockly.Field أو إحدى فئاتها الفرعية) لإعداد القيمة بشكلٍ صحيح واضبط المدقق المحلي لحقلك.
  2. إذا كان الحقل قابلاً للتسلسل، فعيّن الخاصية المقابلة في الدالة الإنشائية. يجب أن تكون الحقول القابلة للتعديل قابلة للتعديل، وأن تكون الحقول قابلة للتعديل. بشكل افتراضي، لذا ربما يتعين عليك تعيين هذه الخاصية على صواب ما لم تكن تعرف فلا ينبغي أن تكون قابلة للتسلسل.
  3. اختياري: تطبيق تخصيص إضافي (على سبيل المثال، حقول التصنيف للسماح بتمرير فئة css، والتي يتم تطبيقها بعد ذلك على النص).

JSON والتسجيل

في جزء JSON والتعريفات يتم وصف الحقول بسلسلة (مثل field_number، field_textinput). يحتفظ بخريطة من هذه السلاسل إلى كائنات الحقول والمكالمات fromJson على العنصر المناسب أثناء البناء.

اتصل بـ Blockly.fieldRegistry.register لإضافة نوع حقلك إلى هذه الخريطة، تمرير فئة الحقل كوسيطة ثانية:

Blockly.fieldRegistry.register('field_generic', GenericField);

ستحتاج أيضًا إلى تعريف دالة fromJson. يجب أن تكون عملية التنفيذ الإشارة أولاً إلى أي سلسلة نصية . استخدام المراجع replaceMessageReferences, ثم تمرير القيم إلى الدالة الإنشائية.

GenericField.fromJson = function(options) {
  const value = Blockly.utils.parsing.replaceMessageReferences(
      options['value']);
  return new CustomFields.GenericField(value);
};

جارٍ الإعداد

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

شاشة عند الحظر

أثناء التهيئة، تكون مسئولاً عن إنشاء أي شيء ستحتاجه لعرض الحقل على الكتلة.

الإعدادات التلقائية والخلفية والنص

تنشئ الدالة initView التلقائية عنصر rect بلون فاتح العنصر text إذا كنت تريد أن يحتوي مجال عملك على كليهما، إلى جانب جديدة، استدعينا الدالة الفائقة initView قبل إضافة باقي عناصر DOM. إذا كنت ترغب في أن يحتوي مجالك على أحدهما، ولكن ليس كليهما، العناصر التي يمكنك استخدام الدالتين createBorderRect_ أو createTextElement_.

تخصيص إنشاء نموذج العناصر في المستند (DOM)

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

على سبيل المثال، قد يحتوي حقل القائمة المنسدلة على صور ونص. بعد initView ينشئ عنصرًا صورة واحدًا وعنصرًا نصيًا واحدًا. ثم خلال render_ يظهر العنصر النشط ويخفي الآخر بناءً على نوع المحدد.

ويمكن إنشاء عناصر DOM باستخدام دالة Blockly.utils.dom.createSvgElement أو باستخدام عملية إنشاء DOM التقليدية الطرق.

فيما يلي متطلبات عرض الحقل على الكتلة:

  • يجب أن تكون جميع عناصر DOM عناصر ثانوية للحقل fieldGroup_. المجال مجموعة يتم إنشاؤها تلقائيًا.
  • يجب أن تبقى جميع عناصر DOM داخل أبعاد الحقل التي تم الإبلاغ عنها.

يمكنك الاطّلاع على العرض لمزيد من التفاصيل حول تخصيص وتحديث شاشة العرض على الكتلة.

إضافة رموز نصية

إذا كنت تريد إضافة رموز إلى نص الحقل (مثل الزاوية رمز درجة الحقل) يمكنك إلحاق عنصر الرمز (عادةً ما يكون مضمنًا في <tspan>) مباشرةً إلى textElement_ في الحقل.

أحداث الإدخال

تُسجِّل الحقول التلقائية أحداث تلميحات الأدوات وأحداث تمرير الماوس (لاستخدامها في يظهر المحررين). إذا كنت تريد الاستماع إلى أنواع أخرى من الأحداث (على سبيل المثال، إذا كنت تريد معالجة السحب على أحد الحقول) يجب إلغاء دالة bindEvents_ للحقل.

bindEvents_() {
  // Call the superclass function to preserve the default behavior as well.
  super.bindEvents_();

  // Then register your own additional event listeners.
  this.mouseDownWrapper_ =
  Blockly.browserEvents.conditionalBind(this.getClickTarget_(), 'mousedown', this,
      function(event) {
        this.originalMouseX_ = event.clientX;
        this.isMouseDown_ = true;
        this.originalValue_ = this.getValue();
        event.stopPropagation();
      }
  );
  this.mouseMoveWrapper_ =
    Blockly.browserEvents.conditionalBind(document, 'mousemove', this,
      function(event) {
        if (!this.isMouseDown_) {
          return;
        }
        var delta = event.clientX - this.originalMouseX_;
        this.setValue(this.originalValue_ + delta);
      }
  );
  this.mouseUpWrapper_ =
    Blockly.browserEvents.conditionalBind(document, 'mouseup', this,
      function(_event) {
        this.isMouseDown_ = false;
      }
  );
}

للالتزام بحدث ما، يجب عليك بشكل عام استخدام Blockly.utils.browserEvents.conditionalBind الأخرى. تعمل طريقة ربط الأحداث هذه على تصفية اللمسات الثانوية أثناء يسحب. إذا كنت تريد أن يعمل المعالج حتى في منتصف عملية السحب الجارية يمكنك استخدام Blockly.browserEvents.bind الأخرى.

للاستعمال

إذا سجّلت أيّ أدوات استماع للأحداث المخصّصة داخل bindEvents_ للحقل الدالة يجب أن تكون غير مسجَّلة في الدالة dispose.

إذا قمت بتهيئة ملف مشاهدة الحقل (من خلال إلحاق جميع عناصر DOM في fieldGroup_)، ثم سيتم التخلص من DOM للحقل تلقائيًا.

التعامل مع القيمة

→ للحصول على معلومات حول قيمة أحد الحقول مقابل نصه، يمكنك مراجعة تشريح .

ترتيب التحقق من الصحة

رسم بياني انسيابي يصف ترتيب تشغيل المدقّقات

تنفيذ مدقق للفئة

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

لاستخدام أداة التحقّق من الفئة في الحقل، عليك إلغاء doClassValidation_. الأخرى.

doClassValidation_(newValue) {
  if (typeof newValue != 'string') {
    return null;
  }
  return newValue;
};

التعامل مع القيم الصالحة

إذا كانت القيمة التي تم تمريرها إلى حقل يتضمن setValue صالحة، ستتلقى معاودة الاتصال doValueUpdate_. تكون الدالة doValueUpdate_ تلقائيًا:

  • تضبط السمة value_ على newValue.
  • لضبط isDirty_ على true.

إذا أردت ببساطة تخزين القيمة بدون اتّخاذ أي إجراءات معالجة مخصّصة، ولا تحتاج إلى إلغاء doValueUpdate_.

أما إذا كنت تريد تنفيذ إجراءات مثل:

  • مساحة تخزين مخصّصة لـ newValue
  • يمكنك تغيير الخصائص الأخرى استنادًا إلى newValue.
  • احفظ ما إذا كانت القيمة الحالية صالحة أم لا.

ستحتاج إلى إلغاء doValueUpdate_:

doValueUpdate_(newValue) {
  super.doValueUpdate_(newValue);
  this.displayValue_ = newValue;
  this.isValueValid_ = true;
}

التعامل مع القيم غير الصالحة

إذا كانت القيمة التي تم إدخالها إلى الحقل الذي يتضمن setValue غير صالحة، ستتلقى معاودة الاتصال doValueInvalid_. بشكل تلقائي، لا تستخدم الدالة doValueInvalid_ لا شيء. وهذا يعني أنه لن تظهر القيم غير الصالحة بشكل افتراضي. وكذلك يعني أنه لن يتم عرض الحقل، لأن isDirty_ .

وإذا أردت عرض القيم غير الصالحة، عليك إلغاء السمة doValueInvalid_. في معظم الحالات، يجب ضبط السمة displayValue_ على قيمة غير صالحة، تعيين isDirty_ إلى true، وتجاوز render_ لتعديل طريقة العرض المحظورة بناءً على displayValue_ بدلاً من value_

doValueInvalid_(newValue) {
  this.displayValue_ = newValue;
  this.isDirty_ = true;
  this.isValueValid_ = false;
}

قيم متعددة الأجزاء

عندما يحتوي الحقل على قيمة متعددة الأجزاء (على سبيل المثال، القوائم والمتجهات والكائنات) يمكنك قد يرغب في التعامل مع الأجزاء كقيم فردية.

doClassValidation_(newValue) {
  if (FieldTurtle.PATTERNS.indexOf(newValue.pattern) == -1) {
    newValue.pattern = null;
  }

  if (FieldTurtle.HATS.indexOf(newValue.hat) == -1) {
    newValue.hat = null;
  }

  if (FieldTurtle.NAMES.indexOf(newValue.turtleName) == -1) {
    newValue.turtleName = null;
  }

  if (!newValue.pattern || !newValue.hat || !newValue.turtleName) {
    this.cachedValidatedValue_ = newValue;
    return null;
  }
  return newValue;
}

في المثال أعلاه، يتم التحقّق من صحة كل سمة من سمات newValue على حدة. بَعْدَ ذَلِكْ في نهاية الدالة doClassValidation_، إذا كانت أي خاصية فردية غير صالح، يتم تخزين القيمة مؤقتًا في السمة cacheValidatedValue_ قبل عرض null (غير صالح). جارٍ تخزين العنصر مؤقتًا باستخدام الملف الذي تم التحقّق منه بشكل فردي الخصائص إلى doValueInvalid_ للتعامل معها بشكل منفصل، وذلك ببساطة عن طريق إجراء فحص !this.cacheValidatedValue_.property، بدلاً من إعادة التحقق من كل منها كل على حدة.

ويمكن أيضًا استخدام هذا النمط للتحقق من صحة القيم متعددة الأجزاء باللغة local المدقّقين لكن ولا توجد حاليًا طريقة لفرض هذا النمط.

isDirty_

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

النص

→ للحصول على معلومات حول مكان استخدام نص الحقل وكيفية اختلافه من قيمة الحقل، راجع تشريح .

إذا كان نص الحقل مختلفًا عن قيمة الحقل، فيجب إلغاء دالة getText لتقديم النص الصحيح.

getText() {
  let text = this.value_.turtleName + ' wearing a ' + this.value_.hat;
  if (this.value_.hat == 'Stovepipe' || this.value_.hat == 'Propeller') {
    text += ' hat';
  }
  return text;
}

إنشاء محرِّر

إذا قمت بتحديد دالة showEditor_، سيستمع Blockly تلقائيًا إلى من النقرات والاتصال بـ showEditor_ في الوقت المناسب. يمكنك عرض أي جدول HTML في المحرِّر من خلال إحاطته باثنين من عنصري div المميزين، المسماين DropDowndiv وWidgetdiv، الذي يطفو فوق باقي واجهة مستخدم Blockly.

يُستخدَم DropDownDiv لتوفير المحرِّرين الذين يعملون داخل صندوق متصل. إلى حقل. وهو يضع نفسه تلقائيًا بالقرب من الحقل مع البقاء ضمن الحدود المرئية. يعد منتقي الزاوية ومنتقي الألوان أمثلة جيدة على DropDownDiv.

صورة أداة اختيار الزاوية

يتم استخدام WidgetDiv للأغراض التالية: وتوفير محررين لا يعملون داخل صندوق. تستخدم حقول الأرقام دالة Widgetdiv لتغطية الحقل بمربع إدخال نص بتنسيق HTML. أثناء DropDownDiv يتعامل مع تحديد الموضع نيابةً عنك، بينما لا يتعامل Widgetdiv مع ذلك. يجب أن تكون العناصر يدويًا. يوجد نظام الإحداثيات في إحداثيات البكسل بالنسبة إلى أعلى يسار النافذة. يُعد محرر إدخال النص مثالاً جيدًا WidgetDiv

صورة محرِّر إدخال النص

showEditor_() {
  // Create the widget HTML
  this.editor_ = this.dropdownCreate_();
  Blockly.DropDownDiv.getContentDiv().appendChild(this.editor_);

  // Set the dropdown's background colour.
  // This can be used to make it match the colour of the field.
  Blockly.DropDownDiv.setColour('white', 'silver');

  // Show it next to the field. Always pass a dispose function.
  Blockly.DropDownDiv.showPositionedByField(
      this, this.disposeWidget_.bind(this));
}

نموذج رمز Widgetdiv

showEditor_() {
  // Show the div. This automatically closes the dropdown if it is open.
  // Always pass a dispose function.
  Blockly.WidgetDiv.show(
    this, this.sourceBlock_.RTL, this.widgetDispose_.bind(this));

  // Create the widget HTML.
  var widget = this.createWidget_();
  Blockly.WidgetDiv.getDiv().appendChild(widget);
}

التنظيف

يؤدي كل من DropDownDiv ومؤشر Widgetdiv إلى إتلاف رمز HTML المصغّر ولكن تحتاج إلى التخلص يدويًا من أي أدوات استماع للأحداث تطبيقها على هذه العناصر.

widgetDispose_() {
  for (let i = this.editorListeners_.length, listener;
      listener = this.editorListeners_[i]; i--) {
    Blockly.browserEvents.unbind(listener);
    this.editorListeners_.pop();
  }
}

يتم استدعاء الدالة dispose في سياق null على DropDownDiv. مشغَّلة WidgetDiv يتم استدعاؤها في سياق WidgetDiv. في كلتا الحالتين فمن الأفضل استخدام ربط عند تمرير دالة التخلص من البيانات، كما هو موضح في DropDownDiv أعلاه وWidgetDiv من الأمثلة.

→ لمزيد من المعلومات حول التخلص من المحررين، يرجى مراجعة التخلص من المنتج:

تحديث الشاشة عند الحظر

تُستخدَم الدالة render_ لتعديل طريقة عرض الحقل في الكتلة لتتطابق مع وقيمته الداخلية.

وفي ما يلي بعض الأمثلة الشائعة:

  • تغيير النص (قائمة منسدلة)
  • تغيير اللون (اللون)

الإعدادات التلقائية

تضبط الدالة render_ التلقائية نص العرض على نتيجة getDisplayText_ الأخرى. تعرض الدالة getDisplayText_ السمة value_ الخاصة بالحقل. إرسالها إلى سلسلة، بعد أن يتم اقتطاعها لمراعاة الحد الأقصى من النص المنقار.

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

إذا كان سلوك النص التلقائي يعمل مع الحقل الخاص بك، ولكن الحقل محظور تحتوي الشاشة على عناصر ثابتة إضافية، ويمكنك استدعاء القيمة التلقائية للسمة render_ ولكنك ستظل بحاجة إلى تجاوزها لتحديث المقاس.

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

مخطط انسيابي يصف كيفية اتخاذ قرار بشأن تجاهل العرض_

تخصيص العرض

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

يُرجى العلم أنّ جميع التغييرات التي يتم إجراؤها على سمات DOM تعد قانونية، وأهم أمرين عليك مراعاتهما:

  1. يجب معالجة إنشاء DOM أثناء الإعداد، لأنه أكثر كفاءة.
  2. عليك دائمًا تحديث size_ لمطابقة حجم شاشة العرض على الكتلة.
render_() {
  switch(this.value_.hat) {
    case 'Stovepipe':
      this.stovepipe_.style.display = '';
      break;
    case 'Crown':
      this.crown_.style.display = '';
      break;
    case 'Mask':
      this.mask_.style.display = '';
      break;
    case 'Propeller':
      this.propeller_.style.display = '';
      break;
    case 'Fedora':
      this.fedora_.style.display = '';
      break;
  }

  switch(this.value_.pattern) {
    case 'Dots':
      this.shellPattern_.setAttribute('fill', 'url(#polkadots)');
      break;
    case 'Stripes':
      this.shellPattern_.setAttribute('fill', 'url(#stripes)');
      break;
    case 'Hexagons':
      this.shellPattern_.setAttribute('fill', 'url(#hexagons)');
      break;
  }

  this.textContent_.nodeValue = this.value_.turtleName;

  this.updateSize_();
}

جارٍ تعديل الحجم

من المهم جدًا تعديل السمة size_ الخاصة بالحقل، لأنّها تحدّد رمز عرض الكتلة وهو كيفية وضع الحقل. إن أفضل طريقة لمعرفة لما يجب أن تكون عليه size_ عن طريق التجربة.

updateSize_() {
  const bbox = this.movableGroup_.getBBox();
  let width = bbox.width;
  let height = bbox.height;
  if (this.borderRect_) {
    width += this.constants_.FIELD_BORDER_RECT_X_PADDING * 2;
    height += this.constants_.FIELD_BORDER_RECT_X_PADDING * 2;
    this.borderRect_.setAttribute('width', width);
    this.borderRect_.setAttribute('height', height);
  }
  // Note how both the width and the height can be dynamic.
  this.size_.width = width;
  this.size_.height = height;
}

مطابقة ألوان القوالب

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

applyColour() {
  const sourceBlock = this.sourceBlock_;
  if (sourceBlock.isShadow()) {
    this.arrow_.style.fill = sourceBlock.style.colourSecondary;
  } else {
    this.arrow_.style.fill = sourceBlock.style.colourPrimary;
  }
}

جارٍ تعديل إمكانية التعديل

يمكن استخدام الدالة updateEditable لتغيير كيفية ظهور حقلك اعتمادًا على ما إذا كان قابلاً للتعديل أم لا. وتجعل الدالة الافتراضية تحتوي الخلفية على/لا تحتوي على استجابة التمرير (الحدود) إذا كانت/غير قابلة للتعديل. يجب ألا يتغيّر حجم شاشة العرض على الكتلة اعتمادًا على إمكانية تعديلها، ولكن السماح بجميع التغييرات الأخرى.

updateEditable() {
  if (!this.fieldGroup_) {
    // Not initialized yet.
    return;
  }
  super.updateEditable();

  const group = this.getClickTarget_();
  if (!this.isCurrentlyEditable()) {
    group.style.cursor = 'not-allowed';
  } else {
    group.style.cursor = this.CURSOR;
  }
}

التسلسل

يدور التسلسل حول حفظ حالة الحقل بحيث يمكن إعادة تحميله إلى مساحة العمل لاحقًا.

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

إذا كان حقلك قابلاً للتسلسل، يجب ضبط السمة SERIALIZABLE على true

يوفر Blockly مجموعتين من عناصر التسلسل للحقول. زوج واحد من الخطاطيف مع نظام تسلسل JSON الجديد، بينما يعمل الزوج الآخر مع نظام تسلسل XML القديم.

saveState وloadState

saveState وloadState هما عنصر جذب تسلسلي يعمل مع ملف JSON الجديد نظام التسلسل.

في بعض الحالات، لا تحتاج إلى تقديم هذه المعلومات، نظرًا لأن إعداد عمليات التنفيذ. إذا كان (1) حقلك عبارة عن فئة فرعية مباشرة للقاعدة الفئة Blockly.Field، (2) القيمة هي JSON قابل للتسلسل. النوع، و (3) ما عليك سوى تنفيذ ما يلي: أي إنشاء تسلسل للقيمة، فإن التنفيذ الافتراضي سيعمل بشكل جيد!

وبخلاف ذلك، يجب أن تعرض الدالة saveState ملف JSON قابلاً للتسلسل. الكائن/القيمة التي تمثل حالة الحقل. وloadState قبول كائن/قيمة JSON القابلة للتسلسل نفسه، وتطبيقها على في هذا المجال.

saveState() {
  return {
    'country': this.getValue(),  // Value state
    'zoom': this.getZoomLevel(), // UI state
  };
}

loadState(state) {
  this.setValue(state['country']);
  this.setZoomLevel(state['zoom']);
}

التسلسل الكامل والبيانات الاحتياطية

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

في ما يلي حالتا استخدام شائعتان لذلك:

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

أحد الحقول التي تستخدم هذا هو حقل المتغير المضمن. إنه في العادة متسلسلة معرّف المتغيّر الذي يشير إليه، ولكن إذا كانت doFullSerialization صحيحة فهو يسرد كل حالته بشكل تسلسلي.

saveState(doFullSerialization) {
  const state = {'id': this.variable_.getId()};
  if (doFullSerialization) {
    state['name'] = this.variable_.name;
    state['type'] = this.variable_.type;
  }
  return state;
}

loadState(state) {
  const variable = Blockly.Variables.getOrCreateVariablePackage(
      this.getSourceBlock().workspace,
      state['id'],
      state['name'],   // May not exist.
      state['type']);  // May not exist.
  this.setValue(variable.getId());
}

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

toXml وfromXml

toXml وfromXml هما عنصرا جذب تسلسلي يعملان مع ملف XML القديم نظام التسلسل. لا تستخدم عناصر الجذب هذه إلا إذا اضطررت إلى ذلك (مثلاً، كنت تعمل تستخدم قاعدة رموز برمجية قديمة لم يتم نقلها بعد)، وإلا عليك استخدام saveState loadState

يجب أن تعرض الدالة toXml عقدة XML تمثل حالة في هذا المجال. ويجب أن تقبل دالة fromXml عقدة XML نفسها وأن تطبّقها إلى هذا المجال.

toXml(fieldElement) {
  fieldElement.textContent = this.getValue();
  fieldElement.setAttribute('zoom', this.getZoomLevel());
  return fieldElement;
}

fromXml(fieldElement) {
  this.setValue(fieldElement.textContent);
  this.setZoomLevel(fieldElement.getAttribute('zoom'));
}

السمات القابلة للتعديل والقابلة للتسلسل

تحدِّد السمة EDITABLE ما إذا كان يجب أن يحتوي الحقل على واجهة مستخدم للإشارة إلى أنّ التي يمكن التفاعل معها. والإعداد التلقائي هو true.

تحدِّد السمة SERIALIZABLE ما إذا كان يجب إرسال الحقل بشكل تسلسلي. أُنشأها جون هنتر، الذي كان متخصصًا يتم ضبط القيمة التلقائية على false. إذا كانت السمة true، قد تحتاج إلى تقديم دوال التسلسل والإزالة (راجع التسلسل).

تخصيص المؤشر

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