Структура проекта Polymer

Проект на Polymer организуется вокруг веб-компонентов, каждый из которых представляет собой самостоятельный элемент интерфейса. Фреймворк поощряет модульность и повторное использование кода, что напрямую отражается на структуре проекта.

Папки и файлы

Типичная структура проекта выглядит следующим образом:

my-app/
├── index.html
├── package.json
├── bower.json
├── src/
│   ├── components/
│   │   ├── my-element/
│   │   │   ├── my-element.html
│   │   │   └── my-element.js
│   │   └── shared-styles.html
│   ├── app-shell.html
│   └── main.js
├── node_modules/
└── bower_components/

Разбор структуры:

  • index.html — основной файл приложения. Обычно содержит <app-root> или главный контейнер приложения и подключение скриптов.

  • package.json — управление зависимостями Node.js, сборкой и скриптами.

  • bower.json — управление фронтенд-зависимостями, такими как сам Polymer и сторонние элементы.

  • src/ — исходные файлы проекта.

    • components/ — каталог всех кастомных компонентов.

      • Каждый компонент располагается в отдельной папке и содержит HTML-шаблон и скрипт с логикой.

    • shared-styles.html — общий CSS для повторного использования в разных компонентах.

    • app-shell.html — каркас приложения, содержащий маршрутизацию, навигацию и основной layout.

    • main.js — точка входа для инициализации приложения, регистрации сервисов и компонентов.

  • node_modules/ и bower_components/ — каталоги зависимостей.

Веб-компоненты

Каждый компонент в Polymer строится на основе класса, расширяющего PolymerElement. Основные элементы компонента:

  • HTML-шаблон: <template> с разметкой и стилями.

  • Скрипт: определяет поведение и свойства компонента.

  • Свойства (properties): определяют реактивные данные.

  • Методы жизненного цикла:

    • connectedCallback() — вызывается при добавлении элемента в DOM.
    • disconnectedCallback() — вызывается при удалении из DOM.
    • ready() — инициализация после первого рендеринга.

Пример структуры компонента:

<dom-module id="my-element">
  <template>
    <style include="shared-styles">
      :host {
        display: block;
        color: var(--primary-text-color);
      }
    </style>
    <div>{{greeting}}</div>
  </template>
  <script>
    import { PolymerElement, html } from '@polymer/polymer/polymer-element.js';
    
    class MyElement extends PolymerElement {
      static get properties() {
        return {
          greeting: {
            type: String,
            value: 'Привет, мир!'
          }
        };
      }
    }

    customElements.define('my-element', MyElement);
  </script>
</dom-module>

Стилизация

Polymer поддерживает Shadow DOM, что обеспечивает изоляцию стилей компонентов. Общие стили подключаются через <style include="shared-styles">. Для глобальных переменных CSS используют custom properties:

:root {
  --primary-color: #6200ee;
  --primary-text-color: #ffffff;
}

Использование переменных в компоненте:

div {
  background-color: var(--primary-color);
  color: var(--primary-text-color);
}

Организация маршрутизации

Проекты с большим количеством страниц используют App Router или кастомные решения с <iron-pages> и <app-route>. Каркас приложения (app-shell.html) содержит маршруты и определяет, какой компонент отображать в зависимости от URL.

<app-route route="{{route}}" pattern="/:page" data="{{routeData}}" tail="{{subroute}}"></app-route>
<iron-pages selected="[[routeData.page]]" attr-for-selected="name">
  <home-page name="home"></home-page>
  <about-page name="about"></about-page>
</iron-pages>

Рекомендации по организации проекта

  • Каждый компонент должен быть самодостаточным и иметь свою папку.
  • Общие элементы и стили лучше выносить в отдельные файлы для повторного использования.
  • Минимизировать глобальные зависимости — использовать локальные импорты компонентов.
  • Структурировать папки по смыслу: components/ для UI, services/ для бизнес-логики, pages/ для страниц.

Инструменты сборки и зависимости

Polymer использует Bower и npm для управления зависимостями, а для сборки — Polymer CLI. Полезные команды:

  • polymer init — создание нового проекта.
  • polymer serve — локальный сервер разработки.
  • polymer build — оптимизация и сборка проекта для продакшена.

Система сборки генерирует оптимизированные HTML, JS и CSS файлы с минификацией, объединением скриптов и полифилами для браузеров, не поддерживающих Shadow DOM.

Взаимодействие компонентов

Компоненты общаются через:

  • Свойства (properties) — для передачи данных сверху вниз.
  • События (CustomEvent) — для уведомления родителя о действиях.
  • Слоты (<slot>) — для вставки контента в шаблон компонента.

Пример передачи данных и события:

<child-element message="Привет!" on-action="handleAction"></child-element>
this.dispatchEvent(new CustomEvent('action', { detail: { value: 42 } }));

Итоговая структура масштабного проекта

Для крупных приложений структура может быть расширена так:

src/
├── components/
├── pages/
├── services/
├── styles/
├── utils/
├── app-shell.html
└── main.js
  • pages/ — отдельные страницы приложения.
  • services/ — классы для работы с API, хранением данных, авторизацией.
  • styles/ — глобальные и общие CSS-модули.
  • utils/ — вспомогательные функции и утилиты.

Такой подход обеспечивает чистую архитектуру, легкость поддержки и масштабируемость проекта на Polymer.

Оглавление