Polymer 3.0. Основные изменения
В данное время Polymer 3.0 доступен в режиме предпросмотра для экспериментирования и сегодня я покажу как можно начать с ним работу.
Настройка
Перед началом работы, обновим Polymer CLI до последней версии.
npm install -g polymer-cli
Также нужно установить менеджер пакетов Yarn (см. установка Yarn).
Наконец, нужен Chrome 61 или позже версии и Safari 10.1 для запуска предпросмотра кода.
Установка зависимостей с помощью Yarn
Компоненты Polymer публикуются в репозитории npm под @polymer
неймспейсом. Используйте Yarn для установки компонентов.
Еще нет шаблонов polymer init
для Polymer 3.0, поэтому нужно создать проект с нуля.
Создаём Polymer 3.0 проект:
- Инициализация. Создадим новую папку и запустите в ней
yarn init
.
mkdir polymer3 && cd polymer3
yarn init
Дайте ответ на запрос командной строки для установки проекта (в большинстве случаев выбирайте всё по-умолчанию).
- Отредактируем
package.json
файл и добавим параметр"flat": true
.
{
"name": "my-app",
"flat": true,
...
- Добавим компоненты, используя
yarn add
, это эквивалент использовавшейся ранее командыbower install --save
. Например:
yarn add @polymer/polymer@next
yarn add @webcomponents/webcomponentsjs
Любые ранее установленные компоненты из организации Polymer
или PolymerElements
с помощью Bower, теперь вы можете устанавливать используя @polymer
неймспейс. Обязательно включите @next
для того, чтобы получить пакеты для версии 3.0.
Вы можете установить полифилы из @webcomponents/webcomponentsjs
(тут не нужно использовать@next
, так как вы будете использовать существующую версию полифилов).
Альтернативы yarn установке
Если у вас есть другие npm зависимости, такие как серверы, инструменты разработки или компайлеры, установка flat
можеть стать причиной конфликтов. В этом случае у вас есть пара опций:
- Устанавливайте веб-компоненты с ключем
--flat
.
Уберите параметр "flat": true
из файла package.json
и добавьте флаг --flat
, когда добавляете фронтэнд компоненты.
yarn add --flat @polymer/polymer@next
Для существующего проекта с файлом package.json
этот способ наиболее удачный.
Преимущество его в том, что все зависимости в одной папке node_modules
, но это значит, что каждый раз вы должны добавлять флаг --flat
каждый раз, когда вы устанавливаете компонент.
- Используйте отдельные папки.
Другой альтернативой установочному файлу package.json
в корневой папке "flat": true
и добавление подпапки (например, tools
) с собственным файлом package.json
для пакетов, которым нужны вложенные зависимости.
Использование модулей
Существует много информации про ES6 модули, так что если вы не знакомы с ними, то можете загуглить, тут будет сказано лишь о нескольких основных фичах.
Хорошо рассказано о модулях в этой главе от Exploring ES6 автор Dr. Axel Rauschmayer.
Также можете просмотреть выступление Sam Thorogood по модулям ES6 на конференции Polymer Summit.
Импорт зависимостей
Вы можете импортировать модуль HTML используя <script type="module">
. Например, ваш файлindex.html
может выглядеть так:
<!doctype html>
<html>
<head>
<!-- Load polyfills. Same as 2.x, except for the path -->
<script
src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js">
</script>
<!-- Import the my-app element's module. -->
<script type="module" src="src/my-app.js"></script>
</head>
<body>
<my-app></my-app>
</body>
</html>
Всередине модуля вы можете импортировать модуль используя выражение:
import {Element as PolymerElement}
from "../node_modules/@polymer/polymer/polymer-element.js"
Что схоже на зависимости Bower, повторно используемые элементы не должны включать node_modules в свой путь (например ../@polymer/polymer/polymer-element.js).
Есть несколько вещей, на которые следует обратить внимание, когда работаете с модулями и их импортом:
Как и HTML импорты, они должны использовать путь, а не имя модуля.
Путь у импорта, должен начинаться с “./”, “../”, или “/”.
Выражение импорта может использоваться только всередине модуля (который является внешним файлом или инлайн скриптом, который загружается через
import "../@polymer/paper-button/paper-button.js"
Для поведений, вы импортируете для поведения дополнительно:
import {IronResizableBehavior}
from "../@polymer/iron-resizable-behavior/iron-resizable-behavior.js"
Для использования таких модулей как Async
, который экспортирует несколько членов, вы можете импортировать индивидуальные члены или импортировать целый модуль:
import * as Async from "../@polymer/polymer/lib/utils/async.js"
Async.microTask.run(callback);
Различные модули структурированны по-разному; пока нет документации по 3.0, вам нужно будет смотреть в исходный код, чтобы узнать что экспортирует модуль.
Динамические импорты: пока не совсем готово
There’s a specification for dynamic imports using the import()
operator but it hasn’t quite landed yet. The import operator acts like a function, and returns a Promise
:
import('my-view1.js').then((MyView1) => {
console.log("MyView1 loaded");
}).catch((reason) => {
console.log("MyView1 failed to load", reason);
});
Текущие Polymer CLI инструменты не поддерживать трансформирующиеся динамические импорты, поэтому вы пока что не сможете применять паттерны с “ленивой” загрузкой, такие как PRPL в 3.0.
Если вы используете пользовательскую установку с помощью инструмента типа Webpack, то вы можете использовать динамические импорты уже сегодня, но это не входит в сегодняшний пост.
Определение элементов
Вместо определения элементов в HTML импортах, вы определяете элементы в ES6 модулях. Кроме того, что вы теперь пишете в JS файл вместо HTML файла, есть ещё три главных отличия нового формата:
- Импорты используют синтаксис импорта ES6, а не
<link rel="import">
. - Шаблоны определяются геттером
template
, который возвращает строку, а не<dom-module>
и<template>
элементы. - Вместо определения глобалов (например, при определении поведений или миксинов) используйте выражение
export
для экспорта символов из модулей.
Например:
my-app.js
// Такой же элемент как и Polymer.Element в 2.x
// Модули дают вам возможность переименовывать членов, которые вы импортируете
import {Element as PolymerElement}
from '../node_modules/@polymer/polymer/polymer-element.js';
// Добавлен "export" для экспорта символа MyApp из модуля класса экспорта
export class MyApp extends PolymerElement {
// Определение шаблона строки вместо элемента `<template>`.
static get template() {
return `<div>This is my app.</div>`
}
constructor() {
super();
this.name = '3.0 preview';
}
// свойства, обзерверы и другое идентичны с версией 2.x
static get properties() {
name: {
Type: String
}
}
}
customElements.define('my-app', MyApp);
Как видите, кроме изменений указанных выше, определения элементов выглядят так же как и в 2.x. Таким образом есть несколько изменений в 2.x API, которые связаны с динамическим импортом: в частности, функция Polymer.importHref
больше не поддерживается; это связано с её заменой динамическими ES6 импортами.
Для переиспользуемых элементов, импорт класса Polymer Element
будет не включать в себя папку node_modules
:
import {Element as PolymerElement}
from '../@polymer/polymer/polymer-element.js';
Предпросмотр проектов
Используйте новый флаг --npm
для предпросмотра или тестирования проектов.
polymer serve --npm
polymer test --npm
Флаг указывает серверу загрузить компоненты из node_modules
вместо bower_components
и для поиска имени пакета в package.json
вместо bower.json
.
Убедитесь, что вы загружаете ваши проекты в Safari 10.1 или Chrome 61 или позже. CLI не делает конверсию модулей в данное время, поэтому 3.0 только работает на браузерах, у которых есть нативная поддержка модулей.
Обновление существующих проектов
Инструмент Polymer Modulizer обновляет Polymer 2.x проекты к npm и ES6 модульному формату Polymer 3.0. Этот инструмент находится на очень ранней стадии. Существует множество известных проблем, которые должны быть решены за несколько других недель. Поэтому если у вас возникнут проблемы - не волнуйтесь, команда гугл активно работает над ней. Документация Modulizer README в помощь. Можете также присоединится к каналу #modulizer
на Slack если у вас есть вопросы по Polymer Modulizer.