بنية الكتلة في ملف JSON

في هذا المستند، سنتناول كيفية استخدام JSON لتحديد المدخلات والحقول (بما في ذلك التصنيفات) وعمليات الربط في البلوك. إذا لم تكن على دراية بهذه المصطلحات، يُرجى الاطّلاع على بنية الحظر قبل المتابعة.

يمكنك أيضًا تحديد المدخلات والحقول وعمليات الربط في JavaScript.

نظرة عامة

في JSON، يمكنك وصف بنية أحد المربّعات باستخدام سلسلة واحدة أو أكثر من سلاسل الرسائل (message0 وmessage1 وما إلى ذلك) ومصفوفات الوسيطات المقابلة (args0 وargs1 وما إلى ذلك). تتألف سلاسل الرسائل من نص يتم تحويله إلى تصنيفات، ورموز استيفاء (%1 و%2 وما إلى ذلك) تحدّد مواضع الروابط والحقول غير التصنيفية. توضّح مصفوفات الوسيطات كيفية التعامل مع رموز الاستيفاء.

على سبيل المثال، هذه الكتلة:

يتم تحديدها من خلال JSON التالي:

JSON

{
  "message0": "set %1 to %2",
  "args0": [
    {
      "type": "field_variable",
      "name": "VAR",
      "variable": "item",
      "variableTypes": [""]
    },
    {
      "type": "input_value",
      "name": "VALUE"
    }
  ]
}

يمثّل رمز الاستبدال الأول (%1) حقل متغير (type: "field_variable")، ويتم وصفه بواسطة العنصر الأول في مصفوفة args0. يمثّل الرمز المميّز الثاني (%2) اتصال الإدخال في نهاية إدخال القيمة (type: "input_value"). ويتم وصفه بواسطة العنصر الثاني في الصفيف args0.

الرسائل وأساليب الإدخال

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

مثال 1

JSON

{
  "message0": "set %1 to %2",
  "args0": [
    {"type": "field_variable", ...} // token %1
    {"type": "input_value", ...}    // token %2
  ],
}

يؤدي ذلك إلى إنشاء إدخال بقيمة واحدة مع ثلاثة حقول: تصنيف ("set") وحقل متغير وتصنيف آخر ("to").

مثال 2

JSON

{
  "message0": "%1 + %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_value", ...} // token %2
  ],
}

يؤدي ذلك إلى إنشاء مدخلَين للقيم. لا يحتوي الأول على أي حقول، بينما يحتوي الثاني على حقل واحد ("+").

مثال 3

JSON

{
  "message0": "%1 + %2 %3",
  "args0": [
    {"type": "input_value", ...}   // token %1
    {"type": "input_end_row", ...} // token %2
    {"type": "input_value", ...}   // token %3
  ],
}

يؤدي ذلك إلى إنشاء ما يلي:

• قيمة تم إدخالها بدون حقول
• إدخال نهاية الصف مع حقل تصنيف ("+")، ما يؤدي إلى عرض إدخال القيمة التالي في صف جديد، و
• قيمة تم إدخالها بدون حقول

إدخال وهمي في نهاية الرسالة

إذا انتهى السلسلة message بنص أو حقول، لن تحتاج إلى إضافة رمز مميّز للربط إلى الإدخال الوهمي الذي يحتوي عليها، لأنّ Blockly يضيفه نيابةً عنك. على سبيل المثال، بدلاً من تحديد حظر lists_isEmpty على النحو التالي:

JSON

{
  "message0": "%1 is empty %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_dummy", ...} // token %2
  ],
}

يمكنك السماح لـ Blockly بإضافة الإدخال الوهمي وتحديده على النحو التالي:

JSON

{
  "message0": "%1 is empty",
  "args0": [
    {"type": "input_value", ...} // token %1
  ],
}

تتيح الإضافة التلقائية لإدخال وهمي لاحق للمترجمين تغيير message بدون الحاجة إلى تعديل الوسيطات التي تصف رموز الاستيفاء. لمزيد من المعلومات، يُرجى الاطّلاع على ترتيب الرموز المميزة للاستيفاء.

implicitAlign

في حالات نادرة، يجب محاذاة الإدخال الوهمي الأخير الذي يتم إنشاؤه تلقائيًا مع "RIGHT" أو "CENTRE". القيمة التلقائية في حال عدم تحديدها هي "LEFT".

في المثال أدناه، قيمة message0 هي "send email to %1 subject %2 secure %3" ، ويضيف Blockly تلقائيًا إدخالاً وهميًا للصف الثالث. يؤدي ضبط implicitAlign0 على "RIGHT" إلى محاذاة هذا الصف إلى اليمين.

تنطبق implicitAlign على جميع الإدخالات التي لم يتم تحديدها بشكل صريح في تعريف كتلة JSON، بما في ذلك إدخالات نهاية الصف التي تحل محل أحرف السطر الجديد ('\n'). هناك أيضًا السمة المتوقّفة نهائيًا lastDummyAlign0 التي لها السلوك نفسه مثل implicitAlign0.

عند تصميم مربّعات للغات المكتوبة من اليمين إلى اليسار (مثل العربية والعبرية)، يتم عكس اتجاه اليمين واليسار. وبالتالي، سيؤدي "RIGHT" إلى محاذاة الحقول إلى اليسار.

