سریال سازی

سریال‌سازی وضعیت فضای کاری شما را ذخیره می‌کند تا بتواند بعداً دوباره در فضای کاری بارگیری شود. این شامل سریال کردن وضعیت هر بلوک، متغیر یا افزونه ای است که می خواهید ذخیره کنید. می‌توانید تمام داده‌هایی را که برای ذخیره‌سازی نیاز دارید به یک فرمت مبتنی بر متن تبدیل کنید تا ذخیره‌سازی آسان شود و سپس آن داده‌ها را بعداً در یک فضای کاری کاملاً کاربردی بارگیری کنید.

Blockly دو فرمت برای این داده ها ارائه می دهد: JSON و XML. توصیه می کنیم از سیستم JSON برای پروژه های جدید استفاده کنید و پروژه های قدیمی تر را با استفاده از XML برای ارتقا تشویق کنید. سیستم XML فرمت ذخیره قدیمی است. حذف نخواهد شد، اما ویژگی های جدیدی دریافت نخواهد کرد.

سیستم JSON

سیستم سریال سازی JSON از چندین سریال ساز تشکیل شده است. سریال‌سازهای داخلی برای بلوک‌ها و متغیرها وجود دارد، و همچنین می‌توانید سریال‌سازهای اضافی را ثبت کنید. هر سریال‌ساز مسئول سریال‌سازی و سریال‌زدایی وضعیت یک پلاگین یا سیستم خاص است.

ذخیره و بارگذاری

فضاهای کاری

می‌توانید با فراخوانی روش‌های 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);

دستور deserialization

سیستم JSON دارای یک ترتیب صریح deserialization است که جلوگیری از تکرار حالت در یک ذخیره را آسان‌تر می‌کند.

هنگامی که Blockly.serialization.workspaces.load فراخوانی می شود، به سریال سازها به ترتیب اولویت حالت deserialization داده می شود. این موضوع در بخش سریال سازها توضیح داده شده است و هدف آن این است که به سریال سازها اجازه دهد تا به وضعیت سایر سیستم ها وابسته شوند.

ترتیب سریال زدایی سریالایزرهای داخلی به شرح زیر است:

  1. مدل‌های متغیر بی‌سریال می‌شوند.
  2. مدل‌های رویه‌ای بی‌سریال شده‌اند.
  3. بلوک‌ها بی‌اهمیت هستند. بلوک‌های سطح بالای منفرد به ترتیب دلخواه از فهرست خارج می‌شوند.
    1. نوع deserialized است. این بلوک را می سازد، روش init آن را راه اندازی می کند، و در پسوندها مخلوط می شود.
    2. ویژگی‌ها غیرقانونی شده‌اند. این شامل ویژگی هایی است که می تواند برای هر بلوکی اعمال شود. به عنوان مثال: x، y، جمع شده، غیرفعال، و داده.
    3. حالت اضافی بی‌سریال شده است. برای اطلاعات بیشتر به اسناد Extensions and Mutators مراجعه کنید.
    4. بلوک به والد خود متصل است (در صورت وجود).
    5. آیکون‌ها غیرقانونی هستند. نمادهای منفرد به ترتیب دلخواه از فهرست خارج می شوند.
    6. فیلدها بی هویت شده اند. فیلدهای منفرد به ترتیب دلخواه از فهرست خارج می شوند.
    7. بلوک‌های ورودی بی‌ثبات می‌شوند. این شامل بلوک های متصل به ورودی های مقدار و ورودی های بیانیه است. ورودی‌های فردی به ترتیب دلخواه از فهرست خارج می‌شوند.
    8. بلوک‌های بعدی بی‌ثبات می‌شوند.

زمان ذخیره حالت اضافی

برای بلوک‌ها، اگر چیزی پایین‌تر در ترتیب دارید که به چیزی بالاتر در ترتیب بستگی دارد، باید آن داده‌ها را کپی کنید و به حالت اضافی خود اضافه کنید.

