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

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

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

שדות alt

לכל אובייקט יכול להיות גם שדה alt. אם Blockly לא מזהה את type של האובייקט, במקום זאת נעשה שימוש באובייקט alt. לדוגמה, אם מוסיפים ל-Blockly שדה חדש בשם field_time, בלוקים שמשתמשים בשדה הזה יכולים להשתמש ב-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), האובייקט הזה פשוט מושמט.