حفظ وتحميل

تؤدي عملية التسلسل إلى حفظ حالة مساحة العمل حتى يمكن تحميلها مجددًا في مساحة العمل لاحقًا. ويشمل ذلك تسلسل حالة أي كتل أو متغيّرات أو مكوّنات إضافية تريد حفظها. يمكنك تحويل كل البيانات التي تحتاج إلى حفظها إلى تنسيق يستند إلى النص لتسهيل تخزينها، ثم تحميل هذه البيانات مرة أخرى إلى مساحة عمل وظيفية بالكامل في وقت لاحق.

يوفّر Blockly تنسيقَين لهذه البيانات: JSON وXML. ننصح باستخدام نظام JSON للمشاريع الجديدة، ونشجّع المشاريع القديمة التي تستخدم XML على الترقية. نظام XML هو تنسيق الحفظ القديم. ولن تتم إزالته، ولكن لن يتم إضافة ميزات جديدة إليه.

نظام JSON

ملاحظة: للحصول على معلومات عن كيفية نقل البيانات إلى تنسيق JSON من تنسيق XML، اطّلِع على دليل نقل البيانات.

يتألف نظام تسلسل 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);

ترتيب إزالة التسلسل

يحتوي نظام JSON على ترتيب صريح لتحويل البيانات إلى سلسلة، ما يسهّل منع تكرار الحالة ضمن عملية حفظ.

عند استدعاء Blockly.serialization.workspaces.load، يتم منح معرِّفات التسلسل حالة لتحويلها إلى سلسلة بترتيب الأولوية. يتم شرح ذلك بشكل أكبر في القسم أدوات التحويل ، والغرض منه هو السماح لأدوات التحويل بالاعتماد على الحالة من الأنظمة الأخرى.

ترتيب تحويل ترميز معرِّفات البيانات إلى سلسلة هو:

1. يتم إعادة تسلسل نماذج المتغيّرات.
2. يتم تحويل نماذج الإجراءات إلى سلسلة.
3. يتم تحويل تنسيق السلسلة إلى تنسيق ثنائي. يتم بترتيب عشوائي تحويل التنسيق إلى نص لوحدات المستوى الأعلى الفردية.
   1. يتم تحويل النوع إلى سلسلة. يؤدي ذلك إلى إنشاء الكتلة وتشغيل أسلوب init ومزج الإضافات.
   2. يتم تحويل السمات إلى سلسلة. ويشمل ذلك السمات التي يمكن تطبيقها على أيّ عنصر. على سبيل المثال: x وy وcollapsed وdisabled وdata.
4. يتم تحويل الحالة الإضافية إلى سلسلة. اطّلِع على مستندات Mutators للحصول على مزيد من المعلومات.
5. يكون العنصر الرئيسي مرتبطًا بعنصره الرئيسي (إذا كان متوفّرًا).
   1. يتم تحويل الرموز إلى سلسلة. يتم تحويل ترميز الرموز الفردية إلى نص في ترتيب عشوائي.
   2. يتم تحويل الحقول إلى سلسلة. يتم تحويل ترميز الحقول الفردية إلى نص في ترتيب عشوائي.
   3. يتم تحويل وحدات الإدخال إلى سلسلة. ويشمل ذلك الكتل المرتبطة ب inputs قيمة وinputs بيان. يتم تحويل بيانات الإدخال الفردية إلى نص في ترتيب عشوائي.
   4. يتم تحويل التنسيق إلى سلسلة من الأحرف في الكتل التالية.

حالات حفظ البيانات الإضافية

بالنسبة إلى الكتل، إذا كان لديك عنصر في ترتيب أدنى يعتمد على عنصر في ترتيب أعلى، عليك تكرار هذه البيانات وإضافتها إلى حالة الإضافية.

