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

تصف تعريفات الكتلة كيف تبدو الكتلة وسلوكها، بما في ذلك النص واللون والشكل والكتل الأخرى التي يمكن أن تتصل بها.

تنسيق JSON مقابل واجهة برمجة تطبيقات JavaScript

هناك طريقتان لتحديد الكتل في المحظورة: كائنات JSON ودوال JavaScript. تم تصميم تنسيق JSON لتبسيط عملية الترجمة عند تطوير اللغات ذات الترتيبات المختلفة للكلمات. تنسيق JSON هو الطريقة المفضلة لتعريف الكتل.

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

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

JSON

Blockly.defineBlocksWithJsonArray([{
  "type": "string_length",
  "message0": 'length of %1',
  "args0": [
    {
      "type": "input_value",
      "name": "VALUE",
      "check": "String"
    }
  ],
  "output": "Number",
  "colour": 160,
  "tooltip": "Returns number of letters in the provided text.",
  "helpUrl": "http://www.w3schools.com/jsref/jsref_length_string.asp"
}]);

JavaScript

Blockly.Blocks['string_length'] = {
  init: function() {
    this.appendValueInput('VALUE')
        .setCheck('String')
        .appendField('length of');
    this.setOutput(true, 'Number');
    this.setColour(160);
    this.setTooltip('Returns number of letters in the provided text.');
    this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');
  }
};

تنشئ الدالة init شكل الكتلة. في سياق هذه الوظيفة، تكون الكلمة الرئيسية this هي الكتلة الفعلية التي يتم إنشاؤها.

يحمّل كلا المثالين مجموعة "string_length" نفسها.

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

في ما يلي مثال على مجموعة يتم تحديدها بشكل أساسي باستخدام JSON، ولكن تم توسيعها باستخدام واجهة برمجة تطبيقات JavaScript لعرض تلميح ديناميكي.

JavaScript

var mathChangeJson = {
  "message0": "change %1 by %2",
  "args0": [
    {"type": "field_variable", "name": "VAR", "variable": "item", "variableTypes": [""]},
    {"type": "input_value", "name": "DELTA", "check": "Number"}
  ],
  "previousStatement": null,
  "nextStatement": null,
  "colour": 230
};

Blockly.Blocks['math_change'] = {
  init: function() {
    this.jsonInit(mathChangeJson);
    // Assign 'this' to a variable for use in the tooltip closure below.
    var thisBlock = this;
    this.setTooltip(function() {
      return 'Add a number to variable "%1".'.replace('%1',
          thisBlock.getFieldValue('VAR'));
    });
  }
};

لون الكتلة

يتم تحديد اللون الأساسي للكتلة من خلال سمة JSON colour، أو وظيفة block.setColour(..)، أو من خلال استخدام المظاهر وتحديد نمط الحظر.

JSON

{
  // ...,
  "colour": 160,
}

JavaScript

init: function() {
  // ...
  this.setColour(160);
}

ويمكنك الاطّلاع على دليل ألوان الكتلة للحصول على مزيد من التفاصيل.

اتصالات العبارات

يمكن للمستخدمين إنشاء تسلسلات من المجموعات باستخدام موصِّلَي nextStatement وpreviousStatement. في تخطيط Bluely، تكون هذه الاتصالات في الجزء العلوي والسفلي، مع الكتل المكدسة عموديًا.

ولا يمكن أن تحتوي الوحدة التي تشتمل على موصل سابق على موصل إخراج، والعكس صحيح. يشير مصطلح مجموعة عبارات إلى مجموعة بدون ناتج قيمة. ستحتوي كتلة العبارة عادةً على اتصال سابق واتصال تالٍ.

ويمكن كتابة وصلات nextStatement وpreviousStatement، إلا أنّ هذه الميزة لا تُستخدم من خلال الوحدات الأساسية القياسية.

عملية الربط التالية

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

JSON

غير مكتوب:

{
  ...,
  "nextStatement": null,
}

مكتوب (نادر):

{
  "nextStatement": "Action",
  ...
}

JavaScript

غير مكتوب:

this.setNextStatement(true);  // false implies no next connector, the default

مكتوب (نادر):

this.setNextStatement(true, 'Action');

عملية الربط السابقة

تنشئ شقًا في أعلى القطعة، بحيث يمكن ربطها كحزمة من العبارات.

لا يمكن إجراء اتصال ناتج عن الحظر باستخدام اتصال سابق.

JSON

غير مكتوب:

{
  ...,
  "previousStatement": null,
}

