Эта статья — перевод оригинальной статьи Luis Aviles "How to integrate Web Components using Lit in Angular"

Также я веду телеграм канал “Frontend по-флотски”, где рассказываю про интересные вещи из мира разработки интерфейсов.

Вступление

В этом руководстве я объясню необходимые шаги для интеграции веб-компонентов в Angular. Спойлер: Вы можете найти исходный код демонстрационного проекта в конце.

Настройка проекта

В вашей локальной среде должны быть установлены следующие инструменты:

Node.js. Желательно последняя версия LTS.
Менеджер пакетов. Вы можете использовать npm или yarn. В этом руководстве будет использоваться npm.

Создание проекта Angular

Давайте создадим проект с нуля с помощью Angular CLI.

ng new angular-lit-web-components --routing --prefix corp --style css --skip-tests

Эта команда инициализирует базовый проект с использованием некоторых параметров конфигурации:

--routing. Будет создан модуль маршрутизации.
--prefix corp. Он определяет префикс, который будет применяться к селекторам для созданных компонентов (в данном случае corp). Значение по умолчанию - app.
--style css. Расширение файла стилей.
--skip-tests. Это позволяет избежать генерации файлов .spec.ts, которые используются для тестирования.

Установка Lit

Lit - это простая библиотека для создания быстрых и легких веб-компонентов.

Lit доступен через npm, давайте установим его как новую зависимость для текущего проекта.

npm install --save lit

Дополнительную информацию о Lit можно найти здесь.

Установка Web Components Polyfills

Есть несколько способов установить полифилы веб-компонентов. В этом случае мы установим его с помощью npm.

npm install --save @webcomponents/webcomponentsjs

Затем вы можете использовать webcomponents-loader.js, который позволяет загружать минимальный пакет полифиллов.

Обновляем Angular конфиг

Вы можете загрузить полифиллы с помощью тега <script> в файл index.html. Однако в Angular это можно сделать путем добавления новых конфигураций ресурсов и скриптов в файл angular.json следующим образом:

"architect": {
  "build": {
    ...
    "options": {
      ...
      "assets": [
        "src/favicon.ico",
        "src/assets",
        {
          "glob": "{*loader.js,bundles/*.js}",
          "input": "node_modules/@webcomponents/webcomponentsjs",
          "output": "node_modules/@webcomponents/webcomponentsjs"
        }
      ],
      "scripts": [
        "node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"
      ]
      ...
    },
    "configurations": {
      ...
    },
      ...
  },
 }

И входные, и выходные свойства должны относиться к корневому пути проекта. То же самое и с импортированным скриптом.

Создание веб-компонентов с использованием Lit

Настройка проекта завершена, и теперь пора создать наш первый веб-компонент с использованием Lit.

Давайте создадим папку src/web-components/card-user, а затем создадим два файла: card-user.ts и user.ts.

Файл user.ts будет определять общую модель, используемую реализацией веб-компонента и проектом Angular:

// user.ts
export interface User {
  id: number;
  fullName: string;
  role: string;
  avatar?: string;
}

Затем давайте напишем код для нашего веб-компонента в файле card-user.ts:

// card-user.ts

import { LitElement, html, css } from 'lit';
import { property, customElement } from 'lit/decorators.js';
import { User } from './user';

@customElement('card-user')
export class CardUser extends LitElement {
  static styles = css`
    :host {
      display: block;
    }
    .card {
      box-shadow: 0 10px 10px 0 rgba(0, 0, 0, 0.5);
      max-width: 160px;
    }
    .card-content {
      padding: 10px;
    }
  `;

  @property({ type: Object }) user?: User = {
    id: 0,
    fullName: 'Luis Aviles',
    role: 'Software Engineer',
  };

  render() {
    if (this.user === undefined) {
      return '';
    }

    return html`
      <div class="card">
        <img
          width="160px"
          src=${this.user.avatar
            ? this.user.avatar
            : 'assets/images/avatar.png'}
        />
        <div class="card-content">
          <h4>${this.user.fullName}</h4>
          <p>${this.user.role}</p>
          <button @click=${this.handleEdit}>Edit</button>
        </div>
      </div>
    `;
  }

