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

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

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

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

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

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

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

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

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

البدء بسرعة

وإذا أجريت تغييرات محلية وتريد التأكد من عدم خرق وإنشاء أو أي اختبارات وإجراء
```
npm test
```
لإنشاء Blockly وتشغيل مجموعة الاختبار.
إذا كنت تريد اختبار التغييرات المحلية في المتصفّح، يمكنك تنفيذ
```
npm start
```
يؤدي هذا إلى تجميع Blockly وفتح متصفح ويب يشير إلى القسم "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`

يتم تعديل ملفات الرسائل في "msg/json/" من قِبل "npm run messages" بأي تغييرات. التي تم إجراؤها على 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.

تستخدم الملفات التي تم إنشاؤها برنامج تضمين لضمان التوافق مع واجهة برمجة التطبيقات Universal تعريف الوحدة وبالتالي لا تكون هناك معالجة إضافية مطلوبة قبل تضمينها في الحزمة.

`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، ويُجري تحليلاً ثابتًا لإيجاد المشكلات.

`test`

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