مكتوب (نادر):

{
  "previousStatement": "Action",
  ...
}

JavaScript

غير مكتوب:

this.setPreviousStatement(true);  // false implies no previous connector, the default

مكتوب (نادر):

this.setPreviousStatement(true, 'Action');

حظر الإخراج

قد يكون للقطعة مخرج واحد، يتم تمثيله على شكل موصل jigsaw (وصلة) ذكر على الحافة الرائدة. ترتبط المخرجات بمدخلات القيمة. عادة ما يُطلق على الكتل التي لها مخرجات اسم كتل القيمة.

JSON

غير مكتوب:

{
  // ...,
  "output": null,
}

الكتابة:

{
  // ...,
  "output": "Number",
}

JavaScript

غير مكتوب:

init: function() {
  // ...
  this.setOutput(true);
}

الكتابة:

init: function() {
  // ...
  this.setOutput(true, 'Number');
}

لا يمكن أن تحتوي القوالب التي بها موصل إخراج على درجة سابقة أيضًا.

حظر الإدخالات

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

  • إدخال القيمة: يؤدي هذا الخيار إلى الاتصال باتصال ناتج لكتلة قيمة. كتلة math_arithmetic (الجمع والطرح) هي مثال على كتلة مع إدخالَين للقيمة.
  • إدخال عبارة: يؤدي هذا الخيار إلى الاتصال باتصال سابق ضمن مجموعة عبارات. القسم المتداخل من التكرار الحلقي while هو مثال على إدخال عبارة.
  • الإدخال الوهمي: لا يتوفّر اتصال محدود. يعمل كسطر جديد عندما يتم ضبط الكتلة لاستخدام مدخلات القيمة الخارجية.
  • إدخال صف النهاية: ليس به اتصال محظور، ويعمل دائمًا كخط جديد.

يمكنك أيضًا إنشاء إدخال مخصّص لتوفير العرض المخصّص.

يستخدم تنسيق JSON وواجهة برمجة تطبيقات JavaScript نماذج مختلفة قليلاً لوصف إدخالاتهما.

الإدخالات والحقول بتنسيق JSON

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

JSON

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

يجب أن تتطابق الرموز المميّزة للاستيفاء مع مصفوفة args0 تمامًا: ما مِن تكرارات أو عمليات حذف. يمكن العثور على الرموز المميزة بأي ترتيب، ما يسمح للغات مختلفة بتغيير تنسيق الكتلة.

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

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

تم بشكل حظري تغيير ترتيب الحقول تلقائيًا وإنشاء إدخال وهمي والتبديل من مدخلات خارجية إلى داخلية.

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

JSON

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

أقواس

يتم إقران كل سلسلة رسالة بمصفوفة args لها الرقم نفسه. على سبيل المثال، يتم استخدام message0 مع args0. تشير الرموز المميّزة للاستيفاء (%1، %2، ...) إلى عناصر مصفوفة args. ويحتوي كل كائن على سلسلة type. وتختلف باقي المعلمات حسب النوع:

يمكنك أيضًا تحديد الحقول المخصّصة والإدخالات المخصّصة وضبطها كوسيطات.

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

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 خاص به، ما يسمح بالتسلسل. في نهاية الأمر، إذا لم يتمكن حظر كائن في صفيف args0 (بعد محاولة أي كائنات alt)، يتم تخطي ذلك الكائن.

وستتم تلقائيًا إضافة إدخال وهمي إلى نهاية المجموعة إذا كانت سلسلة message تنتهي بنص أو حقول لا يتضمّنها أي إدخال. وبالتالي، إذا كان الإدخال الأخير في الكتلة هو إدخال وهمي، قد يتم حذفه من الصفيف args ولن يحتاج إلى الاستيفاء في message. إنّ الإضافة التلقائية لإدخال وهمي مخصص للترجمات تسمح للمترجمين بتغيير message بدون الحاجة إلى تعديل بقية ملفات JSON. يمكنك الاطّلاع على مثال "set %1 to %2" (بدون إدخال وهمي) و"put %2 in %1" (تمت إضافة إدخال وهمي) في وقت سابق من هذه الصفحة.

implicitAlign0

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

