إنشاء النصوص البرمجية

يتألف Blockly من أكثر من مئة ملف TypeScript. ويجب أن يتم تجميعها بواسطة محوّل TypeScript البرمجي، tsc، إلى JavaScript قبل أن يتم استخدامها. يؤدي ذلك إلى إنشاء عدد كبير من ملفات .js المناسبة للاختبار المحلي، ولكن تحميل هذا العدد الكبير من الملفات عبر الإنترنت يقدّم تجربة بطيئة للمستخدمين النهائيين. لتحميل Blockly بشكل أسرع، يتم استخدام Closure Compiler لضغط الملفات (تصغيرها) ودمجها في ستة ملفات تقريبًا ("حِزم" أو "أجزاء") يقل حجمها الإجمالي عن نصف حجم الملفات غير المضغوطة.

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

يحتوي مستودع RaspberryPiFoundation/blockly على رمز المصدر فقط. كانت تحتوي سابقًا أيضًا على منتجات الإصدار، ولكن منذ عام 2019، تم نشر الحِزم المصغّرة باسم حزمة blockly NPM، ومنذ عام 2022، تم إرفاقها أيضًا كملف .tgz بكل إصدار على GitHub، لذلك لا حاجة إلى إنشاء Blockly إلا إذا كنت تعمل على تعديل Blockly نفسه، وخاصةً على الملفات في الدلائل core أو blocks أو generators أو msg.

تتم عملية إنشاء Blockly واختباره ونشره بشكل آلي باستخدام نصوص npm البرمجية لتشغيل مهام Gulp. تتضمّن هذه الصفحة مستندات حول النصوص البرمجية الأساسية ووظيفة كل منها.

الوضع المضغوط والوضع غير المضغوط

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

يُشار إلى تحميل Blockly من الحِزم المصغّرة باسم "الوضع المضغوط". هذه هي أفضل طريقة لاختبار التغييرات التي يتم إجراؤها على Blockly عند استخدامه كعنصر تابع لحزمة أخرى، لأنّها تختبر (إصدارًا غير منشور من) حزمة blocklynpm.

N.B.: في بعض الأماكن في مستودع Blockly، يتم استخدام المصطلحَين "الوضع غير المجمَّع" و "الوضع المجمَّع" كمرادفين للمصطلحَين "الوضع غير المضغوط" و "الوضع المضغوط" على التوالي. كان هذا الاستخدام منطقيًا في الماضي لأنّ Closure Compiler كان يُستخدم لضغط الرمز (تصغيره)، ولكن الآن يجب دائمًا استخدام برنامج الترجمة البرمجية TypeScript، حتى في وضع عدم الضغط، لذا قد يكون هذا المصطلح البديل مربكًا ويُنصح بعدم استخدامه.

البدء بسرعة

  • إذا أجريت تغييرات محلية وأردت التأكّد من أنّها لم تؤدِّ إلى تعطيل الإصدار أو أي اختبارات، نفِّذ ما يلي:

    npm test

    لإنشاء Blockly وتشغيل مجموعة الاختبارات الخاصة به.

  • إذا أردت اختبار التغييرات المحلية في المتصفح، شغِّل

    npm start

    يؤدي ذلك إلى تجميع Blockly وفتح متصفّح ويب يشير إلى ساحة تجارب Blockly التي تشغّل Blockly في وضع غير مضغوط.

    تتم إعادة تجميع أي ملفات تم تعديلها في core/ وblocks/ وgenerators/ تلقائيًا، لذا أعِد تحميل علامة تبويب المتصفّح للاطّلاع على التغييرات.

  • لإنشاء نسختك المعدَّلة من Blockly واختبارها في الوضع المضغوط، كعنصر تابع لحزمة npm أخرى، نفِّذ ما يلي:

    npm run package

    لإنشاء حزمة Blockly، ثم

    cd dist && npm link

    لتحديد مكان العثور على الملفات المجمّعة في npm، ثم انتقِل إلى دليل مشروعك باستخدام cd قبل تشغيل

    npm link blockly

    لكي تستخدم حزمتك الإصدار الذي تم تجميعه حديثًا من Blockly بدلاً من حزمة blockly المنشورة.

