‫JSON وJavaScript

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

استخدام تنسيق JSON أو JavaScript

هذه الكتلة:

عنصر "طول_السلسلة"

يمكن تعريفها في تنسيق JSON أو JavaScript على النحو التالي.

JSON

Blockly.common.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"
}]);

تحوِّل الدالة defineBlocksWithJsonArray كل عنصر JSON إلى كائن تعريف لوحدة باستخدام الدالة init. ويتم تخزين هذه العناصر في Blockly.Blocks.

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');
  }
};

بما أنّ عناصر تعريف الكتل يتم دمجها مع عناصر الكتل، تشير الكلمة الرئيسية this إلى الكتلة الفعلية التي يتم إنشاؤها.

تؤدي كلتا الطريقتَين إلى تخزين عنصر تعريف العنصر في Blockly.Blocks باستخدام مفتاح اسم نوع العنصر (string_length). يحتوي عنصر تعريف العنصر على طريقة واحدة (init) تحدّد شكل العنصر.

دمج تنسيقَي JSON وJavaScript

يُستخدَم تنسيق JSON بشكل أساسي لتحديد مظهر الكتلة وأسلوبها. ولا يمكنه تحديد بعض الميزات مباشرةً، مثل أدوات التحقّق وأدوات التحويل، والتي تتطلّب منك تحديد دالة. لحلّ هذه المشكلة، حدِّد أكبر قدر ممكن من العنصر باستخدام تنسيق JSON، واستخدِم JavaScript للجزء المتبقّي.

ينشئ المثال التالي تعريفًا للوحدة باستخدام الدالة init التي تستخدم jsonInit لتحميل عنصر JSON وواجهة برمجة التطبيقات JavaScript لتحديد tooltip ديناميكي.

JavaScript

// Define the block structure in JSON.
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() {
    // Use jsonInit to load the JSON block structure.
    this.jsonInit(mathChangeJson);

    // Use JavaScript to define a tooltip function.
    // 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'));
    });
  }
};

واجهة برمجة التطبيقات لتعريف المحتوى

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

Blockly.Blocks

‫Blockly.Blocks هو عنصر يخزّن تعريفات الوحدات. مفاتيح هذا الجدول هي أسماء أنواع الكتل، وقيمها هي كائنات تعريف الكتل. استخدِم Blockly.Blocks عند تحديد الكتل باستخدام JavaScript:

Blockly.Blocks['my_block'] = {
  init: function() {/* ... */},
  onchange: function() {/* ... */},
  // ...
}

من الأخطاء الشائعة افتراض أنّ Blockly.Blocks تخزِّن الكتل ومحاولة إجراء ما يلي: لا يمكن تنفيذ هذا الإجراء لأنّ Blockly.Blocks تخزِّن تعريفات العناصر، وليس العناصر نفسها.

// Fails with "Blockly.Blocks.my_block.setColour is not a function".
Blockly.Blocks['my_block'].setColour(150);

defineBlocksWithJsonArray

يقبل defineBlocksWithJsonArray مصفوفة من كائنات JSON، وينشئ تعريفات للكتلة منها، ويضيفها إلى Blockly.Blocks.

Blockly.common.defineBlocksWithJsonArray([
  {
    type: 'my_block1',
    // ...
  }
  {
    type: 'my_block3',
    // ...
  }
  {
    type: 'my_block2',
    // ...
  }
]);

createBlockDefinitionsFromJsonArray وdefineBlocks

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

const myBlockDefinitions = Blockly.common.createBlockDefinitionsFromJsonArray([
  {
    type: 'my_block1',
    // ...
  }
  {
    type: 'my_block3',
    // ...
  }
  {
    type: 'my_block2',
    // ...
  }
]);
Blockly.common.defineBlocks(myBlockDefinitions);

Block.jsonInit

jsonInit يقبل عنصر JSON ويستدعي الطرق المقابلة في Block. على سبيل المثال، يؤدي عنصر JSON الذي يتضمّن زوج المفتاح والقيمة colour: 150 إلى إجراء مكالمة إلى this.setColour(150). استخدِم jsonInit في دالة init لتحميل عنصر JSON.

var myJson = {
  // ...
};

Blockly.Blocks['my_block'] = {
  init: function() {
    this.jsonInit(myJson);
    // The rest of the init function.
  }
};