به عنوان مثال، اگر یک فیلد دارید که فقط در صورت اتصال بلوک بعدی وجود دارد، باید اطلاعات مربوط به بلوک بعدی را به حالت اضافی خود اضافه کنید، بنابراین قبل از اینکه وضعیت فیلد از فهرست خارج شود، می توان فیلد را به بلوک شما اضافه کرد.

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

توجه داشته باشید که قاعده مربوط به حالت تکراری باید این را نیز در نظر بگیرد که پشته‌های بلوک، نمادها، فیلدها و بلوک‌های ورودی به ترتیب دلخواه از فهرست خارج می‌شوند. به عنوان مثال، اگر یک فیلد B دارید که فقط در صورتی وجود دارد که فیلد A دیگری دارای مقدار مشخصی باشد، باید اطلاعات مربوط به A را به حالت اضافی خود اضافه کنید، در صورتی که B قبل از A از فهرست خارج شود.

قلاب ها را مسدود کنید

برای اطلاعات در مورد نحوه اضافه کردن سریال سازی اضافی به بلوک ها، به مستندات Extensions and Mutators مراجعه کنید.

قلاب های صحرایی

برای اطلاعات در مورد نحوه سریال سازی فیلدها، به مستندات فیلدهای سفارشی مراجعه کنید.

قلاب های سریال ساز

سیستم 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 ارائه شده نامیده می شود. این تضمین می کند که وضعیت پلاگین/سیستم شما قبل از بارگیری حالت بیشتر تمیز است. برای مثال، سریال‌ساز فضای کاری-کامنت‌ها تمام نظرات موجود را از فضای کاری حذف می‌کند.
  2. تابع load ارائه شده نامیده می شود.

سیستم XML

سیستم XML به شما این امکان را می دهد که فضای کاری خود را به یک گره XML سریال کنید. این سیستم سریال سازی اصلی Blockly بود. اکنون جعبه یخی بسته شده است، به این معنی که ویژگی های جدیدی دریافت نخواهد کرد. به این ترتیب، توصیه می کنیم در صورت امکان از سیستم JSON استفاده کنید.

API ها

برای اطلاعات در مورد APIهای سیستم XML به مستندات مرجع مراجعه کنید.

قلاب ها را مسدود کنید

برای اطلاعات در مورد نحوه اضافه کردن سریال سازی اضافی به بلوک ها، به مستندات Extensions and Mutators مراجعه کنید.

قلاب های صحرایی

برای اطلاعات در مورد نحوه سریال سازی فیلدها، به مستندات فیلدهای سفارشی مراجعه کنید.

انتخاب بین JSON و XML

ما سریال‌ساز JSON را روی XML توصیه می‌کنیم. سیستم JSON به شما امکان می دهد وضعیت فضای کاری خود را به یک شی جاوا اسکریپت سریال کنید. این مزیت است زیرا:

  1. فشرده سازی یا تبدیل JSON به فرمت دیگری آسان است.
  2. کار با JSON به صورت برنامه نویسی آسان است.
  3. JSON به راحتی قابل گسترش و اضافه کردن داده ها است.

علاوه بر این، سیستم XML دیگر به‌روزرسانی‌ها را دریافت نمی‌کند و در مقایسه با سریال‌ساز JSON فاقد ویژگی‌هایی است. برای مثال، می‌توانید سریال‌ساز JSON خود را ثبت کنید تا به راحتی داده‌های اضافی را ذخیره و بارگیری کنید، مانند داده‌های افزونه‌ها یا سفارشی‌سازی‌هایی که اضافه کرده‌اید. در سیستم XML این امکان وجود ندارد.

اگر قبلاً از سریال‌سازی XML استفاده کرده‌اید، برای اطلاعات در مورد نحوه ارتقاء به راهنمای مهاجرت مراجعه کنید.