التسلسل

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

توفِّر سياسة Openly تنسيقَين لهذه البيانات هما: 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);

ترتيب إزالة العنوان

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

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

يكون ترتيب إلغاء التسلسل التسلسلي المدمج هو ما يلي:

1. يتم إلغاء تسلسل النماذج المتغيّرة.
2. يتم إلغاء تسلسل نماذج الإجراءات.
3. يتم إلغاء تسلسل مجموعات القوالب. يتم إلغاء ترتيب المجموعات الفردية ذات المستوى الأعلى بترتيب عشوائي.
   1. تم إلغاء تسلسل النوع. يؤدي هذا إلى إنشاء الكتلة وتشغيل أسلوبها والمزج في الإضافات.
   2. يتم إلغاء تسلسل السمات. ويتضمن ذلك الخصائص التي يمكن تطبيقها على أي كتلة. على سبيل المثال: "س" و"ص" و"تم تصغيرها" و"غير مفعَّلة" و"بيانات".
   3. يتم إلغاء تسلسل البيانات في الحالة الإضافية. راجع وثائق الإضافات وأجهزة الإعداد للحصول على مزيد من المعلومات.
   4. ترتبط المجموعة بعنصرها الرئيسي (إن وُجد).
   5. يتم إلغاء تسلسل الرموز. يتم إلغاء تسلسل الرموز الفردية بترتيب عشوائي.
   6. يتم إلغاء تسلسل الحقول. يتم إلغاء ترتيب الحقول الفردية بترتيب عشوائي.
   7. يتم إلغاء تسلسل مجموعات الإدخالات. يتضمن ذلك الكتل المرتبطة بمدخلات القيمة ومدخلات العبارة. يتم إلغاء ترتيب الإدخالات الفردية بترتيب عشوائي.
   8. يتم إلغاء تسلسل الوحدات التالية.

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

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

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

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

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

خطافات عمودية

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

خُطافات الملعب

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

خطافات متسلسلة

يسمح لك نظام 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 إن أمكن ذلك.

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

لمزيد من المعلومات حول واجهات برمجة التطبيقات لنظام XML، يمكنك الاطّلاع على الوثائق المرجعية.

خطافات عمودية

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

خُطافات الملعب

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

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

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

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

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

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