twc
0.5.1
Напечатанные веб-компоненты представляют вам путь, основанный на шейке, для написания нативных полимерных модулей (полимерный набор инструментов, дружественный). Весь процесс выполняется во время проектирования, поэтому в проект не нужно добавлять никакой дополнительной зависимости.
npm install -g twc
TWC приходит с CLI. Большая часть его конфигурации поступает от tsconfig (и bower.json ), и она в значительной степени работает так же, как TSC. Чтобы преобразовать классы TS в нативные полимерные модули, просто введите проект root dir и выполните следующее в терминале:
twc
Он работает так же, как tsc , чтение конфигурации из файла tsconfig.json . Единственная разница в том, что он выводит файлы .html с полимерным модулем вместо простых .js
Аннотации будут доступны в пространстве имен @types NPM. Пока это не произойдет, типы должны быть включены в 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 также доступны для TWC, хотя не все поддерживается. Вот список неподдерживаемых вариантов (может в конечном итоге измениться в будущем):
Модули в 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@templatetemplate() Первый подход очень распространен, и вы, вероятно, видели это несколько раз. Все, что обычно проходило между <template> тегами, теперь попадет в декоратор. Здесь нет причудливой магии.
@ CustomElement ( )
@ template ( `<h1>Hello [[name]]</h1>` )
export class MyElement extends Polymer . Element {
name : string ;
} Точно так же второй подход, вам просто нужно предоставить относительный путь к шаблону (так же, как вы импортируете его через <link rel="import"> Tag). Содержание файла шаблона должно быть таким, как в первом подходе - код между тегами <template> .
@ CustomElement ( )
@ template ( 'template.html' )
export class MyElement extends Polymer . Element {
name : string ;
} Если вы приезжаете больше из мира реагирования, вам может понравиться метод render() . Итак, здесь, метод template() который работает очень похож. Преимущество этого метода состоит в том, что у вас есть доступ к прототипу класса, и вы можете использовать его в строке шаблона. Каждое this выражение будет заменено двусторонним привязкой с свойством (если у вас есть предложение, как определить, когда использовать двустороннюю и когда использовать одностороннее привязка, пожалуйста, дайте мне знать).
@ CustomElement ( )
export class MyElement extends Polymer . Element {
name : string ;
template ( ) {
return `<h1>Hello ${ this . name } </h1>` ;
}
}Окончательный подход заключается в том, чтобы оставить класс как есть, и создать файл шаблона с тем же именем, что и файл TS. Во время компиляции TWC заберут содержимое файла и прикрепит его (как и во втором подходе). Будьте осторожны, хотя! Если вы не указаете Outdir, конечные модули могут заменить шаблоны (по умолчанию, он будет генерировать файл HTML с тем же базовым именем).
Обратите внимание, что TWC использует полимерные шаблоны. Чтобы узнать больше о шаблонах и привязке, обратитесь к этим документам.
Импорт 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 или Bower, вы можете сделать это, установив переменные среды bowerDir и npmDir .
Также возможно импортировать по сравнению с Project Root. Просто добавьте ~ перед пути:
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 в каталоге Project Root. Объявления будут сохранены в файле 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
}ES Mixins поддерживаются с тех пор, как TypeScript 2.2. Вы можете прочитать больше о них здесь.
Микшины не поддерживаются полимером V1
Поведение является первым подходом к функциональности совместного использования в полимере (теперь заменен на ES Mixins). Они определяются как простые объекты со свойствами полимера и методами, перечисленными так же, как и в случае с объектом конфигурации Polymer V1. Чтобы добавить поведение, используйте MixIn Polymer.mixinBehaviors() (больше информации). Для Polymer V1 они будут добавлены в конфигурацию поведения, в то время как Polymer V2 будет использовать их с вышеупомянутым микшином.
Как упоминалось ранее, не все можно сделать с помощью ключевых слов. Вот почему 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 добавить reflectToAttribute и notify флаги на конфигурацию properties .
export class MyElement {
@ attr ( ) name : string ; // property will have `reflectToAttribute` flag
@ notify ( ) age : number ; // property will have `notify` flag
} Вычисленные свойства - это свойства, которые объединяют одну или несколько зависимостей (наблюдаемые свойства). Всякий раз, когда какое -либо из изменений зависимости, вычисляемое метод свойства и возвращаемый результат назначается свойству. Больше информации здесь. 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 ) Чтобы запустить тесты в Windows ( npm run test ), в настоящее время необходимо изменить раздел include раздел tsconfig.json , поэтому он содержит шаблон ниже:
{
"include" : [
" node_modules/@types/**/*.d.ts "
]
}
