بلوک ها را تعریف کنید

تعاریف بلوک نحوه ظاهر و رفتار یک بلوک را توصیف می کند، از جمله متن، رنگ، شکل و بلوک های دیگری که می تواند به آن متصل شود.

فرمت JSON در مقابل JavaScript API

Blockly دو راه برای تعریف بلوک دارد: اشیاء JSON و توابع جاوا اسکریپت. فرمت JSON برای ساده‌سازی فرآیند بومی‌سازی هنگام توسعه برای زبان‌هایی با ترتیب کلمات مختلف طراحی شده است. فرمت JSON روش ترجیحی برای تعریف بلوک ها است.

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

برنامه‌هایی که از پیاده‌سازی اصلی جاوا اسکریپت Blockly استفاده می‌کنند همچنین می‌توانند تعاریف بلوک را مستقیماً در فراخوانی‌های عملکرد Blockly API سطح پایین‌تر بنویسند، که در مثال‌های مختلف جاوا اسکریپت در زیر نشان داده شده است.

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

جاوا اسکریپت 

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 تعریف کنید و از جاوا اسکریپت فقط برای قسمت هایی از تعریف بلوک استفاده کنید که JSON پشتیبانی نمی کند.

در زیر نمونه ای از بلوکی است که عمدتاً با استفاده از JSON تعریف شده است، اما با استفاده از JavaScript API گسترش یافته است تا یک راهنمای ابزار پویا را ارائه دهد.

جاوا اسکریپت 

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

رنگ بلوک

رنگ اصلی یک بلوک با ویژگی colour JSON، تابع block.setColour(..) یا با استفاده از تم ها و تعریف سبک بلوک تعریف می شود.

JSON 

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

جاوا اسکریپت 

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

برای جزئیات بیشتر به راهنمای رنگ بلوک مراجعه کنید.

ارتباطات بیانیه

کاربران می توانند توالی بلوک ها را با استفاده از اتصال دهنده های nextStatement و previousStatement ایجاد کنند. در طرح استاندارد Blockly، این اتصالات در بالا و پایین هستند و بلوک ها به صورت عمودی روی هم قرار می گیرند.

بلوکی با کانکتور قبلی نمی تواند کانکتور خروجی داشته باشد و بالعکس. عبارت بلوک بیانیه به بلوکی بدون مقدار خروجی اشاره دارد. یک بلوک عبارت معمولاً هم اتصال قبلی و هم اتصال بعدی خواهد داشت.

اتصال nextStatement و previousStatement را می توان تایپ کرد ، اما این ویژگی توسط بلوک های استاندارد استفاده نمی شود.

اتصال بعدی

یک نقطه در پایین بلوک ایجاد می‌کند تا عبارات دیگر در زیر آن قرار گیرند. یک بلوک با اتصال بعدی اما بدون اتصال قبلی معمولاً یک رویداد را نشان می‌دهد و می‌تواند برای رندر کردن با یک کلاه پیکربندی شود.

JSON

بدون تایپ:

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

تایپ شده ( نادر ):

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

جاوا اسکریپت

بدون تایپ:

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

تایپ شده (نادر):

this.setNextStatement(true, 'Action');

اتصال قبلی

یک بریدگی در بالای بلوک ایجاد می کند، به طوری که می توان آن را به عنوان پشته ای از عبارات متصل کرد.

بلوک های دارای اتصال قبلی نمی توانند اتصال خروجی داشته باشند.

JSON

بدون تایپ: 

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

تایپ شده ( نادر ): 

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

جاوا اسکریپت

بدون تایپ: 

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

تایپ شده (نادر): 

this.setPreviousStatement(true, 'Action');

بلوک خروجی

یک بلوک ممکن است یک خروجی داشته باشد که به عنوان یک اتصال دهنده اره منبت کاری اره مویی نر در لبه جلویی نمایش داده می شود. خروجی ها به ورودی های مقدار متصل می شوند. بلوک های دارای خروجی معمولاً بلوک های ارزش نامیده می شوند.

JSON

بدون تایپ: 

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

تایپ شده: 

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

جاوا اسکریپت

بدون تایپ: 

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

تایپ شده: 

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

بلوک های دارای کانکتور خروجی نیز نمی توانند دارای بریدگی عبارت قبلی باشند.

