שמירה וטעינה

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

ב-Blockly יש שני פורמטים לנתונים האלה: JSON ו-XML. מומלץ להשתמש במערכת JSON בפרויקטים חדשים, ולשדרג פרויקטים ישנים יותר שמשתמשים ב-XML. מערכת ה-XML היא פורמט השמירה הקודם. הוא לא יוסר, אבל לא יתווספו לו תכונות חדשות.

מערכת JSON

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

שמירה וטעינה

סביבות עבודה

אפשר לבצע סריאליזציה או דה-סריאליזציה של המצב של סביבת עבודה שלמה על ידי קריאה לשיטות save ו-load במרחב השמות workspaces.

const state = Blockly.serialization.workspaces.save(myWorkspace);
Blockly.serialization.workspaces.load(state, myWorkspace);

הקריאות האלה מבצעות סריאליזציה או דה-סריאליזציה של כל המערכות הנפרדות (שמיוצגות על ידי סריאליזטורים) שרשומים בסביבת העבודה.

בלוקים נפרדים

אפשר לבצע סריאליזציה או דה-סריאליזציה של בלוקים ספציפיים על ידי קריאה לשיטות save ו-append במרחב השמות blocks.

const blockJson = Blockly.serialization.blocks.save(myBlock);
const duplicateBlock =
    Blockly.serialization.blocks.append(blockJson, myWorkspace);

מערכות נפרדות

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

// Saves only the variables information for the workspace.
const serializer = new Blockly.serialization.variables.VariableSerializer();
const state = serializer.save(myWorkspace);
serializer.load(state, myWorkspace);

סדר ביטול הסריאליזציה

למערכת ה-JSON יש סדר מפורש של ביטול סריאליזציה, שמאפשר למנוע בקלות כפילויות במצב השמירה.

כשמפעילים את Blockly.serialization.workspaces.load, למסנני ה-JSON ניתנת סטטוס לביטול סריאליזציה לפי עדיפות. הסבר נוסף מופיע בקטע סריאליזציה, והמטרה שלו היא לאפשר לסריאליזציה להסתמך על מצב ממערכות אחרות.

הסדר של ביטול הסריאליזציה של סריאליזטורים מובְנים הוא:

  1. מודלים של משתנים עוברים סריאליזציה.
  2. מודלים של פרוצדורות עוברים דה-סריאליזציה.
  3. הבלוקים עוברים סריאליזציה. בלוקים בודדים ברמה העליונה עוברים דה-סריאליזציה בסדר שרירותי.
    1. הסוג עובר סריקה חוזרת (deserialization). הפונקציה הזו יוצרת את הבלוק, מפעילה את שיטת ה-init שלו ומערבבת את התוספים.
    2. המאפיינים עוברים סריאליזציה חוזרת. המאפיינים האלה כוללים מאפיינים שיכולים לחול על כל בלוק. לדוגמה: x,‏ y,‏ collapsed,‏ disabled ו-data.
  4. מצב נוסף עובר סריאליזציה. למידע נוסף, עיינו במסמכי התיעוד של Mutators.
  5. החסימה מחוברת לרכיב ההורה שלה (אם יש כזה).
    1. הסמלים עוברים סריאליזציה. סמלים בודדים עוברים סריאליזציה בסדר שרירותי.
    2. השדות עוברים סריאליזציה לאחור. שדות נפרדים עוברים רסטורציה בסדר שרירותי.
    3. בלוקים של קלט עוברים סריאליזציה. הרשימה הזו כוללת בלוקים שמחוברים לקלטים של ערכים ולקלטים של הצהרות. הקלט היחיד מומר ל-JSON בסדר שרירותי.
    4. הבלוקים הבאים עוברים סריאליזציה.

מתי שומרים מצב נוסף

בבלוק, אם יש משהו שנמצא נמוך יותר בסדר ותלוי במשהו שנמצא גבוה יותר בסדר, צריך להכפיל את הנתונים האלה ולהוסיף אותם למצב הנוסף.

לדוגמה, אם יש לכם שדה שקיים רק אם הבלוק הבא מחובר, עליכם להוסיף מידע על הבלוק הבא למצב הנוסף, כדי שאפשר יהיה להוסיף את השדה לבלוק לפני שהמצב של השדה יתבצע סריאליזציה.

עם זאת, אם יש לכם קלט שקיים רק אם לשדה יש ערך מסוים, אתם לא צריכים להוסיף מידע על השדה למצב הנוסף. הסיבה לכך היא שהמצב של השדה יתבצע קודם, ואז תוכלו להוסיף את הקלט לבלוק. בדרך כלל, הוספת הקלט מופעלת על ידי מאמת.

