التسلسل

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

يوفّر الحظر باستخدام تنسيقَين لهذه البيانات، وهما 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. تم إلغاء تسلسل النوع. يؤدي هذا إلى إنشاء الكتلة وتشغيل طريقة البدء والمزج في الإضافات.
   2. يتم تحويل السمات إلى سلسلة. ويشمل ذلك السمات التي يمكن تطبيقها على أيّ مجموعة. على سبيل المثال: x وy وcollapsed وdisabled وdata.
   3. يتم تحويل الحالة الإضافية إلى سلسلة ثنائية. اطّلِع على وثائق الإضافات والمفاتيح البرمجية لمزيد من المعلومات.
   4. يكون العنصر الرئيسي مرتبطًا بالعنصر (إذا كان متوفّرًا).
   5. يتم تحويل الرموز إلى سلسلة. يتم تحويل ترميز الرموز الفردية إلى نص في ترتيب عشوائي.
   6. يتم تحويل الحقول إلى سلسلة. يتم تحويل ترميز الحقول الفردية إلى نص في ترتيب عشوائي.
   7. إلغاء تسلسل وحدات الإدخال: ويشمل ذلك الكتل المرتبطة بمدخلات القيم ومدخلات العبارة. يتم تحويل بيانات الإدخال الفردية إلى نص في ترتيب عشوائي.
   8. يتم تحويل التنسيق إلى سلسلة من الأحرف في الكتل التالية.

متى يتم حفظ الحالة الإضافية

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

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

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

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

خطافات حديدية

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

أدوات الصيد

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

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

يتيح لك نظام 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 المقدَّمة. يضمن ذلك أنّ حالة المكوّن الإضافي/النظام خالية من أي أخطاء قبل تحميل المزيد من الحالات. على سبيل المثال، سيزيل تسلسل التعليقات على مساحة العمل جميع التعليقات الحالية من مساحة العمل.
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، يُرجى الاطّلاع على دليل نقل البيانات للحصول على معلومات حول كيفية الترقية.