كيفية بناء ونشر وحدة الزاوي

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

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

هذا المنشور مخصص للمطورين ذوي الخبرة الذين يعرفون بالفعل المفاهيم الأساسية لـ Angular وكيفية إنشاء تطبيق أساسي. النسخة الفرنسية من هذا المنشور متاحة هنا.

تحديث: الزاوي 6

هذا المنشور لم يعد ذا صلة. باستخدام Angular 6 ، يكون إنشاء مكتبة Angular بسيطًا مثل اسم مكتبة ng g. انظر وثائق CLI الرسمية.

من قبل المؤلف نفسه

  • ملحق الخطط الزاوي لرمز VS: واجهة المستخدم الرسومية لأوامر CLI الزاوية
  • @ ngx-pwa / local-storage: مكتبة الزاوي الأولى للتخزين المحلي
  • مكتبات Angular أخرى: @ ngx-pwa / دون اتصال & @ ngx-pwa / ngsw-schema
  • المشاركات الزاوي شعبية أخرى على متوسطة
  • تابعني على تويتر
  • دورات تدريبية في الموقع (مقرها في باريس ، لذلك الموقع باللغة الفرنسية ، لكن لغتي الإنجليزية هي هنا وأنا منفتح للسفر)

إنشاء وحدة الزاوي الخاص بك: المزالق

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

أولا ، أبدا استيراد BrowserModule. الوحدة النمطية الخاصة بك عبارة عن وحدة ميزات ، يجب على المستخدم النهائي فقط استيراد BrowserModule ، في وحدة الجذر الخاصة بالتطبيق. إذا كنت بحاجة إلى التوجيهات الشائعة (* ngIf ، * ngFor ...) ، فاستورد CommonModule.

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

الأهم من ذلك ، لا تخلط المكونات / التوجيهات / الأنابيب والخدمات في نفس الوحدة. لماذا ا؟

  • ستتوفر خدمة متوفرة في وحدة نمطية في كل مكان في التطبيق ، لذلك يجب استيراد الوحدة الخاصة بك مرة واحدة فقط ، في وحدة الجذر لتطبيق المستخدم (مثل وحدة Http).
  • سيتوفر المكون / التوجيه / الإخراج المُصدر فقط في الوحدة النمطية التي تستورد لك ، لذلك يجب أن تستورد الوحدة الخاصة بك في كل وحدة مستخدم (وحدات نمطية للجذر و / أو الميزة) التي تحتاج إليها (مثل CommonModule).

إذا لم يكن هذا الأمر واضحًا بالنسبة لك ، فيجب أن تكون مشاركتي الأخرى "فهم وحدات الزاوي (NgModule) ونطاقاتها" ، لأنها نقطة مهمة (ومربكة) في الزاوي.

أخيرًا ، احترم القاعدة الزاوية: لا تستخدم أبدًا واجهات برمجة التطبيقات الخاصة بالمستعرض (مثل DOM) مباشرةً. إذا قمت بذلك ، فلن تكون وحدتك متوافقة مع تقديم خادم Universal وخيارات Angular المتقدمة الأخرى. إذا كنت بحاجة حقًا إلى استخدام واجهات برمجة التطبيقات الخاصة بالمتصفح (localStorage ...) ، فيجب عليك تجربة / التقاط الأخطاء.

تصدير API العامة

عند استخدام وحدة Angular رسمية ، لديك فقط نقطة إدخال واحدة لاستيراد كل ما تحتاج إليه (مثل "@ angular / http").

لذلك ستحتاج إلى إنشاء ملف index.ts ، وتصدير جميع واجهات برمجة التطبيقات (API) العامة لوحدتك. يجب أن يحتوي على الأقل على NgModule الخاص بك ، ومكوناتك أو خدماتك (سيحتاج المستخدم إلى استيرادها لحقنها عند الحاجة).

لن يتم استيراد المكونات / التوجيهات / الأنابيب مباشرة من قبل المستخدم ، ولكن يتعين عليك تصديرها لتكون متوافقة مع AoT (بفضل Isaac Mann على هذه المعلومات).

بناء الأدوات

إنه المكان الذي بدأت فيه الكفاح. لذلك تمكنت من نسخ كيفية عمل الوحدات الزاويّة الرسمية ، مثل HttpModule. هم يستخدمون:

  • منضدة ، من خلال المترجم الزاوي (ngc) ، للاستنساخ ،
  • rollupjs للتغليف ،
  • uglify-js للتصغير.
npm install @ angular / compiler @ angular / compiler-cli typescript rollup uglify-js --save-dev

تكوين TypeScript

إليك tsconfig.json لوحدتي:

هناك بعض الاختلافات المهمة مع tsconfig.json الكلاسيكية:

  • هناك حاجة إلى "مسارات" صريحة للوحدات الأخرى التي تستخدمها ، لأن الحزمة النهائية لن تتضمنها مباشرةً (المزيد حول هذا لاحقًا).
  • "angularCompilerOptions": {"rictMetadataEmit ": true} مطلوب لتكون متوافقًا مع AoT.
  • "التعريف": صحيح هو المهم لإنشاء ملفات تعريفات النوع ، لذلك سيكون لدى المستخدم Intellisense لوحدتك.
  • "noImplicitAny": صواب و "rictNullChecks ": صواب ينصح بتجنب الأخطاء ، ولكي يكون متوافقًا مع كل تكوينات المستخدم. "noImplicitAny": صحيح يجب احترامه منذ Angular 4.0 و "rictNullChecks ": true ابتداءً من Angular 4.1.
  • "module": "es2015" مهم للأداء و "sourceMap": صحيح في تصحيح الأخطاء ، لكن لا يوجد شيء محدد هنا.
  • "stripInternal": true تجنب الإعلانات غير المجدية لواجهات برمجة التطبيقات الداخلية و "skipLibCheck": true تجنب الحجب عن طريق الأخطاء (غير الضارة) في المكتبات التي تستخدمها.

التكوين التراكمي

يتم تسليم الوحدات الزاوية في تنسيق UMD ، لذلك يجب ضبط ملف rollup.config.js الخاص بك. هنا مثال:

البرنامج النصي للدخول هو index.ts الخاص بك المنقول ، لذلك يجب أن يتطابق مع تكوين TypeScript الخاص بك. الحزم / modulename.umd.js هي المسار التقليدي والاسم الذي تستخدمه الوحدات الزاويّة.

تتطلب مجموعة التحديثات اسم وحدة نمطية لتنسيق UMD. سيكون كائن JavaScript ، لذلك لا تستخدم أحرفًا خاصة (بدون شرطات).

ثم ، هنا تكمن النقطة المهمة. تستخدم الوحدة الخاصة بك أشياء Angular (على الأقل ديكور NgModule) ، ولكن يجب ألا تتضمن الحزمة الخاصة بك Angular.

لماذا ا؟ سيتم تضمين الزاوي بالفعل في تطبيق المستخدم. إذا كانت الوحدة النمطية الخاصة بك تتضمن ذلك أيضًا ، فستكون هناك مرتين ، وسيكون هناك أخطاء فادحة (وغير مفهومة).

لذلك تحتاج إلى تعيين Angular باعتبارها عالمية. وتحتاج إلى معرفة اسم وحدة UMD لكل وحدة. تتبع هذه الاتفاقية: ng.modulename (ng.core ، ng.common ، ng.http ...).

ينطبق الشيء نفسه على RxJS ، إذا كانت الوحدة النمطية تستخدمه. وأسماء الوحدة النمطية هي تماما فوضى هنا. بالنسبة للفصول (الملاحظة ...) ، إنها Rx. بالنسبة للمشغلين (الخريطة ، عامل التصفية ...) ، إنه Rx.Observable.prototype. بالنسبة للطرق المباشرة للفئات (من ، من الأحداث ...) ، إنها Rx.Observable.

بناء ، في النهاية

يمكنك الآن إنشاء حزمة الوحدة النمطية الخاصة بك. يمكنك حفظ أسطر الأوامر في البرامج النصية npm:

ثم:

تشغيل npm بناء

لاحظ أن عملية النقل لا تتم مباشرة بواسطة TypeScript ، يجب عليك استخدام برنامج التحويل البرمجي Angular (ngc): إنه برنامج TypeScript مع بعض السحر الزاوي.

النشر على npm

لا تنشر كل شيء على npm ، فقط دليل dist.

ستحتاج إلى إنشاء dist / package.json جديدة ومحددة. فمثلا :

بعض النقاط المحددة:

  • يجب أن يتبع "الإصدار" الإصدار الدلالي. أي تغيير عاجل يعني زيادة عدد كبير (حتى لو كان تغييرًا طفيفًا). وعندما تقوم بتعديل الوحدة النمطية الخاصة بك لتظل على علم بآخر الزاوي ، فهذا يمثل زيادة طفيفة في الرقم.
  • هناك حاجة إلى مسارات "الرئيسي" و "الوحدة النمطية" لواردات المستخدم. مسار "typings" خاص بـ Intellisense.
  • "الترخيص": "معهد ماساتشوستس للتكنولوجيا": الترخيص مفتوح المصدر مهم ، أو الوحدة النمطية الخاصة بك غير مجدية. يستخدم Angular ترخيص MIT ، ويجب عليك الالتزام به.
  • سيتم إدراج الوحدات الزاوية التي استخدمتها في التبعيات النظيرة. لا تزال تتبع الفصل ، مع علامة ^ ، أو الوحدة الخاصة بك سوف تكون عفا عليها الزمن في كل مرة ترقيات الزاوي. بالنسبة للمكتبات الأخرى (RxJS ، zone.js ...) ، يمكنك رؤية المتطلبات الحالية لـ Angular هنا.

لا تنس أن تكتب README ، مع وثائق API الخاصة بك. خلاف ذلك الوحدة النمطية الخاصة بك غير مجدية. يمكنك استخدام مكتبة مثل ملفات النسخ لنسخ README الخاص بك من دليل مشروع الجذر (المعروض على Github) إلى دليل dist (المعروض على مستودع npm).

ومع حساب تكوين npm ، يمكنك الآن نشر الوحدة النمطية الخاصة بك:

مؤتمر نزع السلاح dist
npm نشر

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