في المثال أدناه، تكون القيمة message0 هي "send email to %1 subject %2 secure %3"، وتضيف بشكل تلقائي مدخلاً وهميًا إلى الصف الثالث. يؤدي ضبط implicitAlign0 على "RIGHT" إلى فرض محاذاة هذا الصف إلى اليمين. وتنطبق هذه المحاذاة على جميع الإدخالات التي لم يتم تحديدها صراحةً في تعريف كتلة JSON، بما في ذلك مدخلات صف النهاية التي تحل محل أحرف السطر الجديد ('\n') في الرسالة. هناك أيضًا السمة lastDummyAlign0 التي تم إيقافها نهائيًا والتي تتّبع سلوك implicitAlign0 نفسه.

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

message1 وargs1 وimplicitAlign1

تنقسم بعض القوالب بشكل طبيعي إلى جزءين منفصلين أو أكثر. ضع في الاعتبار هذا الجزء المتكرر الذي يتضمن صفين:

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

JSON

{
  "type": "controls_repeat_ext",
  "message0": "repeat %1 times",
  "args0": [
    {"type": "input_value", "name": "TIMES", "check": "Number"}
  ],
  "message1": "do %1",
  "args1": [
    {"type": "input_statement", "name": "DO"}
  ],
  "previousStatement": null,
  "nextStatement": null,
  "colour": 120
}

يمكن تحديد أي عدد من سمات message وargs وimplicitAlign بتنسيق JSON، بدءًا من 0 ثم زيادة الأعداد بشكل تسلسلي. يُرجى ملاحظة أن Block factory غير قادر على تقسيم الرسائل إلى أجزاء متعدّدة، ولكن القيام بذلك يدويًا أمر بسيط.

الإدخالات والحقول في JavaScript

تتضمن واجهة برمجة تطبيقات JavaScript طريقة append لكل نوع إدخال:

JavaScript

this.appendEndRowInput()
    .appendField('for each')
    .appendField('item')
    .appendField(new Blockly.FieldVariable());
this.appendValueInput('LIST')
    .setCheck('Array')
    .setAlign(Blockly.inputs.Align.RIGHT)
    .appendField('in list');
this.appendStatementInput('DO')
    .appendField('do');
this.appendDummyInput()
    .appendField('end');

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

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

JavaScript

this.appendInput(new MyCustomInput('INPUT_NAME'))
    .appendField('an example label')

تعرض كل طرق appendInput (العامة وغير العامة) كائن الإدخال حتى يمكن ضبطها بشكل أكبر باستخدام تسلسل الطرق. هناك ثلاث طرق مدمجة تستخدم لتهيئة الإدخالات.

setCheck

JavaScript

input.setCheck('Number');

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

setAlign

JavaScript

input.setAlign(Blockly.inputs.Align.RIGHT);

وتُستخدم هذه الدالة الاختيارية لمحاذاة الحقول (انظر أدناه). هناك ثلاث قيم وصفية ذاتية يمكن تمريرها كوسيطة إلى هذه الدالة: Blockly.inputs.Align.LEFT وBlockly.inputs.Align.RIGHT و Blockly.inputs.Align.CENTER.

عند تصميم القوالب من أجل RTL (العربية والعبرية)، يتم عكس اتجاهها إلى اليمين واليسار. وبالتالي، سيؤدي الترميز Blockly.inputs.Align.RIGHT إلى محاذاة الحقول إلى اليسار.

appendField

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

JavaScript

input.appendField('hello');

أبسط عنصر حقل هو النص. اصطلاح Bluely هو استخدام النص الكامل باستثناء أسماء العلم (مثل Google وSQL).

يمكن أن يحتوي صف الإدخال على أي عدد من عناصر الحقول. يمكن ربط طلبات appendField المتعددة معًا لإضافة عدة حقول بكفاءة إلى صف الإدخال نفسه.

JavaScript

input.appendField('hello')
     .appendField(new Blockly.FieldLabel('Neil', 'person'));

استدعاء appendField('hello') هو في الواقع اختصار لاستخدام دالة إنشاء FieldLabel صريحة: appendField(new Blockly.FieldLabel('hello')). المرة الوحيدة التي قد ترغب فيها في استخدام الدالة الإنشائية هي عند تحديد اسم فئة بحيث يمكن تصميم النص باستخدام قاعدة CSS.

مضمّنة في مقابل خارجية

يمكن عرض إدخالات سياسة الحظر على أنّها خارجية أو داخلية.

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

JSON

{
  // ...,
  "inputsInline": true
}

JavaScript

init: function() {
  // ...
  this.setInputsInline(true);
}

