מבנה הבלוק ב-JSON

במאמר הזה נסביר איך להשתמש ב-JSON כדי להגדיר את הקלט, השדות (כולל תוויות) והחיבורים בבלוק. אם אתם לא מכירים את המונחים האלה, מומלץ לעיין במאמר הסבר על בלוק לפני שתמשיכו.

אפשר גם להגדיר את הקלט, השדות והחיבורים ב-JavaScript.

סקירה כללית

ב-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 להוסיף את קלט ה-placeholder ולהגדיר אותו כך:

JSON

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

ההוספה האוטומטית של קלט פיקטיבי בסוף מאפשרת למתרגמים לשנות את message בלי לשנות את הארגומנטים שמתארים את אסימוני האינטרפולציה. מידע נוסף זמין במאמר בנושא סדר של אסימוני אינטרפולציה.

implicitAlign

במקרים נדירים, צריך ליישר את קלט ה-dummy שנוצר אוטומטית בסוף עם "RIGHT" או "CENTRE". אם לא מציינים ערך, ברירת המחדל היא "LEFT".

בדוגמה שלמטה, message0 הוא "send email to %1 subject %2 secure %3" ו-Blockly מוסיף באופן אוטומטי קלט פיקטיבי לשורה השלישית. הגדרת הערך "RIGHT" ל-implicitAlign0 גורמת ליישור השורה הזו לימין.

‫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.
• Inputs:
  • input_value
  • input_statement
  • input_dummy
  • input_end_row

אפשר גם להגדיר שדות מותאמים אישית וקלט מותאם אישית ולהעביר אותם כארגומנטים.

שדות חלופיים

כל אובייקט יכול להכיל גם את השדה 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), האובייקט פשוט ידלג.