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

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

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

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

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

يمكن أيضًا للتطبيقات التي تستخدم تنفيذ JavaScript الأصلي لـ Blockly كتابة حظر التعريفات مباشرةً في استدعاءات دالة Blockly API ذات المستوى الأدنى، المعروضة في أمثلة 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. يتيح ذلك أيضًا المزج بين التنسيقين في صفحات الويب Blockly. من المهم مفضّلاً أن يحدّد الكتلة باستخدام JSON حيثما أمكن ذلك، واستخدِم JavaScript فقط لأجزاء تعريفات الحظر غير المتوافقة مع 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 مُوصلات في تنسيق Blockly القياسي، تحدد هذه الاتصالات في الأعلى والأسفل، مع تكديس الكتل عموديًا.

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

يمكن إجراء اتصالات 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');

حظر الإخراج

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

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 إلى 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) ثم يتم تخطي هذا الكائن ببساطة.

وستتم إضافة إدخال وهمي تلقائيًا إلى نهاية القطعة إذا كانت تنتهي سلسلة 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": وستضيف Blockly تلقائيًا إدخالاً وهميًا للصف الثالث. الإعداد تفرض السياسة implicitAlign0 إلى "RIGHT" محاذاة هذا الصف إلى اليمين. هذا النمط تنطبق المحاذاة على جميع الإدخالات التي لم يتم تحديدها بشكل صريح في ملف JSON حظر التعريف، بما في ذلك إدخالات صف النهاية التي تحل محل أحرف السطر الجديد ('\n') في الرسالة. هناك أيضًا الموقع المتوقّف نهائيًا "lastDummyAlign0" لها نفس سلوك implicitAlign0.

عند تصميم قوالب للنصوص من اليمين إلى اليسار (العربية والعبرية)، يتم عكس الصورة اليمنى واليسرى. وبالتالي، سيعمل "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 factor" تقسيم الرسائل إلى أجزاء متعددة، ولكن القيام بذلك يدويًا أمر سهل ومباشر.

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

تتضمّن JavaScript API طريقة 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');

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

تتضمّن JavaScript API أيضًا طريقة 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

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

appendField

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

JavaScript

input.appendField('hello');

أبسط عنصر حقل هو النص. يتمثّل اصطلاح "بلو Play" في استخدام جميع نص صغير، باستثناء أسماء العلم (مثل Google وSQL).

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

JavaScript

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

يُعد الاستدعاء appendField('hello') في الواقع اختصارًا لاستخدام عنوان URL فاضح طريقة إنشاء 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.

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

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

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

الرموز

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

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

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

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

تلميحات

تقدّم التلميحات مساعدة فورية عندما يمرِّر المستخدم مؤشر الماوس فوق الحظر. في حال كان النص طويلاً، سيتم التفافه تلقائيًا.

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> حيث يمكنك عرض المحتوى
  • ثانيًا، العنصر الفعلي الذي يتم تحريك الماوس فوقه والذي ستعرضه التلميح عن

في نص الدالة، يمكنك عرض أي محتوى تريده في قسم لتحديد سلسلة التلميح على الجزء الذي يتم تمرير الماوس فوقه، يمكنك: الاتصال بـ 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 (نظام التسلسل القديم على icebox)، يتم تخزينه في علامة <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 هي الدالة المطلوب استدعاؤها عند النقر على الخيار.