twc
0.5.1
Les composants Web dactylographiques vous apportent une manière basée sur les puiseurs et basée sur les dactylographies pour écrire des modules de polymère natifs (polymère Toolbox Friendly). L'ensemble du processus se fait dans le temps de conception, donc aucune dépendance supplémentaire ne doit être ajoutée au projet.
npm install -g twc
TWC est livré avec la CLI. La majeure partie de sa configuration provient de tsconfig (et bower.json ), et elle fonctionne à peu près de la même manière que TSC. Pour transformer les classes TS en modules de polymère natifs, entrez simplement dans le Dir du projet et exécutez ce qui suit dans le terminal:
twc
Il fonctionne tout aussi tsc , lisant la configuration du fichier tsconfig.json . La seule différence est qu'il publie des fichiers .html avec module polymère au lieu de .js plaine.
Les annotations seront disponibles sur l'espace de noms @types npm. Jusqu'à ce que cela se produise, les types doivent être inclus dans TSConfig:
{
"compilerOptions": {
...
},
"files": [
...
],
"include": [
"node_modules/twc/types/polymer.decorators.d.ts"
]
}
TWC permet de compiler le même code dans le polymère 1.x ou le polymère 2.x. Avant la compilation, bower.json est vérifié pour la version de dépendance au polymère, puis il est utilisé comme cible. Par exemple:
"polymer": "Polymer/polymer#^1.8.0"
Construirea un module polymère 1.x, tandis que celui-ci:
"polymer": "Polymer/polymer#^2.0.0"
Construit un module Polymer 2.x basé sur ES6.
Les options de compilateur TypeScript sont également disponibles pour TWC, tout n'est pas pris en charge. Voici une liste d'options non soutenues (pourrait éventuellement changer à l'avenir):
Les modules de TWC embrassent la syntaxe et les mots clés du langage TypeScript et ne sont que des classes. Les conventions à suivre correspondent au polymère 2.x (V1 Web Components Spec).
@ CustomElement ( )
export class MyElement extends Polymer . Element {
name : string ;
}égal
<dom-module id="my-element">
<script>
Polymer({
is: "my-element",
properties: {
name: {
type: String
}
}
});
</script>
</dom-module>
Il y a 4 façons d'ajouter un modèle (donc personne ne s'ennuie):
@template@templatetemplate() La première approche est très courante et vous l'avez probablement vu plusieurs fois. Tout ce qui irait normalement entre les balises <template> , irait maintenant dans le décorateur. Pas de magie fantaisie ici.
@ CustomElement ( )
@ template ( `<h1>Hello [[name]]</h1>` )
export class MyElement extends Polymer . Element {
name : string ;
} De même, la deuxième approche, il vous suffit de fournir un chemin relatif vers le modèle (tout comme vous l'importeriez via <link rel="import"> balise). Le contenu du fichier de modèle doit être comme dans la première approche - code entre <template> TAGS.
@ CustomElement ( )
@ template ( 'template.html' )
export class MyElement extends Polymer . Element {
name : string ;
} Si vous venez plus d'un monde React, vous aimerez peut-être la méthode render() . Le voici donc, une méthode template() qui fonctionne très semblable. L'avantage de cette méthode est que vous avez accès au prototype de classe et que vous pouvez l'utiliser dans une chaîne de modèle. this expression sera remplacée par une liaison bidirectionnelle à la propriété (si vous avez une suggestion de déterminer quand utiliser bidirectionnel et quand utiliser la liaison unidirectionnelle, veuillez me le faire savoir).
@ CustomElement ( )
export class MyElement extends Polymer . Element {
name : string ;
template ( ) {
return `<h1>Hello ${ this . name } </h1>` ;
}
}L'approche finale consiste à quitter la classe telleans et à créer un fichier de modèle, avec le même nom que le fichier TS. Au moment de la compilation, TWC ramassera le contenu du fichier et le joignera (comme avec la deuxième approche). Soyez prudent cependant! Si vous ne spécifiez pas OutDIR, les modules finaux peuvent remplacer les modèles (par défaut, il générera un fichier HTML par le même nom de base).
Veuillez noter que TWC utilise des modèles de polymère. Pour en savoir plus sur les modèles et la liaison, veuillez vous référer à ces documents.
Les importations ES ne fonctionnent pas encore dans les navigateurs. Polymer utilise plutôt les importations HTML. Cela nous permet d'utiliser des balises <link> pour importer des modules, mais comment faire cela dans TWC?
import "./my-component.html";
Le même principe s'applique aux scripts (converti en balises <script> ):
import "./some-library.js";
Les ci-dessus sont compilés pour
<link rel="import" href="./my-component.html">
et
<script src="./some-library.js"></script>
respectivement.
La gestion des chemins relatives des référentiels Bower ou NPM pourrait être douloureux. C'est là que les alias sont utiles:
import "bower:polymer/polymer-element.html";
import "npm:jquery/dist/jquery.min.js";
Ce qui précède sera traduit pour utiliser le répertoire Bower à partir de .bowerrc et retombera à bower_components . Comme la plupart des développeurs utiliseront polymer-cli pour servir les composants, les chemins de bower_components seront traduits par si la racine du projet était à l'intérieur de ce dossier.
Si, pour une raison quelconque, vous devez modifier les noms ou chemins de dossiers NPM ou Bower, vous pouvez le faire en définissant des variables d'environnement bowerDir et npmDir .
Il est également possible d'importer par rapport à la racine du projet. Ajoutez simplement un ~ devant le chemin:
import "~demo/index.html";
import "~bower_components/polymer/polymer-element.html";
Pour importation des membres d'autres modules (par exemple l'importation d'un comportement), utilisez les importations ES:
import { IronControlState } from "bower:iron-behaviors/iron-control-state.html";
S'il y a un espace de noms déclaré dans les définitions, il mettra automatiquement à moderniser toutes les instances de membre importé.
Veuillez noter pour permettre l'importation de modules HTML, vous devez générer des définitions.
Pour générer les déclarations de type à partir de comportements / composants existants, utilisez l'outil Potts. Installez-le simplement globalement ( npm install potts -g ) et exécutez potts dans le répertoire Root Project. Les déclarations seront enregistrées dans le fichier potts.d.ts par défaut (Configurable via --outFile ou -o indicateur). Cela générera des déclarations pour tous les fichiers HTML à écouter dans la section main du fichier bower.json de chaque dépendance de bower. Tous les modules seront déclarés pour correspondre au chemin imporable (par exemple bower:polymer/polymer.html ).
Chaque projet solide doit avoir une documentation appropriée. Cela comprend également la documentation des événements tirés par le composant. TWC vous permet de le faire facilement en créant une interface qui étend Event ou CustomEvent .
/** My custom event, which fires when needed */
export interface SomeEvent extends CustomEvent {
detail: {
/** Property inside event.detail */
myCustomProp: string;
};
}
Toute valeur définie directement sur la déclaration de propriétés sera utilisée comme valeur par défaut. Toute valeur non primitive (tableau, objet, etc.) sera enveloppée d'une fonction:
export class MyElement {
title : string = '' ;
categories : Array = [ ] ;
}se traduira par
Polymer ( {
properties : {
title : {
type : string ,
value : ''
} ,
categories : {
type : Array ,
value : function ( ) {
return [ ] ;
}
}
}
} ) ; Tout ne doit pas être ajouté à la configuration properties . Pour ignorer ce processus, la propriété doit être définie comme privée:
export class MyElement {
name : string ; // is added to properties config
private hasName : boolean ; // is NOT added to properties config
} Tout dans Polymer ne peut pas être fait avec des mots clés TypeScript, mais la propriété de lecture uniquement est aussi simple que de préfixer en readonly :
export class MyElement {
readonly name : string ; // property will have `readOnly` flag
}Les mélanges ES sont pris en charge depuis TypeScript 2.2. Vous pouvez en savoir plus à leur sujet ici.
Les mélanges ne sont pas pris en charge par le polymère v1
Les comportements sont la première approche pour partager les fonctionnalités dans le polymère (désormais remplacées par des mélanges ES). Ils sont définis comme des objets simples avec des propriétés et des méthodes de polymère répertoriées comme avec l'objet Polymer V1 Config. Pour ajouter un comportement, utilisez le mixin Polymer.mixinBehaviors() (plus d'informations ici). Pour Polymer V1, ils seront ajoutés à la configuration des comportements, tandis que le polymère V2 les utilisera avec le mélange ci-dessus.
Comme mentionné précédemment, tout ne peut pas être fait avec des mots clés. C'est pourquoi TWC est livré avec un ensemble d'annotations en temps de conception.
Pour les utiliser, installez TWC localement et importez dans les fichiers source des éléments selon les besoins:
import { attr , compute , notify , observe , style , template } from 'twc/polymer' ; Pour donner un corps à votre composant, vous devez lui fournir un modèle. Cela se fait à l'aide de l'annotation @template , qui accepte soit du code de modèle HTML, soit un modèle de chemin vers HTML (doit avoir une extension .html ).
@ template ( `<h1>Hello {{name}}</h1>` )
export class MyElement {
name : string ;
} @ template ( `template.html` )
export class MyElement {
name : string ;
} Le style du composant est aussi simple que de lui donner un modèle. @style Annotation accepte le code CSS, le chemin de fichier CSS ou le nom de style partagé. Plusieurs styles peuvent être fournis à un seul composant.
@ template ( `<h1>Hello {{name}}</h1>` )
@ style ( `:host {display: block;}` , `style.css` , `shared-styles` )
export class MyElement {
name : string ;
} @attr et @notify Ajouter reflectToAttribute et notify les drapeaux aux properties Config.
export class MyElement {
@ attr ( ) name : string ; // property will have `reflectToAttribute` flag
@ notify ( ) age : number ; // property will have `notify` flag
} Les propriétés calculées sont des propriétés qui combinent une ou plusieurs dépendances (propriétés regardées). Chaque fois que l'une des dépendances change, la méthode de la propriété calculée se déclenche et le résultat retourné est attribué à la propriété. Plus d'informations ici. TWC permet de les créer de 2 manières: en fournissant un nom de fonction et des dépendances, ou en passant directement une fonction de résolveur (dans ce cas, les dépendances peuvent être transmises dans un tableau de chaînes, ou comme arguments de fonction).
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` ;
}
} Vous pouvez réagir à toutes les modifications de propriété ou de chemin non seulement par les propriétés calculées, mais aussi par les observateurs. L'observateur ne renvoie rien et c'est la seule différence entre eux.
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` ;
}
} Les composants Web typés sont dans une phase précoce et ont besoin de vos commentaires. Veuillez l'essayer et si vous trouvez un problème, postez-le dans les problèmes. N'hésitez pas non plus à publier également des idées!
classList ) Pour exécuter des tests sur Windows ( npm run test ), il est actuellement nécessaire de modifier la section include du fichier tsconfig.json afin qu'il contient le modèle ci-dessous:
{
"include" : [
" node_modules/@types/**/*.d.ts "
]
}
