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 проект:

  1. Инициализация. Создадим новую папку и запустите в ней yarn init.
mkdir polymer3 && cd polymer3
yarn init

Дайте ответ на запрос командной строки для установки проекта (в большинстве случаев выбирайте всё по-умолчанию).

  1. Отредактируем package.json файл и добавим параметр "flat": true.
{
  "name": "my-app",
  "flat": true,
  ...
  1. Добавим компоненты, используя 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.

Оригинал новости