على سبيل المثال، إذا كان لديك حقل لا يظهر إلا إذا كان هناك قالب لاحق مرتبط به، عليك إضافة معلومات عن هذا القالب اللاحق إلى حالتك الإضافية، حتى تتمكّن من إضافة الحقل إلى قالبك قبل تحويل حالة الحقل إلى سلسلة.

ومع ذلك، إذا كان لديك إدخال لا يظهر إلا إذا كان الحقل يحتوي على قيمة معيّنة، لست بحاجة إلى إضافة معلومات عن الحقل إلى حالتك الإضافية. ويعود السبب في ذلك إلى أنّه سيتم أولاً تحويل حالة الحقل إلى سلسلة، وبعد ذلك يمكنك إضافة الإدخال إلى العنصر. عادةً ما يتم بدء إضافة الإدخال من خلال أداة التحقّق.

تجدر الإشارة إلى أنّ القاعدة المتعلقة بحالة التكرار يجب أن تأخذ في الاعتبار أيضًا أنّه يتم تسلسل حزم الكتل والرموز والحقول وكتل الإدخال في ترتيب عشوائي. على سبيل المثال، إذا كان لديك حقل واحد (ب) لا يظهر إلا إذا كان حقل آخر (أ) يتضمّن قيمة معيّنة، عليك إضافة معلومات عن الحقل (أ) إلى الحالة الإضافية في حال تمّ تحويل الحقل (ب) إلى تنسيق ثنائي قبل الحقل (أ).

عبارات افتتاحية محظورة

للحصول على معلومات عن كيفية إضافة تسلسل إضافي إلى الكتل، يُرجى الاطّلاع على مستندات المُعدِّلات.

أدوات الصيد

للحصول على معلومات عن كيفية تسلسل الحقول، يُرجى الاطّلاع على مستندات الحقول المخصّصة.

أدوات ربط أداة التحويل

يتيح لك نظام 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، الذي يُستخدَم لتحديد ترتيب معالجة السلسلة المبرمَجة

  يمكنك تحديد أولوية أداة تسلسل البيانات استنادًا إلى أولويات تكامل.

عند استدعاء 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 إذا أمكن.

ملاحظة: للحصول على معلومات عن كيفية نقل البيانات إلى تنسيق JSON، اطّلِع على دليل نقل البيانات.

واجهات برمجة التطبيقات

للحصول على معلومات عن واجهات برمجة التطبيقات لنظام XML، يُرجى الاطّلاع على مستندات المرجع.

عبارات افتتاحية محظورة

للحصول على معلومات عن كيفية إضافة تسلسل إضافي إلى الكتل، يُرجى الاطّلاع على مستندات المُعدِّلات.

أدوات الصيد

للحصول على معلومات عن كيفية تسلسل الحقول، يُرجى الاطّلاع على مستندات الحقول المخصّصة.

الاختيار بين JSON وXML

ننصحك باستخدام معرِّف تنسيق JSON بدلاً من XML. يتيح لك نظام JSON تسلسل حالة مساحة العمل إلى كائن JavaScript. ويعود سبب ذلك إلى:

1. من السهل ضغط ملفات JSON أو تحويلها إلى تنسيق آخر.
2. من السهل التعامل مع تنسيق JSON برمجيًا.
3. من السهل توسيع تنسيق JSON وإلحاق البيانات به.

بالإضافة إلى ذلك، لن يتلقّى نظام XML تحديثات بعد الآن، كما أنّه يفتقر إلى ميزات مقارنةً بسلسلة JSON. على سبيل المثال، يمكنك تسجيل ملف تحويل محتوى بتنسيق JSON الخاص بك لحفظ بيانات إضافية وتحميلها بسهولة، مثل بيانات المكوّنات الإضافية أو التخصيصات التي أضفتها. لا يمكن إجراء ذلك في نظام XML.

إذا سبق لك استخدام تسلسل XML، يمكنك الاطّلاع على دليل نقل البيانات للحصول على معلومات عن كيفية الترقية.