مرجع النصوص البرمجية المفصّل

يسرد هذا القسم المبدأ scripts في ملف package.json الخاص بـ Blockly مع شرح لوظائفه.

تنشئ هذه النصوص البرمجية ملفات في مكانَين:

  • الملفات الموجودة في الدليل الفرعي build/ هي ملفات وسيطة تُستخدم للاختبار المحلي أو يتم استيعابها من خلال أجزاء لاحقة من مسار إنشاء التطبيق.
  • تشكّل الملفات الموجودة في الدليل الفرعي dist/ محتوى حزمة npm المنشورة.

لا يتم تتبُّع أي من الدليلين في مستودع git الخاص بـ Blockly.

clean

npm run clean تنظيف أي إصدارات سابقة عن طريق حذف الدليلَين build/ وdist/ وهي مفيدة لإصلاح أخطاء البناء الغامضة، خاصةً تلك الناتجة عن إعادة تسمية ملف مصدر.

messages

يعدّل npm run messages ملفات الرسائل في msg/json/ لتشمل أي تغييرات تم إجراؤها على msg/messages.js، ويجب تشغيله بعد كل مرة يتم فيها تعديل هذا الملف.

langfiles

تنشئ npm run langfiles ملفات اللغة المجمّعة في build/msg/ من ملفات الرسائل في msg/json.

tsc

يُشغّل الأمر npm run tsc برنامج ترجمة TypeScript على محتوى الأدلة core/ وblocks/ وgenerators/، ويُخرج ملفات .js فردية إلى build/src/.

minify

تنفِّذ npm run minify closure-make-deps وclosure-calculate-chunks لتحديد كيفية تقسيم ملفات .js المجمّعة إلى أجزاء (حِزم مصغّرة)، ثم تنفِّذ closure-compiler لإنشاء الأجزاء على النحو التالي:

  • يصبح محتوى build/src/core/ هو محتوى dist/blockly_compressed.js.
  • يصبح محتوى build/src/blocks/ هو محتوى dist/blocs_compressed.js.
  • يصبح محتوى build/src/generators/javascript/ (بالإضافة إلى build/src/generators/javascript.js) هو dist/javascript_compressed.js.
  • وينطبق الأمر نفسه على dart وlua وphp وpython.

تستخدم حِزم chuks التي تم إنشاؤها برنامج تضمين لضمان التوافق مع تعريف الوحدة النمطية الشاملة، وبالتالي لا يلزم إجراء أي معالجة إضافية قبل تضمينها في الحزمة.

build

ينفّذ npm run build المهمتَين minify وlangfiles. من المفترض أن يؤدي ذلك إلى تنفيذ كل ما يلزم لتحميل ساحة تجارب Blockly في الوضع المضغوط أو غير المضغوط.

package

ينفِّذ npm run package المهمتَين clean وbuild، ثم:

  • تطبيق برنامج تضمين UMD على الملفات في build/msg/، ووضع النُسخ المضمّنة في dist/msg/
  • تضيف هذه السمة العديد من ملفات الدعم الإضافية إلى dist/، مع أغلفة UMD حيثما ينطبق ذلك.

publish

يستخدم فريق Blockly npm run publish لنشر حزمة blockly npm. ويعتمد على البنية الأساسية الداخلية في Google، لذا فهو غير مفيد للمطوّرين الخارجيين.

lint

npm run lint يشغّل ESLint، ويجري تحليلًا ثابتًا لرمز المصدر في Blockly للعثور على المشاكل.

test

ينفّذ الأمر npm test (أو npm run test) المهمة package، ثم ينفّذ اختبارات تلقائية مختلفة (بما في ذلك تشغيل ESLint). يجب تشغيل هذا الاختبار واجتيازه على أي رمز يتم إرساله كطلب سحب إلى مستودع Blockly.