ساختار بلوک در JSON

در این سند، نحوه استفاده از JSON برای تعریف ورودی‌ها، فیلدها (از جمله برچسب‌ها) و اتصالات در بلوک را مورد بحث قرار خواهیم داد. اگر با این اصطلاحات آشنا نیستید، قبل از ادامه به Anatomy of a block مراجعه کنید.

همچنین می توانید ورودی ها، فیلدها و اتصالات خود را در جاوا اسکریپت تعریف کنید.

نمای کلی

در JSON، ساختار یک بلوک را با یک یا چند رشته پیام ( message0 , message1 , ...) و آرایه های آرگومان مربوطه آنها ( args0 ، args1 ، ...) توصیف می کنید. رشته های پیام شامل متنی است که به برچسب تبدیل می شود و نشانه های درون یابی ( %1 , %2 , ...) که محل اتصالات و فیلدهای غیر برچسب را مشخص می کنند. آرایه های آرگومان نحوه مدیریت توکن های درون یابی را توضیح می دهند.

به عنوان مثال، این بلوک:

توسط JSON زیر تعریف می شود:

JSON

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

اولین نشانه درون یابی ( %1 ) یک فیلد متغیر را نشان می دهد ( type: "field_variable" ). با اولین شی در آرایه args0 توصیف می شود. نشانه دوم ( %2 ) نشان دهنده اتصال ورودی در انتهای یک مقدار ورودی است ( type: "input_value" ). توسط شی دوم در آرایه args0 توصیف می شود.

پیام ها و ورودی ها

هنگامی که یک توکن درون یابی یک اتصال را علامت گذاری می کند، در واقع انتهای ورودی حاوی اتصال را علامت گذاری می کند. این به این دلیل است که اتصالات در ورودی های مقدار و بیانیه در انتهای ورودی ارائه می شوند. ورودی شامل تمام فیلدها (از جمله برچسب ها) بعد از ورودی قبلی و حداکثر تا نشانه فعلی است. بخش های زیر نمونه پیام ها و ورودی هایی که از آنها ایجاد می شود را نشان می دهد.

مثال 1

JSON

{
  "message0": "set %1 to %2",
  "args0": [
    {"type": "field_variable", ...} // token %1
    {"type": "input_value", ...}    // token %2
  ],
}

این یک ورودی مقدار واحد با سه فیلد ایجاد می کند: یک برچسب ( "set" )، یک فیلد متغیر و یک برچسب دیگر ( "to" ).

مثال 2

JSON

{
  "message0": "%1 + %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_value", ...} // token %2
  ],
}

این دو ورودی مقدار ایجاد می کند. اولی هیچ فیلدی ندارد و دومی یک فیلد ( "+" ) دارد.

مثال 3

JSON

{
  "message0": "%1 + %2 %3",
  "args0": [
    {"type": "input_value", ...}   // token %1
    {"type": "input_end_row", ...} // token %2
    {"type": "input_value", ...}   // token %3
  ],
}

این ایجاد می کند:

• یک مقدار ورودی بدون فیلد،
• یک ورودی انتهای ردیف با یک فیلد برچسب ( "+" )، که باعث می شود ورودی مقدار زیر در یک ردیف جدید ارائه شود، و
• یک مقدار ورودی بدون فیلد.

ورودی ساختگی در انتهای پیام

اگر رشته message شما به متن یا فیلد ختم می‌شود، نیازی به اضافه کردن نشانه درون یابی برای ورودی ساختگی که حاوی آنهاست نیست - Blockly آن را برای شما اضافه می‌کند. به عنوان مثال، به جای تعریف یک بلوک lists_isEmpty مانند این:

JSON

{
  "message0": "%1 is empty %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_dummy", ...} // token %2
  ],
}

می توانید به Blockly اجازه دهید ورودی ساختگی را اضافه کرده و آن را به این صورت تعریف کنید:

JSON

{
  "message0": "%1 is empty",
  "args0": [
    {"type": "input_value", ...} // token %1
  ],
}

افزودن خودکار ورودی ساختگی باطله به مترجمان اجازه می‌دهد message بدون نیاز به اصلاح آرگومان‌هایی که نشانه‌های درونیابی را توصیف می‌کنند، تغییر دهند. برای اطلاعات بیشتر، ترتیب توکن درون یابی را ببینید.

implicitAlign