إذا لم يتم تعريفه، فسيستخدم تطبيقBlockly بعض الأساليب لتخمين الوضع الأفضل. إذا افترضنا أنّ تطبيقBlockly هو الخيار الصحيح، من المفضّل ترك هذا الحقل بدون تحديد، لأنّ الترجمة بلغات مختلفة يمكن أن تتضمّن أوضاعًا مختلفة تلقائيًا. يمكنك الاطّلاع في وقت سابق على مثال JSON عن "set %1 to %2" (الإدخالات الخارجية) و"put %2 in %1" (الإدخالات المضمَّنة) في هذه الصفحة.

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

الحقول

تحدد الحقول معظم عناصر واجهة المستخدم في كتلة واحدة. ويشمل ذلك تسميات السلاسل والصور وإدخالات البيانات الحرفية مثل السلاسل والأرقام. وأبسط مثال هو كتلة math_number التي تستخدم field_input للسماح للمستخدم بكتابة رقم.

يتم إلحاق الحقول بالكتلة باستخدام appendField.

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

→ مزيد من المعلومات حول الحقول المضمّنة.

→ مزيد من المعلومات حول إنشاء حقل مُخصص.

الرموز

تحدد الأيقونات عناصر واجهة المستخدم على الكتلة التي تعرض معلومات "meta" حول الكتلة.

يتم إلحاق الرموز بالكتلة باستخدام addIcon.

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

← مزيد من المعلومات حول إنشاء الرموز المخصّصة.

تلميحات

تقدم التلميحات مساعدة فورية عندما يمرر المستخدم الماوس فوق القطعة. إذا كان النص طويلاً، سيتم التفاف النص تلقائيًا.

JSON

{
  // ...,
  "tooltip": "Tooltip text."
}

JavaScript

init: function() {
  this.setTooltip("Tooltip text.");
}

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

JavaScript

Blockly.Blocks['math_arithmetic'] = {
  init: function() {
    // ...

    // Assign 'this' to a variable for use in the tooltip closure below.
    var thisBlock = this;
    this.setTooltip(function() {
      var mode = thisBlock.getFieldValue('OP');
      var TOOLTIPS = {
        'ADD': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_ADD,
        'MINUS': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_MINUS,
        'MULTIPLY': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_MULTIPLY,
        'DIVIDE': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_DIVIDE,
        'POWER': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_POWER
      };
      return TOOLTIPS[mode];
    });
  }
};

باستخدام واجهة برمجة تطبيقات JavaScript، يمكن أن تحدد المجموعات دالة، بدلاً من سلسلة ثابتة، تعرض سلسلة التلميح. ويسمح ذلك بعرض التلميحات الديناميكية. يمكنك مراجعة math_arithmetic للاطّلاع على مثال.

تخصيص

يمكنك أيضًا تخصيص مظهر التلميحات من خلال توفير وظيفة عرض مخصصة. أنشئ دالة تقبل معلمتين:

  • أولاً، عنصر <div> حيث تعرض المحتوى
  • وثانيًا، العنصر الفعلي الذي يتم تحريكه فوقه والذي سيظهر تلميحًا

في نص الدالة، يمكنك عرض أي محتوى تريده في div. للحصول على سلسلة التلميح المحدَّدة بشأن الكتلة التي يتم تمرير الماوس فوقها، يمكنك استدعاء Blockly.Tooltip.getTooltipOfObject(element); حيث element هي المعلمة الثانية أعلاه.

أخيرًا، سجّل هذه الدالة حتى يتمكن تطبيق Blockly من استدعائها في الوقت المناسب:

Blockly.Tooltip.setCustomTooltip(yourFnHere);

للحصول على مثال، اطّلِع على العرض التوضيحي لنصائح الأدوات المخصّصة.

عنوان URL للمساعدة

يمكن أن ترتبط عمليات الحظر بصفحة مساعدة. وهو متاح لمستخدمي Blockly for Web من خلال النقر بزر الماوس الأيمن على الحظر واختيار "مساعدة" من قائمة السياق. إذا كانت هذه القيمة هي null، ستظهر القائمة باللون الرمادي.

JSON

{
  // ...,
  "helpUrl": "https://en.wikipedia.org/wiki/For_loop"
}

JavaScript

init: function() {
  // ...
  this.setHelpUrl('https://en.wikipedia.org/wiki/For_loop');
}

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

تغيير المستمعين وأدوات التحقّق من الصحة

يمكن أن تؤدي الكتل إلى تغيير دوال المستمعين التي تستدعي أي تغيير في مساحة العمل (بما في ذلك المهام غير المرتبطة بالمجموعة). تُستخدَم هذه الإشعارات في المقام الأول لضبط نص التحذير الخاص بالمجموعة أو إشعارات المستخدمين المشابهة خارج مساحة العمل.