مسدود کردن ورودی ها

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

  • مقدار ورودی : به یک اتصال خروجی یک بلوک مقدار متصل می شود. بلوک math_arithmetic (جمع، تفریق) نمونه ای از بلوک با دو ورودی مقدار است.
  • ورودی بیانیه : به اتصال قبلی یک بلوک بیانیه متصل می شود. بخش تودرتوی یک حلقه while نمونه ای از ورودی دستور است.
  • ورودی ساختگی : اتصال بلوکی ندارد. هنگامی که بلوک برای استفاده از ورودی های مقدار خارجی پیکربندی شده است مانند یک خط جدید عمل می کند.
  • ورودی ردیف انتهایی : اتصال بلوکی ندارد و همیشه مانند یک خط جدید عمل می کند.

همچنین می توانید یک ورودی سفارشی برای پشتیبانی از رندر سفارشی ایجاد کنید.

فرمت JSON و JavaScript API از مدل‌های کمی متفاوت برای توصیف ورودی‌های خود استفاده می‌کنند.

ورودی ها و فیلدها در JSON

بلوک‌های تعریف‌شده JSON به‌عنوان دنباله‌ای از رشته‌های پیام درون‌یابی ( message0 , message1 , ...) ساختار می‌یابند که در آن هر نشانه درون یابی ( %1 ، %2 ، ...) یک فیلد یا یک انتهای ورودی است (بنابراین محل اتصال ورودی است. رندر، درون پیام) در آرایه argsN JSON منطبق است. این قالب برای سهولت بین المللی سازی در نظر گرفته شده است.

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) منجر به بلوک زیر می شود:

Blockly به طور خودکار ترتیب فیلدها را تغییر داد، یک ورودی ساختگی ایجاد کرد و از ورودی خارجی به ورودی داخلی تغییر داد.