در موارد نادر، ورودی ساختگی دنباله دار ایجاد شده به طور خودکار باید با "RIGHT" یا "CENTRE" تراز شود. پیش‌فرض اگر مشخص نشده باشد "LEFT" است.

در مثال زیر message0 "send email to %1 subject %2 secure %3" است و Blockly به طور خودکار یک ورودی ساختگی برای ردیف سوم اضافه می کند. تنظیم implicitAlign0 روی "RIGHT" این سطر را مجبور می‌کند تا به راست تراز شود.

implicitAlign برای همه ورودی‌هایی اعمال می‌شود که به صراحت در تعریف بلوک JSON تعریف نشده‌اند، از جمله ورودی‌های انتهای ردیف که جایگزین نویسه‌های خط جدید ( '\n' ) می‌شوند . همچنین ویژگی منسوخ شده lastDummyAlign0 وجود دارد که رفتاری مشابه با implicitAlign0 دارد.

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

پیام های متعدد

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

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

JSON

{
  "message0": "repeat %1 times",
  "args0": [
    {"type": "input_value", ...} // token %1 in message0
  ],
  "message1": "do %1",
  "args1": [
    {"type": "input_statement", ...} // token %1 in message1
  ],
}

هر تعداد message ، args و خصوصیات implicitAlign ممکن است در قالب JSON تعریف شوند که با 0 شروع می شود و به ترتیب افزایش می یابد. توجه داشته باشید که Block Factory قادر به تقسیم پیام ها به چند قسمت نیست، اما انجام این کار به صورت دستی ساده است.

ترتیب توکن درون یابی

هنگام بومی سازی بلوک ها، ممکن است لازم باشد ترتیب توکن های درونیابی را در یک پیام تغییر دهید. این امر به ویژه در زبان هایی که ترتیب کلمات متفاوت از انگلیسی دارند بسیار مهم است. به عنوان مثال، ما با یک بلوک که با پیام "set %1 to %2" تعریف شده است، شروع کردیم:

اکنون یک زبان فرضی را در نظر بگیرید که در آن "set %1 to %2" باید معکوس شود تا بگوییم "put %2 in %1" . تغییر پیام (شامل ترتیب نشانه های درونیابی) و بدون تغییر آرایه آرگومان ها در بلوک زیر نتیجه می شود:

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

امکان تغییر ترتیب نشانه های درونیابی در یک پیام، بومی سازی را آسان تر می کند. برای اطلاعات بیشتر، درونیابی پیام JSON را ببینید.

مدیریت متن

متن در دو طرف یک نشانه درون یابی با فضای خالی بریده شده است. متنی که از کاراکتر % استفاده می کند (مثلاً هنگام اشاره به درصد) باید از %% استفاده کند تا به عنوان یک نشانه درونیابی تفسیر نشود.

Blockly همچنین به طور خودکار هر کاراکتر خط جدید ( \n ) در رشته پیام را با ورودی انتهای ردیف جایگزین می کند.

JSON

{
  "message0": "set %1\nto %2",
  "args0": [
    {"type": "field_variable", ...}, // token %1
    {"type": "input_value", ...},    // token %2
  ]
}

آرایه های آرگومان ها

هر رشته پیام با یک آرایه args به همان تعداد جفت می شود. به عنوان مثال، message0 با args0 می آید. نشانه های درون یابی ( %1 , %2 , ...) به آیتم های آرایه args اشاره دارند و باید کاملاً با آرایه args0 مطابقت داشته باشند: بدون تکرار، بدون حذف. اعداد رمز به ترتیب آیتم ها در آرایه آرگومان ها اشاره دارد. لازم نیست آنها به ترتیب در یک رشته پیام وجود داشته باشند.

هر شی در آرایه آرگومان ها دارای یک type رشته است. بقیه پارامترها بسته به نوع متفاوت است:

• زمینه ها :
  • field_input
  • field_dropdown
  • field_checkbox
  • field_colour
  • field_number
  • field_angle
  • field_variable
  • field_label
  • field_image .
• ورودی ها :
  • input_value
  • input_statement
  • input_dummy
  • input_end_row

شما همچنین می توانید فیلدهای سفارشی و ورودی های سفارشی خود را تعریف کرده و آنها را به عنوان آرگ ارسال کنید.

فیلدهای alt

هر شی ممکن است یک فیلد 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 )، آن شی به سادگی نادیده گرفته می شود.