twc

مكونات الويب المكتوبة

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

تثبيت

 npm install -g twc

استخدام

TWC يأتي مع CLI. معظم تكوينه يأتي من tsconfig (و bower.json ) ، وهو يعمل إلى حد كبير مثل TSC. لتحويل فئات TS إلى وحدات البوليمر الأصلية ، ما عليك سوى إدخال جذر المشروع وتنفيذ ما يلي في المحطة:

 twc

إنه يعمل مثل tsc ، وقراءة التكوين من ملف tsconfig.json . الفرق الوحيد هو إخراج ملفات .html مع وحدة البوليمر بدلاً من .js .

إعدادات

بما في ذلك التعليقات التوضيحية

ستكون التعليقات التوضيحية متوفرة في مساحة الاسم @types . حتى يحدث هذا ، يجب تضمين الأنواع في TSConfig:

 {
  "compilerOptions": {
    ...
  },

  "files": [
    ...
  ],
  "include": [
    "node_modules/twc/types/polymer.decorators.d.ts"
  ]
}

نسخة البوليمر

يسمح TWC بتجميع نفس الكود في البوليمر 1.x أو البوليمر 2.x. قبل التجميع ، يتم فحص bower.json لإصدار تبعية البوليمر ومن ثم يتم استخدامه كهدف. على سبيل المثال:

 "polymer": "Polymer/polymer#^1.8.0"

سوف يبني وحدة البوليمر 1.x ، في حين أن هذا:

 "polymer": "Polymer/polymer#^2.0.0"

يبني وحدة البوليمر 2.x على أساس ES6.

خيارات TypeScript

تتوفر خيارات برنامج التحويل البرمجي TypeScript لـ TWC أيضًا ، ولا يتم دعم كل شيء. فيما يلي قائمة بالخيارات غير المدعومة (قد تتغير في النهاية في المستقبل):

• sourcemap
• خارج
• JSX
• JSXFactory

إنشاء وحدات

الوحدات النمطية في TWC تتبنى بناء الجملة والكلمات الرئيسية للغة TypeScript ، وهي ببساطة فصول. اتفاقيات لمتابعة مطابقة البوليمر 2.x (مواصفات مكونات الويب V1).

@ CustomElement ( )
export class MyElement extends Polymer . Element {
    name : string ;
}

يساوي

 <dom-module id="my-element">
  <script>
    Polymer({
      is: "my-element",
      properties: {
        name: {
          type: String
        }
      }
    });
  </script>
</dom-module>

القولون

هناك 4 طرق لإضافة قالب (لذلك لا يشعر أحد بالملل):

• قدم قالبًا داخل @template Decorator
• قدم مسارًا إلى ملف القالب داخل @template Decorator
• إرجاع قالب من template()
• لا تستخدم أي مما سبق وإنشاء ملف HTML يسمى نفس ملف TS مع المكون

النهج الأول شائع جدًا وربما رأيت هذا عدة مرات. كل ما من شأنه أن يذهب عادة بين علامات <template> ، سوف يذهب الآن إلى الديكور. لا السحر الفاخر هنا.

@ CustomElement ( )
@ template ( `<h1>Hello [[name]]</h1>` )
export class MyElement extends Polymer . Element {
    name : string ;
}

وبالمثل ، فإن النهج الثاني ، تحتاج فقط إلى توفير مسار نسبي للقالب (تمامًا كما ستستورده عبر <link rel="import"> ). يجب أن يكون محتوى ملف القالب كما هو الحال في النهج الأول - الكود بين علامات <template> .

@ CustomElement ( )
@ template ( 'template.html' )
export class MyElement extends Polymer . Element {
    name : string ;
}

إذا كنت تأتي أكثر من عالم React ، فقد يعجبك طريقة render() . لذلك ، هناك طريقة template() تعمل على حد سواء. ميزة هذه الطريقة هي أن لديك إمكانية الوصول إلى النموذج الأولي للفئة ، ويمكنك استخدامها في سلسلة قالب. سيتم استبدال كل this التعبير بربط في اتجاهين للخاصية (إذا كان لديك اقتراح كيفية تحديد وقت استخدام اتجاهين ومتى تستخدم الربط في اتجاه واحد ، فيرجى إخبارنا).

@ CustomElement ( )
export class MyElement extends Polymer . Element {
    name : string ;
    template ( ) {
        return `<h1>Hello ${ this . name } </h1>` ;
    }
}

النهج النهائي هو ترك الفصل كما هو وإنشاء ملف قالب ، مع نفس اسم ملف TS. في وقت الترجمة ، ستقوم TWC بتقاط محتويات الملف وإرفاقها (تمامًا كما هو الحال مع النهج الثاني). كن حذرا رغم ذلك! إذا لم تحدد Outdir ، فقد تحل الوحدات النهائية محل القوالب (افتراضيًا ، ستقوم بإنشاء ملف HTML بنفس الاسم الأساسي).

