Polymer 2.x to 3.x переход

Polymer 3.x представляет собой значительное обновление по сравнению с 2.x, главным образом за счет полной интеграции ES-модулей, отказа от HTML Imports и улучшенной совместимости с современными инструментами сборки и пакетными менеджерами. Понимание этих изменений критично для миграции существующих проектов.

Использование ES-модулей

В Polymer 2.x компоненты часто определялись с помощью HTML Imports и <link rel="import">. В версии 3.x эти импорты заменены на стандартные ES-модули Jav * aScript:

import { PolymerElement, html } from '@polymer/polymer/polymer-element.js';

class MyElement extends PolymerElement {
  static get template() {
    return html`
      <div>Пример элемента</div>
    `;
  }
}

customElements.define('my-element', MyElement);

Ключевые моменты перехода:

  • Каждая библиотека и компонент должны быть импортированы через import.
  • HTML Templates и стили должны быть инкапсулированы в JavaScript.
  • Старые пути через <link rel="import"> больше не поддерживаются.

Обновление шаблонов

Polymer 3.x использует функцию html для определения шаблонов внутри JavaScript. Старый синтаксис с <dom-module> и атрибутом id полностью устарел. Пример старого шаблона:

<dom-module id="my-element">
  <template>
    <div>Содержимое</div>
  </template>
</dom-module>

В 3.x это преобразуется в:

static get template() {
  return html`
    <div>Содержимое</div>
  `;
}

Шаблон становится частью класса элемента, что упрощает поддержку и сборку модулей через современные инструменты.

Работа со свойствами

В Polymer 2.x свойства объявлялись через объект properties. В 3.x это остается практически без изменений, но важным становится использование ES6-символов и методов для вычисляемых свойств и наблюдателей. Пример:

static get properties() {
  return {
    prop1: {
      type: String,
      value: 'значение по умолчанию'
    },
    prop2: {
      type: Number,
      computed: '_computeProp2(prop1)'
    }
  };
}

_computeProp2(prop1) {
  return prop1.length;
}

Модули и пакеты

В Polymer 3.x компоненты упаковываются как NPM-пакеты. Это позволяет использовать стандартные инструменты сборки:

  • Rollup и Webpack для сборки ES-модулей.
  • Babel для транспиляции кода для поддержки старых браузеров.
  • Управление зависимостями через package.json.

Старые HTML Imports больше не поддерживаются, поэтому все сторонние компоненты должны быть установлены через NPM и импортированы как модули.

Стили и Shadow DOM

Polymer 3.x полностью интегрирован с Shadow DOM и CSS Custom Properties. Основные моменты:

  • Стилевые шаблоны переносятся внутрь функции html.
  • Переменные CSS применяются напрямую через style внутри шаблона или через :host селектор.
  • Поддержка старого polymer-style устарела, необходимо использовать современные подходы к инкапсуляции стилей.

Пример стилей в шаблоне:

static get template() {
  return html`
    <style>
      :host {
        display: block;
        color: var(--primary-text-color, black);
      }
      .container {
        padding: 16px;
      }
    </style>
    <div class="container">Контент элемента</div>
  `;
}

Обновление событий и методов

Методы и события в 3.x используют стандартные DOM API. Изменения:

  • this.fire('event-name', detail) заменяется на this.dispatchEvent(new CustomEvent('event-name', { detail, bubbles: true, composed: true })).
  • Синтаксис слушателей событий через атрибуты on-click в шаблонах поддерживается, но рекомендуется использовать стандартный addEventListener.

Миграция сторонних компонентов

Для перехода сторонних компонентов с 2.x на 3.x:

  1. Найти NPM-пакет с версией 3.x или выше.
  2. Импортировать компонент через import.
  3. Проверить поддержку Shadow DOM и CSS Custom Properties.
  4. Переписать устаревшие методы событий и наблюдателей.

Инструменты для автоматизации миграции

Существуют скрипты и инструменты, облегчающие конвертацию HTML Imports в ES-модули:

  • polymer-modulizer — официальное средство для преобразования проекта.
  • polymer-cli с командой polymer build для подготовки к сборке через NPM.

Важные нюансы

  • Polymer 3.x требует браузеры с поддержкой ES-модулей. Для старых браузеров необходимы полифиллы.
  • Структура проекта изменяется: папка с компонентами превращается в пакет с package.json.
  • Все зависимости должны быть указаны в dependencies или devDependencies для корректной работы сборки.

Переход с 2.x на 3.x — это не только синтаксическое обновление, но и переработка архитектуры проекта для соответствия современным стандартам модульности, совместимости и управляемости зависимостей.

Оглавление