وتتم إضافة هذه الدالة عن طريق استدعاء setOnChange باستخدام إحدى الدوالّ ويمكن تنفيذها أثناء إنشائها أو عبر إضافة JSON إذا كنت تنوي استخدامها على كلّ الأنظمة الأساسية.

JSON

{
  // ...,
  "extensions":["warning_on_change"],
}

Blockly.Extensions.register('warning_on_change', function() {
  // Example validation upon block change:
  this.setOnChange(function(changeEvent) {
    if (this.getInput('NUM').connection.targetBlock()) {
      this.setWarningText(null);
    } else {
      this.setWarningText('Must have an input block.');
    }
  });
});

JavaScript

Blockly.Blocks['block_type'] = {
  init: function() {
    // Example validation upon block change:
    this.setOnChange(function(changeEvent) {
      if (this.getInput('NUM').connection.targetBlock()) {
        this.setWarningText(null);
      } else {
        this.setWarningText('Must have an input block.');
      }
    });
  }
}

يستدعي النظام الدالة ويمرر حدث التغيير. داخل الدالة، يشير this إلى مثيل الكتلة.

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

يمكنك الاطّلاع على عناصر حظر controls_flow_statements وlogic_compare وprocedures_ifreturn للحصول على أمثلة.

وتجدُر الإشارة إلى أنّ الحقول القابلة للتعديل تحتوي على أدوات معالجة أحداث خاصة بها للتحقّق من صحة الإدخال وإحداث آثار جانبية.

أداة تبديل

تسمح المغيرات للكتل المتقدمة بتغيير الشكل، لا سيما عندما يفتح المستخدمون مربّع حوار لإضافة مكونات أو إزالتها أو إعادة ترتيبها. ويمكن إضافة أدوات التغيُّر من خلال JSON باستخدام مفتاح mutator.

JSON

{
  // ...,
  "mutator":"if_else_mutator"
}

الإعدادات لكل قسم

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

حالة قابلة للحذف

block.setDeletable(false);

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

قد يتم حذف أي كتلة (حتى تلك غير القابلة للإلغاء) آليًا:

block.dispose();

حالة قابلة للتعديل

block.setEditable(false);

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

الحالة القابلة للنقل

block.setMovable(false);

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

يمكن نقل أي قطعة (حتى تلك غير القابلة للنقل) آليًا بعد توفُّرها على مساحة العمل.

block.moveBy(dx, dy)

يكون موضع البداية للكتلة في مساحة عمل هو القيمة التلقائية (0، 0).

حظر البيانات

this.data = '16dcb3a4-bd39-11e4-8dfc-aa07a5b093db';

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

غالبًا ما يستخدم هذا لربط كتلة بمورد خارجي.

عند التسلسل بتنسيق JSON، يتم تخزين البيانات كخاصية من المستوى الأعلى في المجموعة:

{
  "type": "my_block",
  "data": "16dcb3a4-bd39-11e4-8dfc-aa07a5b093db",
  // etc..
}

عند إنشاء سلسلة البيانات بتنسيق XML (نظام التسلسل القديم المعبّأ بغلاف ثلجي)، يتم تخزين سلسلة البيانات في علامة <data></data> ضمن المجموعة:

<block type="my_block">
  <data>16dcb3a4-bd39-11e4-8dfc-aa07a5b093db</data>
  <!-- etc... -->
</block>

تدمير

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

JSON

{
  // ...,
  "extensions":["destroy"],
}

Blockly.Extensions.registerMixin('destroy', {
  destroy: function() {
    this.myResource.dispose();
  }
});

JavaScript

Blockly.Blocks['block_type'] = {
  destroy: function() {
    this.myResource.dispose();
  }
}

يتم استدعاء طريقة destroy بعد التخلص من العنصر الرئيسي للكتلة، ولكن قبل التخلص من أي من عناصرها الثانوية أو حقولها.

قوائم السياقات

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

يمكنك إيقاف قائمة السياقات لحزمة فردية من خلال تنفيذ ما يلي:

block.contextMenu = false;

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

يمثل كل خيار قائمة كائنًا له ثلاث خصائص:

  • text هو النص المعروض.
  • enabled قيمة منطقية. عند الإيقاف، يظهر الخيار ولكن مع نص رمادي.
  • callback هي الدالة التي سيتم طلبها عند النقر على الخيار.