يرجى ملاحظة أن TWC يستخدم قوالب البوليمر. لقراءة المزيد حول القوالب والربط ، يرجى الرجوع إلى مستندات هذه.

استيراد البرامج النصية ووحدات HTML

واردات ES لا تعمل في المتصفحات حتى الآن. بدلاً من ذلك ، يستخدم البوليمر واردات HTML. يتيح لنا ذلك استخدام علامات <link> لاستيراد الوحدات ، ولكن كيف نفعل ذلك في TWC؟

 import "./my-component.html";

ينطبق نفس المبدأ على البرامج النصية (التي تم تحويلها إلى علامات <script> ):

 import "./some-library.js";

تم تجميع ما سبق إلى

 <link rel="import" href="./my-component.html">

و

 <script src="./some-library.js"></script>

على التوالى.

الواردات من باور

قد يكون التعامل مع المسارات النسبية لمستودعات Bower أو NPM مؤلمة. هذا هو المكان الذي يأتي فيه المستعار في متناول يدي:

 import "bower:polymer/polymer-element.html";
import "npm:jquery/dist/jquery.min.js";

سيتم ترجمة ما سبق لاستخدام دليل Bower من .bowerrc وسيعود إلى bower_components . نظرًا لأن معظم المطورين سيستخدمون polymer-cli لخدمة المكونات ، فسيتم ترجمة مسارات إلى bower_components كما لو كان جذر المشروع داخل هذا المجلد.

إذا كنت بحاجة إلى تغيير أسماء أو مسارات مجلدات NPM أو مسارات NPM أو مساراتها ، فيمكنك القيام بذلك عن طريق تعيين متغيرات بيئة bowerDir و npmDir .

الواردات بالنسبة لجذر المشروع

من الممكن أيضًا استيراد جذر المشروع. فقط أضف ~ أمام المسار:

 import "~demo/index.html";
import "~bower_components/polymer/polymer-element.html";

استيراد أعضاء الوحدة النمطية

لاستيراد أعضاء الوحدات الأخرى (على سبيل المثال استيراد سلوك) ، استخدم واردات ES:

 import { IronControlState } from "bower:iron-behaviors/iron-control-state.html";

إذا كانت هناك مساحة اسم معلنة في التعريفات ، فسيتم ترقية جميع مثيلات العضو المستورد تلقائيًا.

يرجى ملاحظة للسماح للاستيراد من وحدات HTML ، تحتاج إلى إنشاء تعريفات.

توليد أنواع لعناصر/سلوكيات البوليمر

لإنشاء إعلانات النوع من السلوكيات/المكونات الحالية ، استخدم أداة POTTS. ما عليك سوى تثبيته على مستوى العالم ( npm install potts -g ) وقم بتشغيل potts في دليل جذر المشروع. سيتم حفظ التصريحات إلى ملف potts.d.ts افتراضيًا (قابل للتكوين عبر --outFile أو -o علامة). سيؤدي ذلك إلى توليد إعلانات لجميع ملفات HTML الاستماع في القسم main من ملف bower.json من كل اعتماد Bower. سيتم الإعلان عن جميع الوحدات النمطية لتتناسب مع المسار القابل للاستيراد (على سبيل المثال bower:polymer/polymer.html ).

توثيق الأحداث

يجب أن يكون لكل مشروع قوي وثائق مناسبة. ويشمل ذلك أيضًا توثيق الأحداث التي يطلقها المكون. يتيح لك TWC القيام بذلك بسهولة عن طريق إنشاء واجهة تمتد Event أو CustomEvent .

 /** My custom event, which fires when needed */
export interface SomeEvent extends CustomEvent {
  detail: {
    /** Property inside event.detail */
    myCustomProp: string;
  };
}

القيم الافتراضية للخصائص

سيتم استخدام أي قيمة تم تعيينها مباشرة على إعلان الخصائص كقيمة افتراضية. سيتم لف أي قيمة بدائية (صفيف ، كائن ، إلخ) بوظيفة:

 export class MyElement {
    title : string = '' ;
    categories : Array = [ ] ;
}

سوف تترجم إلى

 Polymer ( {
    properties : {
        title : {
            type : string ,
            value : ''
        } ,
        categories : {
            type : Array ,
            value : function ( ) {
                return [ ] ;
            }
        }
    }
} ) ;

الخصائص الخاصة

لا ينبغي إضافة كل شيء إلى تكوين properties . لتخطي هذه العملية ، يجب تعريف الممتلكات على أنها خاصة:

 export class MyElement {
    name : string ; // is added to properties config
    private hasName : boolean ; // is NOT added to properties config
}

خصائص قراءة