Blockly همچنین به طور خودکار هر کاراکتر خط جدید ( \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 دارد.

هنگام طراحی بلوک برای RTL (عربی و عبری)، چپ و راست معکوس می شوند. بنابراین "RIGHT" فیلدها را به سمت چپ تراز می کند.

message1 ، args1 ، implicitAlign1

برخی از بلوک ها به طور طبیعی به دو یا چند قسمت مجزا تقسیم می شوند. این بلوک تکراری را در نظر بگیرید که دارای دو ردیف است:

اگر این بلوک با یک پیام توصیف شود، ویژگی message0 "repeat %1 times %2 do %3" خواهد بود. این رشته برای یک مترجم ناخوشایند است، توضیح اینکه جایگزینی %2 به چه معناست دشوار است. ورودی ساختگی %2 نیز ممکن است در برخی از زبان ها مورد نظر نباشد. و ممکن است چندین بلوک وجود داشته باشد که بخواهند متن ردیف دوم را به اشتراک بگذارند. یک رویکرد بهتر این است که JSON از بیش از یک پیام و خصوصیات args استفاده کند:

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 قادر به تقسیم پیام ها به چند قسمت نیست، اما انجام این کار به صورت دستی ساده است.

ورودی ها و فیلدها در جاوا اسکریپت

API جاوا اسکریپت شامل یک روش append برای هر نوع ورودی است:

جاوا اسکریپت 

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

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

API جاوا اسکریپت همچنین شامل یک روش appendInput عمومی برای الحاق ورودی های سفارشی است. توجه داشته باشید که در این حالت، شناسه باید مستقیماً به سازنده ورودی سفارشی شما ارسال شود.

جاوا اسکریپت 

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

همه متدهای appendInput (اعم از عمومی و غیرعمومی) شی ورودی را برمی‌گردانند تا بتوان با استفاده از روش زنجیره‌ای، پیکربندی بیشتری انجام داد. سه روش داخلی برای پیکربندی ورودی ها استفاده می شود.

setCheck

جاوا اسکریپت 

input.setCheck('Number');

این تابع اختیاری برای بررسی نوع ورودی های متصل استفاده می شود. اگر آرگومان null، پیش فرض داده شود، این ورودی ممکن است به هر بلوکی متصل شود. برای جزئیات بیشتر به بررسی های نوع مراجعه کنید.

setAlign

جاوا اسکریپت 

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 اضافه شد، می‌توانید به صورت اختیاری هر تعداد فیلد را به ورودی اضافه کنید. این فیلدها اغلب به عنوان برچسب برای توصیف اینکه هر ورودی برای چیست استفاده می شود.

جاوا اسکریپت 

input.appendField('hello');

ساده ترین عنصر فیلد متن است. قرارداد Blockly استفاده از تمام متن‌های کوچک، به استثنای نام‌های خاص (مانند Google، SQL) است.

یک ردیف ورودی می تواند حاوی هر تعداد عنصر فیلد باشد. چندین فراخوان appendField ممکن است به هم متصل شوند تا به طور موثر چندین فیلد را به یک ردیف ورودی اضافه کنند.

جاوا اسکریپت 

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

فراخوان appendField('hello') در واقع میانبری برای استفاده از سازنده FieldLabel صریح است: appendField(new Blockly.FieldLabel('hello')) . تنها زمانی که می‌خواهیم از سازنده استفاده کنیم، زمانی است که نام کلاس را مشخص می‌کنیم تا متن با استفاده از یک قانون CSS استایل‌بندی شود.

درون خطی در مقابل خارجی

ورودی های بلوک می توانند به صورت خارجی یا داخلی ارائه شوند.

تعریف بلوک می تواند یک بولی اختیاری را تعیین کند که آیا ورودی ها درون خطی هستند یا نه. اگر false باشد، هر ورودی مقدار خارجی خواهد بود (مانند بلوک سمت چپ). اگر true باشد، هر ورودی مقدار درون خطی خواهد بود (مانند بلوک سمت راست بالا).

JSON 

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

جاوا اسکریپت 

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

اگر تعریف نشده باشد، Blockly از برخی اکتشافی ها برای حدس زدن بهترین حالت استفاده می کند. با فرض اینکه Blockly انتخاب درستی داشته باشد، ترجیح داده می شود که این فیلد تعریف نشده باقی بماند زیرا ترجمه های زبان های مختلف می توانند به طور خودکار حالت های مختلفی داشته باشند. مثال JSON از "set %1 to %2" (ورودی های خارجی) و "put %2 in %1" (ورودی های درون خطی) را در ابتدا در این صفحه ببینید.

از ورودی های درون خطی زمانی استفاده کنید که یک بلوک احتمال دارد ورودی های کوچکی مانند اعداد داشته باشد. اگر پیکربندی collapse فعال باشد، کاربر می‌تواند این گزینه را از طریق منوی زمینه تغییر دهد (اگر جعبه ابزار دارای دسته‌هایی باشد، به طور پیش‌فرض به درستی تبدیل می‌شود).

فیلدها

فیلدها اکثر عناصر UI را در یک بلوک تعریف می کنند. اینها شامل برچسب‌های رشته، تصاویر و ورودی‌های داده‌های تحت اللفظی مانند رشته‌ها و اعداد است. ساده‌ترین مثال بلوک math_number است که از یک field_input استفاده می‌کند تا کاربر بتواند یک عدد را تایپ کند.

فیلدها با استفاده از appendField به بلوک اضافه می شوند.

Blockly تعدادی فیلد داخلی از جمله ورودی متن، انتخابگر رنگ و تصاویر را فراهم می کند. شما همچنین می توانید فیلدهای خود را ایجاد کنید.

→ اطلاعات بیشتر در مورد فیلدهای داخلی .

→ اطلاعات بیشتر در مورد ایجاد زمینه سفارشی .

نمادها

آیکون‌ها عناصر رابط کاربری را روی یک بلوک تعریف می‌کنند که اطلاعات «متا» مربوط به بلوک را نشان می‌دهد.

نمادها با استفاده از addIcon به بلوک اضافه می شوند.

Blockly تعدادی آیکون داخلی از جمله نمادهای نظرات و نمادهای هشدار را ارائه می دهد. شما همچنین می توانید آیکون های خود را ایجاد کنید.

→ اطلاعات بیشتر در مورد ایجاد نمادهای سفارشی .

نکات ابزار

وقتی کاربر ماوس خود را روی بلوک می‌برد، راهنمای ابزار کمک فوری ارائه می‌کند. اگر متن طولانی باشد، به طور خودکار بسته می شود.

JSON 

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

جاوا اسکریپت 

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

در جاوا اسکریپت API، راهنمای ابزار نیز می تواند به عنوان یک تابع به جای رشته ایستا تعریف شود. این امکان کمک پویا را فراهم می کند. برای مثالی از یک راهنمای ابزار که بسته به اینکه کدام گزینه کشویی انتخاب شده است، به math_arithmetic مراجعه کنید.

جاوا اسکریپت 

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

با استفاده از جاوا اسکریپت API، بلوک‌ها می‌توانند به جای یک رشته استاتیک، یک تابع را مشخص کنند، که یک رشته راهنمای ابزار را برمی‌گرداند. این اجازه می دهد تا برای ابزار پویا. برای مثال به math_arithmetic مراجعه کنید.

سفارشی کردن

همچنین می توانید با ارائه یک تابع رندر سفارشی، ظاهر نکات ابزار خود را سفارشی کنید. تابعی ایجاد کنید که دو پارامتر را بپذیرد:

  • ابتدا یک عنصر <div> که در آن محتوا را رندر خواهید کرد
  • دوم، عنصر واقعی که ماوس روی آن قرار می گیرد و راهنمای ابزار آن را نشان خواهید داد

در بدنه تابع، می توانید هر محتوایی را که دوست دارید در div رندر کنید. برای دریافت رشته راهنمای تعریف شده روی بلوکی که ماوس روی آن قرار می گیرد، می توانید Blockly.Tooltip.getTooltipOfObject(element); که در آن element پارامتر دوم بالا است.

در نهایت، این تابع را ثبت کنید تا Blockly بتواند در زمان مناسب آن را فراخوانی کند: 

Blockly.Tooltip.setCustomTooltip(yourFnHere);

برای مثال، به نسخه نمایشی Custom Tooltps مراجعه کنید.

URL راهنما

بلوک ها می توانند یک صفحه راهنما مرتبط با آنها داشته باشند. این با کلیک راست روی بلوک و انتخاب "Help" از منوی زمینه در دسترس کاربران Blockly برای وب است. اگر این مقدار null باشد، منو خاکستری می شود.

JSON 

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

جاوا اسکریپت 

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

با استفاده از API جاوا اسکریپت، بلوک‌ها می‌توانند یک تابع را به جای یک رشته ثابت، که یک رشته URL را برمی‌گرداند، مشخص کنند، بنابراین کمک پویا را ممکن می‌سازد.

شنوندگان و اعتبار سنجی ها را تغییر دهید

بلوک‌ها می‌توانند توابع شنونده تغییری داشته باشند که در هر تغییری در فضای کاری (از جمله موارد غیرمرتبط با بلوک) فراخوانی می‌شوند. اینها عمدتاً برای تنظیم متن هشدار بلوک یا اعلان های مشابه کاربر در خارج از فضای کاری استفاده می شوند.

این تابع با فراخوانی setOnChange با یک تابع اضافه می‌شود و می‌توان آن را در طول init یا از طریق یک افزونه 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.');
    }
  });
});

