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

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

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

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

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

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

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

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

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

البدء بسرعة

  • إذا أجريت تغييرات محلية وتريد التأكد من أنها لم تكسر الإصدار أو أي اختبارات، فقم بإجراء

    npm test

    لإنشاء تطبيقBlockly وتشغيل مجموعة أدواته التجريبية.

  • إذا كنت ترغب في اختبار التغييرات المحلية في المتصفح، فابدأ

    npm start

    يجمّع هذا الرمز باسم بشكل حظر ويفتح متصفّح ويب يشير إلى ساحة اللعب القائمة التي تعمل بحظر في وضع غير مضغوط.

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

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

    npm run package

    لإنشاء حزمة حظر،

    cd dist && npm link

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

    npm link blockly

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

مرجع النص البرمجي التفصيلي

يسرد هذا القسم المبدأ scripts في ملف package.json الخاص بأداة حظر الإعلانات مع شرح لما يفعله.

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

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

لا يتم تتبع أي من الدليلين في مستودع git المحظور.

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.

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

build

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

package

يشغِّل npm run package مهمتَي clean وbuild، وبعد ذلك:

  • يؤدي هذا إلى تطبيق برنامج تضمين UMD على الملفات في build/msg/، مع وضع الإصدارات التي تم لفّها في dist/msg/.
  • يضيف العديد من ملفات الدعم الإضافية إلى dist/، مع برامج تضمين UMD عندما انطبق ذلك.

publish

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

lint

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

test

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