  private handleEdit() {
    this.dispatchEvent(
      new CustomEvent<User>('edit', {
        detail: this.user,
      })
    );
  }
}

Класс CardUser определяет кастомный элемент как новый виджет для нашего проекта.

Декоратор @customElement позволяет определять компонент, используя для него имя: card-user.
Поле static styles определяет стили для компонента с литерала шаблона css.
Декоратор @property, который позволяет объявлять свойства кастомного элемента в удобном виде.
Метод рендеринга возвращает содержимое HTML через литерал шаблона html. Эта функция будет вызываться каждый раз при изменении свойства пользователя.

Вы можете узнать больше о том, как создать компонент с помощью Lit здесь.

Использование веб-компонентов в Angular

Импортируем веб-компонент

Перед использованием любого веб-компонента в Angular, нам необходимо импортировать его следующим образом:

// app.component.ts

import { Component } from '@angular/core';

import '../web-components/card-user/card-user'; // <-- import the web component

@Component({
  selector: 'corp-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent {}

Используем кастомный элемент

Следующим шагом будет использование нового кастомного элемента <card-user> как части шаблона. В этом случае давайте использовать его в нашем файле app.component.html:

<card-user></card-user>

После сохранения этих изменений вы можете обнаружить ошибку в консоле (место, где вы запускаете ng serve).

Error: src/app/app.component.html:1:1 - error NG8001: 'card-user' is not a known element:
1. If 'card-user' is an Angular component, then verify that it is part of this module.
2. If 'card-user' is a Web Component, add 'CUSTOM_ELEMENTS_SCHEMA' to the '@NgModule.schemas' of this component to suppress this message.

1 <card-user></card-user>
  ~~~~~~~~~~~

  src/app/app.component.ts:7:16
    7   templateUrl: './app.component.html',
                     ~~~~~~~~~~~~~~~~~~~~~~
    Error occurs in the template of component AppComponent.

К счастью, предыдущее сообщение об ошибке достаточно понятно нам говорит, что нам нужно изменить файл app.module.ts.

// app.module.ts

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, AppRoutingModule],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

Важная часть здесь - импортировать CUSTOM_ELEMENTS_SCHEMA из пакета @angular/core, а затем использовать его в свойстве schemas. Вы можете найти больше информации об этом здесь.

Сохраните изменения еще раз, и волшебство произойдет :-)

Использование Property Binding

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

Для этого определим свойство user в файле app.component.ts:

// app.component.ts

export class AppComponent {
  user: User = {
    id: 2,
    fullName: 'Luis',
    role: 'Software Engineer',
    avatar: 'https://luixaviles.com/images/avatar@2x.png',
  };
}

Затем мы можем обновить связанный шаблон и использовать квадратные скобки для привязки свойства:

<card-user [user]="user"></card-user>

Более того, вы можете создать массив пользователей, чтобы иметь возможность отображать их, используя другие полезные функции из нашего любимого фреймворка, например, структурная директива *ngFor.

<card-user *ngFor="let user of users" [user]="user"></card-user>

Использование Event Binding

Пришло время слушать действия пользователя и реагировать на них через привязку событий в Angular. Как вы видели ранее, компонент corp-user может отправлять событие edit после нажатия кнопки «Изменить».

На этот раз воспользуемся круглыми скобками для привязки метода:

<card-user *ngFor="let user of users" [user]="user" (edit)="edit($event)"></card-user>

Наконец, давайте создадим метод редактирования в нашем компоненте.

// app.component.ts

//...
export class AppComponent {
  //...

  edit(event: Event) {
    const user = (event as CustomEvent<User>).detail;
    console.log('Edit user', user);
  }
}

Метод edit получает обобщенный Event. Хотя кастомный элемент отправил объект User через CustomEvent. Затем мы можем использовать синтаксический оператор as из TypeScript и получить к нему доступ с помощью свойства detail. На следующем снимке экрана показаны результаты в консоли браузера.

Исходный код проекта

Вы можете найти полный код в этом репозитории GitHub: angular-lit-web-components. Не забудьте поставить звездочку ⭐️ и поэкспериментировать с кодом.

Как интегрировать веб-компоненты с помощью Lit в Angular