جاوا اسکریپت 

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

وقتی روی false تنظیم شود، کاربر نمی تواند بلوک را حذف کند. در یک فضای کاری قابل ویرایش، پیش‌فرض قابل حذف را مسدود می‌کند.

هر بلوکی (حتی آنهایی که قابل حذف نیستند) ممکن است به صورت برنامه ریزی شده حذف شوند: 

block.dispose();

حالت قابل ویرایش 

block.setEditable(false);

وقتی روی false تنظیم شود، کاربر نمی‌تواند فیلدهای بلوک را تغییر دهد (مثلاً کرکره‌ها و ورودی‌های متن). بلوک های پیش فرض برای ویرایش در یک فضای کاری قابل ویرایش.

حالت متحرک 

block.setMovable(false);

وقتی روی 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();
  }
});

جاوا اسکریپت 

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

متد destroy پس از حذف والد بلوک، اما قبل از حذف هر یک از فرزندان یا فیلدهای آن فراخوانی می شود.

منوهای زمینه

به‌طور پیش‌فرض، بلوک‌ها دارای منوی زمینه کلیک راست هستند که به کاربران اجازه می‌دهد کارهایی مانند افزودن نظرات یا بلوک‌های تکراری را انجام دهند.

با انجام زیر می توانید منوی زمینه یک بلوک را غیرفعال کنید: 

block.contextMenu = false;

همچنین می توانید گزینه های نشان داده شده در منو را سفارشی کنید. برای سفارشی کردن منو برای همه بلوک ها، به مستندات منوهای زمینه مراجعه کنید. برای سفارشی کردن منو برای یک بلوک جداگانه، می توانید customContextMenu را پیاده سازی کنید. این تابع آرایه‌ای از گزینه‌های منو را می‌گیرد و آن را در جای خود تغییر می‌دهد، به این معنی که هم می‌توانید موارد را اضافه و هم حذف کنید.

هر گزینه منو یک شی با سه ویژگی است:

  • text ، متن نمایش است.
  • enabled یک بولی است. هنگامی که غیرفعال است، این گزینه اما با متن خاکستری نشان داده می شود.
  • callback تابعی است که با کلیک روی گزینه فراخوانی می شود.