סידור של

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

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

מערכת JSON

הערה: למידע על העברה ל-JSON מ-XML, אפשר לעיין במדריך להעברת נתונים (מיגרציה).

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

שמירה וטעינה

סביבות עבודה

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

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

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

בלוקים בודדים

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

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

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

אפשר לבצע סריאליזציה או לבצע פעולת deserialize של מערכות נפרדות (למשל, חסימות, משתנים, יישומי פלאגין וכו') על ידי יצירה של מפעיל הסדרה המשויך וקריאה לשיטות של 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);

הזמנה של פעולת deserialization

במערכת JSON יש הזמנה מפורשת של פעולת deserialization, שכך קל יותר למנוע כפילות של מצב בשמירה.

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

הסדר של ביצוע פעולת deserialization של מבצעים מובנים בהיבט זה הוא:

1. המשתנים עוברים תהליך deseriality.
2. בלוקים עוברים פעולת deserialize. מקבצים בודדים או בלוקים ברמה העליונה עוברים פעולת deseriality לפי סדר שרירותי.
   1. הסוג עובר deserialized. כך מפעילים את שיטת ההתחלה של הבלוק, שילוב של תוספים וכו'.
   2. המאפיינים עברו deserialized. זה כולל מאפיינים שאפשר להחיל על כל בלוק. לדוגמה: x, y, מכווץ, מושבת, נתונים וכו'.
   3. מצב נוסף עובר deserialize. למידע נוסף, עיינו במסמכי התיעוד בנושא תוספים ומשתנים.
   4. הבלוק מקושר להורה שלו (אם קיים).
   5. הסמלים עוברים תהליך deserialized. סמלים ספציפיים עוברים פעולת deseriality לפי סדר שרירותי.
   6. השדות עוברים אנונימיזציה. שדות נפרדים עוברים פעולת deseriality לפי סדר שרירותי.
   7. בלוקים של קלט עוברים פעולת deserialize. זה כולל בלוקים שמחוברים לקלט של ערכים ולקלט של הצהרות. קלט פרטני עובר פעולת deseriality לפי סדר שרירותי.
   8. הבלוקים הבאים עוברים פעולת deserialize.

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

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

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

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

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

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

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

קטעי הוק (hooks) למגרש

במסמכי התיעוד בנושא Custom fields אפשר לקרוא מידע על יצירת סדרה של שדות.

קטעי הוק (hooks) ליוצר סריאלי

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

בדרך כלל משתמשים בהמשכים נוספים כדי לעדכן את מצב הפלאגין ולבצע פעולת deserialize שלו.

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

בעת רישום של עורך טורי, עליך לספק מספר פרטים:

• שם של מבצע הסדרה, שגם בו נשמרים הנתונים.
• פונקציה שמייצגת save את המצב של הפלאגין/המערכת שמשויכים ל-Serrializer.
• פונקציה שמפעילה 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 יסיר את כל התגובות הקיימות מסביבת העבודה.
2. הפונקציה load שסופקה מופעלת.

מערכת XML

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

הערה: מידע על המעבר ל-JSON זמין במדריך להעברת נתונים (מיגרציה).

ממשקי API

למידע על ממשקי ה-API של מערכת ה-XML, עיינו במסמכי התיעוד.

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

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

קטעי הוק (hooks) למגרש

במסמכי התיעוד בנושא Custom fields אפשר לקרוא מידע על יצירת סדרה של שדות.

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

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

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

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

אם השתמשתם בעבר בסדרה של XML, קראו את מדריך ההעברה למידע על השדרוג.