لا يمكن القيام بكل شيء في البوليمر باستخدام الكلمات الرئيسية TypeScript ، ولكن قراءة خاصية فقط هي سهلة مثل البادئة readonly :

 export class MyElement {
    readonly name : string ; // property will have `readOnly` flag
}

Mixins

يتم دعم Mixins ES منذ TypeScript 2.2. يمكنك قراءة المزيد عنها هنا.

لا يتم دعم Mixins بواسطة Polymer V1

السلوكيات

السلوكيات هي النهج الأول لمشاركة وظائف في البوليمر (تم استبداله الآن بـ ES mixins). يتم تعريفها على أنها كائنات عادية مع خصائص البوليمر والأساليب المدرجة كما هو الحال مع كائن تكوين البوليمر V1. لإضافة سلوك ، استخدم Polymer.mixinBehaviors() mixin (مزيد من المعلومات هنا). بالنسبة إلى Polymer V1 ، سيتم إضافتها إلى Config Config ، بينما سوف يستخدمها Polymer V2 مع Mixin أعلاه.

ديكور

كما ذكرنا من قبل ، لا يمكن القيام بكل شيء بالكلمات الرئيسية. لهذا السبب يأتي TWC مع مجموعة من التعليقات التوضيحية لوقت التصميم.

لاستخدامها ، قم بتثبيت TWC محليًا واستيراد ملفات مصدر العناصر حسب الحاجة:

 import { attr , compute , notify , observe , style , template } from 'twc/polymer' ; 

@نموذج

لإعطاء المكون جسمًا ، تحتاج إلى تزويده بقالب. يتم ذلك باستخدام التعليق @template ، الذي يقبل إما رمز قالب HTML ، أو مسار إلى قالب HTML (يجب أن يكون. تمديد .html ).

@ template ( `<h1>Hello {{name}}</h1>` )
export class MyElement {
    name : string ;
} 

@ template ( `template.html` )
export class MyElement {
    name : string ;
} 

@أسلوب

تصفيف المكون سهل مثل إعطائه قالبًا. @style annotation يقبل رمز CSS أو مسار ملف CSS أو اسم النمط المشترك. يمكن توفير أنماط متعددة إلى مكون واحد.

@ template ( `<h1>Hello {{name}}</h1>` )
@ style ( `:host {display: block;}` , `style.css` , `shared-styles` )
export class MyElement {
    name : string ;
} 

ATTR و notify

@attr و @notify إضافة reflectToAttribute notify الأعلام properties التكوين.

 export class MyElement {
    @ attr ( ) name : string ; // property will have `reflectToAttribute` flag
    @ notify ( ) age : number ; // property will have `notify` flag
} 

compute

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

 export class MyElement {
    name : string ;
    age : number ;
    cards : Array < string > ;

    // Responds to `name` changes. Property name taken from function argument.
    @ compute ( ( name : string ) => `Hi, I am ${ name } ` ) greetings : string ;

    // Responds to `age` changes. Property name taken from an array.
    @ compute ( ( value : number ) => value >= 18 , [ "age" ] ) isAdult : boolean ;

    // Responds to both `age` and `name` changes.
    @ compute ( ( age : number , name : string ) => ` ${ name } is ${ age } years old` ) aboutMe : string ;

    // Responds to length of `cards` array changes. As dependency is a path, it has to be added to an array.
    @ compute ( ( size ) => size , [ "cards.length" ] ) collectionSize : number ;

    // Responds to name and length of `cards` array changes. Resolver method is provided by name.
    @ compute ( '_summary' , [ "name" , "cards.length" ] ) summary : string ;

    private _summary ( name , collectionSize ) {
        return ` ${ name } has ${ collectionSize } cards` ;
    }
} 

@يراقب

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

 export class MyElement {
    name : string ;
    cards : Array < string > ;

    // Responds to name and length of `cards` array changes.
    @ observe ( "name" , "cards.length" ) summary ( name , collectionSize ) {
        console . log ( ` ${ name } cards collection size changed to ${ collectionSize } cards` ;
    }
} 

المزيد في المستقبل!

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

خريطة الطريق

• تحذير من استخدام خاصية/اسم الطريقة (مثل classList )
• السماح للتعبيرات في القوالب
• استيراد واجهات الأحداث (لتجنب التجديد
• اجعل الواردات النسبية لا تحطم إذا قام Outdir بتغيير بنية الملفات
• توليد خرائط مصدر صالحة
• قم بإنشاء ديكورات وسير عمل متوافقة مع Polymerts

إجراء اختبارات على Windows

لتشغيل الاختبارات على Windows ( npm run test ) ، من الضروري حاليًا تعديل قسم include ملف tsconfig.json بحيث يحتوي على النمط أدناه:

{
  "include" : [
    " node_modules/@types/**/*.d.ts "
  ]
}