التسلسل

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

يوفّر بشكل حظر تنسيقين لهذه البيانات، وهما 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، يتم منح حالة المتسلسلين لإلغاء التسلسل حسب الأولوية. يتم شرح ذلك بشكل أكبر في قسم تسلسلات البيانات، والغرض منه هو السماح للتسلسلات بالاعتماد على حالة الأنظمة الأخرى.

ترتيب إلغاء التسلسلات المضمنة هو:

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

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

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

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

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

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

خطافات القطع

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

مشبكات الملاعب

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

خطافات جهاز التسلسل

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