חשוב לזכור שבכלל לגבי כפילויות של מצב צריך להביא בחשבון שערמות של בלוקים, סמלים, שדות ובלוקים של קלט עוברים סריאליזציה מחדש בסדר שרירותי. לדוגמה, אם יש לכם שדה אחד, B, שקיים רק אם לשדה אחר, A, יש ערך מסוים, עליכם להוסיף מידע על A למצב הנוסף למקרה ש-B עבר סריקה מחדש לפני A.

קטעי הוק (hooks) לחסימה

למידע נוסף על הוספת סריאליזציה נוספת לבלוק, עיינו במאמר בנושא Mutators.

קטעי הוק (hooks) לשדות

מידע נוסף על סריאליזציה של שדות זמין במסמכי העזרה בנושא שדות מותאמים אישית.

קטעי הוק לסריאליזציה

מערכת ה-JSON מאפשרת לרשום סריאליזטורים שמבצעים סריאליזציה ופענוח של מצב מסוים. הסוגריים המובנים של Blockly מטפלים בסריאליזציה של מידע על בלוקים ומשתנים, אבל אם רוצים לסריאליז מידע אחר, צריך להוסיף סוגריים משלכם. לדוגמה, מערכת ה-JSON לא מבצעת שרשור של תגובות ברמת סביבת העבודה כברירת מחדל. אם רוצים לסריאליזציה אותם, צריך לרשום סריאליזטור נוסף.

לרוב משתמשים בסריאליזטורים נוספים כדי לסריאליזציה ולדה-סריאליזציה של המצב של הפלאגין.

Blockly.serialization.registry.register(
    'workspace-comments',  // Name
    {
      save: saveFn,      // Save function
      load: loadFn,      // Load function
      clear: clearFn,    // Clear function
      priority: 10,      // Priority
    });

כשרושמים סריאליזטור, צריך לספק כמה דברים:

  • שם לסריאליזטור, שבו הנתונים נשמרים גם כן.
  • פונקציה לsave המצב של הפלאגין או המערכת שמשויכים לסריאלייזר.
  • פונקציה לclear המצב.
  • פונקציה לload המצב.

  • priority, שמשמשים לקביעת סדר ה-deserialization.

    אפשר להגדיר את העדיפות של הסריאליזטור על סמך העדיפויות המובנות

כשמפעילים את Blockly.serialization.workspaces.save, מתבצעת קריאה לפונקציה save של כל סריאליזטור, והנתונים שלו מתווספים לפלט ה-JSON הסופי:

{
  "blocks": { ... },
  "workspaceComments": [ // Provided by workspace-comments serializer
    {
      "x": 239,
      "y": 31,
      "text": "Add 2 + 2"
    },
    // etc...
  ]
}

כשמפעילים את Blockly.serialization.workspaces.load, כל סריאליזטור מופעל לפי סדר העדיפויות. סריאליזטורים עם ערכי עדיפות חיוביים יותר מופעלים לפני סריאליזטורים עם ערכי עדיפות חיוביים פחות.

כשמפעילים סריאליזטור, קורים שני דברים:

  1. הפונקציה clear שצוינה נקראת. כך מוודאים שהמצב של הפלאגין או המערכת נקי לפני טעינה של מצב נוסף. לדוגמה, הסריאליזטור של workspace-comments יסיר את כל התגובות הקיימות מ-workspace.
  2. הפונקציה load שצוינה נקראת.

מערכת XML

מערכת ה-XML מאפשרת לסדר את סביבת העבודה בצורה רציפה בצומת XML. זו הייתה מערכת הסריאליזציה המקורית של Blockly. הוא הועבר למצב 'הקפאה', כלומר לא יתווספו לו תכונות חדשות. לכן, מומלץ להשתמש במערכת JSON אם אפשר.

ממשקי API

מידע על ממשקי ה-API של מערכת ה-XML זמין במסמכי העזרה.

קטעי הוק (hooks) לחסימה

למידע נוסף על הוספת סריאליזציה נוספת לבלוק, עיינו במאמר בנושא Mutators.

קטעי הוק (hooks) לשדות

מידע נוסף על סריאליזציה של שדות זמין במסמכי העזרה בנושא שדות מותאמים אישית.

בחירה בין JSON ל-XML

אנחנו ממליצים להשתמש בסריאליזציה של JSON במקום ב-XML. מערכת ה-JSON מאפשרת לסריאליזציה של מצב סביבת העבודה באובייקט JavaScript. זה מועיל כי:

  1. קל לדחוס או להמיר קובצי JSON לפורמט אחר.
  2. קל לעבוד עם JSON באופן פרוגרמטי.
  3. קל להרחיב את הנתונים ב-JSON ולהוסיף להם נתונים.

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

אם השתמשתם בעבר בסריאליזציה של XML, תוכלו לקרוא את המדריך להעברת נתונים (מיגרציה) כדי לקבל מידע על השדרוג.