JSON و جاوا اسکریپت

Blockly دو راه برای تعریف بلوک ها دارد: اشیاء JSON که از جفت های کلید-مقدار استفاده می کنند و توابع جاوا اسکریپت که API Blockly را فراخوانی می کنند. فرمت JSON ترجیح داده می شود زیرا بومی سازی را ساده می کند و خواندن و نوشتن آسان تر است. با این حال، نمی توان از آن برای تعریف مستقیم ویژگی های پیشرفته مانند جهش دهنده ها یا اعتبار سنجی ها استفاده کرد. اینها باید در جاوا اسکریپت نوشته شوند، معمولاً به صورت پسوند .

از JSON یا جاوا اسکریپت استفاده کنید

این بلوک:

بلوک «طول_رشته».

را می توان در JSON یا جاوا اسکریپت به صورت زیر تعریف کرد.

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 ذخیره می کند.

جاوا اسکریپت 

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 و جاوا اسکریپت را مخلوط کنید

فرمت JSON در درجه اول از تعریف ظاهر و احساس یک بلوک پشتیبانی می کند. نمی‌تواند مستقیماً برخی از ویژگی‌ها را تعریف کند، مانند اعتباردهنده‌ها و جهش‌دهنده‌ها، که نیاز به تعریف یک تابع دارند. برای حل این مشکل، تا جایی که ممکن است بلاک خود را با JSON تعریف کنید و برای بقیه از جاوا اسکریپت استفاده کنید.

مثال زیر یک تعریف بلوک با یک تابع init ایجاد می کند که jsonInit برای بارگذاری یک شی JSON و API جاوا اسکریپت برای تعریف یک راهنمای ابزار پویا استفاده می کند.

جاوا اسکریپت 

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

Block definition API

این بخش اشیاء و توابع مورد استفاده برای تعریف بلوک های سفارشی را خلاصه می کند.

Blockly.Blocks

Blockly.Blocks یک شی است که تعاریف بلوک را ذخیره می کند. کلیدهای آن نام نوع بلوک و مقادیر آن اشیاء تعریف بلوک هستند. هنگام تعریف بلوک ها با جاوا اسکریپت Blockly.Blocks استفاده کنید:

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.
  }
};