رسائل متعدّدة

تنقسم بعض الوحدات بشكل طبيعي إلى جزأين أو أكثر. لنفترض أنّ لديك كتلة تكرار تتضمّن صفَّين:

إذا تم وصف هذا المربّع برسالة واحدة، ستكون قيمة السمة message0 هي "repeat %1 times %2 do %3"، حيث يمثّل %2 إدخالاً في نهاية الصف. هذه السلسلة غير ملائمة للمترجم لأنّه من الصعب شرح معنى الاستبدال %2. قد لا يكون إدخال %2 نهاية الصف مطلوبًا أيضًا في بعض اللغات. وقد تكون هناك عدة مربّعات تريد مشاركة نص الصف الثاني. من الأفضل استخدام أكثر من سمة message وargs:

JSON

{
  "message0": "repeat %1 times",
  "args0": [
    {"type": "input_value", ...} // token %1 in message0
  ],
  "message1": "do %1",
  "args1": [
    {"type": "input_statement", ...} // token %1 in message1
  ],
}

يمكن تحديد أي عدد من السمات message وargs وimplicitAlign بتنسيق JSON، بدءًا من 0 وزيادتها بالتسلسل. يُرجى العِلم أنّ Block Factory لا يمكنها تقسيم الرسائل إلى أجزاء متعددة، ولكن يمكنك إجراء ذلك يدويًا بسهولة.

ترتيب الرموز المميزة للاستيفاء

عند ترجمة الكتل، قد تحتاج إلى تغيير ترتيب رموز الاستبدال في الرسالة. ويُعدّ هذا الأمر مهمًا بشكل خاص في اللغات التي يختلف فيها ترتيب الكلمات عن اللغة الإنجليزية. على سبيل المثال، بدأنا بكتلة محدّدة بالرسالة "set %1 to %2":

لنفترض الآن أنّ هناك لغة افتراضية يجب فيها عكس "set %1 to %2" ليصبح "put %2 in %1". سيؤدي تغيير الرسالة (بما في ذلك ترتيب الرموز المميزة الخاصة باستيفاء السلسلة) وترك مصفوفة الوسيطات بدون تغيير إلى ظهور الحظر التالي:

غيّر Blockly تلقائيًا ترتيب الحقول، وأنشأ إدخالاً وهميًا، وبدّل من الإدخالات الخارجية إلى الإدخالات الداخلية.

تسهّل إمكانية تغيير ترتيب رموز الاستبدال في الرسالة عملية الترجمة. لمزيد من المعلومات، يُرجى الاطّلاع على استيفاء رسائل JSON.

معالجة النصوص

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

يستبدل Blockly أيضًا تلقائيًا أي حرف سطر جديد (\n) في سلسلة الرسالة بإدخال نهاية الصف.

JSON

{
  "message0": "set %1\nto %2",
  "args0": [
    {"type": "field_variable", ...}, // token %1
    {"type": "input_value", ...},    // token %2
  ]
}

مصفوفات الوسيطات

يتم إقران كل سلسلة رسائل بمصفوفة args تحتوي على العدد نفسه. على سبيل المثال، message0 يتوافق مع args0. تشير رموز الاستيفاء (%1 و%2 وما إلى ذلك) إلى عناصر مصفوفة args ويجب أن تتطابق تمامًا مع مصفوفة args0، أي بدون تكرار أو حذف. تشير أرقام الرموز المميزة إلى ترتيب العناصر في مصفوفة الوسيطات، ولا يُشترط أن تظهر بالترتيب في سلسلة الرسائل.

يحتوي كل عنصر في مصفوفة الوسيطات على السلسلة type. تختلف بقية المَعلمات حسب النوع:

• الحقول:
  • field_input
  • field_dropdown
  • field_checkbox
  • field_colour
  • field_number
  • field_angle
  • field_variable
  • field_label
  • field_image.
• المدخلات:
  • input_value
  • input_statement
  • input_dummy
  • input_end_row

يمكنك أيضًا تحديد حقول مخصّصة ومدخلات مخصّصة وتمريرها كمعلَمات.

الحقول البديلة

قد يتضمّن كل عنصر أيضًا الحقل alt. في حال عدم تعرّف Blockly على type الخاص بالكائن، يتم استخدام الكائن alt بدلاً منه. على سبيل المثال، إذا تمت إضافة حقل جديد باسم field_time إلى Blockly، يمكن أن تستخدم الوحدات التي تستخدم هذا الحقل alt لتحديد field_input احتياطي للإصدارات القديمة من Blockly:

JSON

{
  "message0": "sound alarm at %1",
  "args0": [
    {
      "type": "field_time",
      "name": "TEMPO",
      "hour": 9,
      "minutes": 0,
      "alt":
        {
          "type": "field_input",
          "name": "TEMPOTEXT",
          "text": "9:00"
        }
    }
  ]
}

قد يحتوي عنصر alt على عنصر alt خاص به، ما يسمح بالتسلسل. في النهاية، إذا لم يتمكّن Blockly من إنشاء عنصر في مصفوفة args0 (بعد محاولة أي عناصر alt)، سيتم تخطّي هذا العنصر ببساطة.