Обзор Angular elements

Angular elements — это Angular-компоненты, упакованные как custom elements (также называемые Web Components) — веб-стандарт для определения новых HTML-элементов независимо от фреймворка.

Custom elements — это функция веб-платформы, доступная во всех браузерах, поддерживаемых Angular. Custom element расширяет HTML, позволяя определить тег, содержимое которого создаётся и управляется кодом JavaScript. Браузер поддерживает CustomElementRegistry определённых custom elements, который сопоставляет инстанцируемый JavaScript-класс с HTML-тегом.

Пакет @angular/elements экспортирует API createCustomElement(), который обеспечивает мост между интерфейсом компонента Angular, функциональностью обнаружения изменений и встроенным DOM API.

Преобразование компонента в custom element делает всю необходимую инфраструктуру Angular доступной браузеру. Создание custom element простое и прямолинейное, и автоматически связывает представление компонента с обнаружением изменений и привязкой данных, сопоставляя функциональность Angular с соответствующими встроенными HTML-эквивалентами.

Использование custom elements

Custom elements загружаются самостоятельно — они запускаются при добавлении в DOM и уничтожаются при удалении из DOM. После добавления custom element на любую страницу он выглядит и ведёт себя как любой другой HTML-элемент и не требует специальных знаний терминологии или соглашений Angular.

Чтобы добавить пакет @angular/elements в рабочее пространство, выполните следующую команду:

npm install @angular/elements

yarn add @angular/elements

pnpm add @angular/elements

bun add @angular/elements

Как это работает

Функция createCustomElement() преобразует компонент в класс, который можно зарегистрировать в браузере как custom element. После регистрации настроенного класса в реестре custom elements браузера используйте новый элемент так же, как встроенный HTML-элемент в содержимом, добавляемом напрямую в DOM:

<my-popup message="Use Angular!" />

Когда custom element размещается на странице, браузер создаёт экземпляр зарегистрированного класса и добавляет его в DOM. Содержимое предоставляется шаблоном компонента, который использует синтаксис шаблонов Angular, и рендерится с использованием данных компонента и DOM. Input-свойства компонента соответствуют input-атрибутам элемента.

Преобразование компонентов в custom elements

Angular предоставляет функцию createCustomElement() для преобразования Angular-компонента вместе с его зависимостями в custom element.

Процесс преобразования реализует интерфейс NgElementConstructor и создаёт класс-конструктор, настроенный на создание самозагружаемого экземпляра компонента.

Используйте нативную функцию браузера customElements.define() для регистрации настроенного конструктора и связанного с ним тега custom element в CustomElementRegistry браузера. Когда браузер встречает тег зарегистрированного элемента, он использует конструктор для создания экземпляра custom element.

Сопоставление

Custom element хостит Angular-компонент, обеспечивая мост между данными и логикой, определёнными в компоненте, и стандартными DOM API. Свойства и логика компонента напрямую сопоставляются с HTML-атрибутами и системой событий браузера.

• API создания анализирует компонент в поисках input-свойств и определяет соответствующие атрибуты для custom element. Имена свойств преобразуются для совместимости с custom elements, которые не различают регистр. Полученные имена атрибутов используют строчные буквы с дефисами. Например, для компонента с inputProp = input({alias: 'myInputProp'}) соответствующий custom element определяет атрибут my-input-prop.

• Output компонента отправляются как HTML Custom Events, имя custom event совпадает с именем output. Например, для компонента с valueChanged = output() соответствующий custom element отправляет события с именем «valueChanged», а переданные данные хранятся в свойстве detail события. Если указан alias, используется это значение; например, clicks = output<string>({alias: 'myClick'}); приводит к отправке событий с именем «myClick».

Подробнее см. документацию Web Components по созданию пользовательских событий.

Пример: сервис Popup

Чтобы добавить компонент в приложение во время выполнения, можно программно отрендерить его с помощью API createComponent. При таком подходе вы отвечаете за окружающую инфраструктуру: присоединение host view компонента к ApplicationRef для запуска обнаружения изменений, установку его inputs, подписку на outputs, а также отсоединение и очистку view при удалении компонента.

Использование Angular custom element упрощает и делает прозрачным этот процесс, автоматически предоставляя всю инфраструктуру — достаточно определить нужную обработку событий.

В следующем примере приложения Popup Service определяется компонент, который можно либо загрузить динамически, либо преобразовать в custom element.

Для сравнения демо показывает оба метода. Одна кнопка добавляет popup методом динамической загрузки, другая — через custom element. Результат одинаковый, но подготовка различается.

import {Component, computed, input, output} from '@angular/core';
import {animate, state, style, transition, trigger} from '@angular/animations';

@Component({
  selector: 'my-popup',
  template: `
    <span>Popup: {{ message() }}</span>
    <button type="button" (click)="closed.emit()">&#x2716;</button>
  `,
  animations: [
    trigger('state', [
      state('opened', style({transform: 'translateY(0%)'})),
      state('void, closed', style({transform: 'translateY(100%)', opacity: 0})),
      transition('* => *', animate('100ms ease-in')),
    ]),
  ],
  styles: [
    `
      :host {
        position: absolute;
        bottom: 0;
        left: 0;
        right: 0;
        background: #009cff;
        height: 48px;
        padding: 16px;
        display: flex;
        justify-content: space-between;
        align-items: center;
        border-top: 1px solid black;
        font-size: 24px;
      }

      button {
        border-radius: 50%;
      }
    `,
  ],
  host: {
    '[@state]': 'state()',
  },
})
export class Popup {
  readonly message = input('');
  readonly closed = output<void>();

  readonly state = computed(() => (this.message() ? 'opened' : 'closed'));
}

import {
  ApplicationRef,
  createComponent,
  EnvironmentInjector,
  inject,
  Injectable,
} from '@angular/core';
import {NgElement, WithProperties} from '@angular/elements';
import {Popup} from './popup';

@Injectable()
export class PopupService {
  private readonly injector = inject(EnvironmentInjector);
  private readonly applicationRef = inject(ApplicationRef);

  // Previous dynamic-loading method required you to set up infrastructure
  // before adding the popup to the DOM.
  showAsComponent(message: string) {
    // Create element
    const popup = document.createElement('popup-component');

    // Create the component and wire it up with the element
    const popupComponentRef = createComponent(Popup, {
      environmentInjector: this.injector,
      hostElement: popup,
    });

    // Attach to the view so that the change detector knows to run
    this.applicationRef.attachView(popupComponentRef.hostView);

    // Listen to the close event
    popupComponentRef.instance.closed.subscribe(() => {
      document.body.removeChild(popup);
      this.applicationRef.detachView(popupComponentRef.hostView);
    });

    // Set the message
    popupComponentRef.setInput('message', message);

    // Add to the DOM
    document.body.appendChild(popup);
  }

  // This uses the new custom-element method to add the popup to the DOM.
  showAsElement(message: string) {
    // Create element
    const popupEl: NgElement & WithProperties<Popup> = document.createElement(
      'popup-element',
    ) as any;

    // Listen to the close event
    popupEl.addEventListener('closed', () => document.body.removeChild(popupEl));

    // Set the message
    popupEl.setAttribute('message', message);
    // Add to the DOM
    document.body.appendChild(popupEl);
  }
}

import {Component, Injector} from '@angular/core';
import {createCustomElement} from '@angular/elements';
import {Popup} from './popup';
import {PopupService} from './popup.service';

@Component({
  selector: 'app-root',
  template: `
    <input #input value="Message" />
    <button type="button" (click)="popup.showAsComponent(input.value)">Show as component</button>
    <button type="button" (click)="popup.showAsElement(input.value)">Show as element</button>
  `,
  providers: [PopupService],
  imports: [Popup],
})
export class App {
  constructor(
    injector: Injector,
    public popup: PopupService,
  ) {
    // Convert `PopupComponent` to a custom element.
    const PopupElement = createCustomElement(Popup, {injector});
    // Register the custom element with the browser.
    customElements.define('popup-element', PopupElement);
  }
}

Типизация для custom elements

Общие DOM API, такие как document.createElement() или document.querySelector(), возвращают тип элемента, соответствующий указанным аргументам. Например, вызов document.createElement('a') возвращает HTMLAnchorElement, у которого TypeScript знает о свойстве href. Аналогично, document.createElement('div') возвращает HTMLDivElement, у которого TypeScript знает, что нет свойства href.

При вызове с неизвестными элементами, например именем custom element (popup-element в нашем примере), методы возвращают общий тип, например HTMLElement, поскольку TypeScript не может вывести правильный тип возвращаемого элемента.

Custom elements, созданные с Angular, расширяют NgElement (который в свою очередь расширяет HTMLElement). Кроме того, эти custom elements будут иметь свойство для каждого input соответствующего компонента. Например, наш popup-element имеет свойство message типа string.

Есть несколько вариантов получить корректные типы для custom elements. Предположим, вы создаёте custom element my-dialog на основе следующего компонента:

@Component(/* ... */)
class MyDialog {
  content = input('');
}

Самый простой способ получить точную типизацию — привести возвращаемое значение соответствующих DOM-методов к правильному типу. Для этого используйте типы NgElement и WithProperties (оба экспортируются из @angular/elements):

const aDialog = document.createElement('my-dialog') as NgElement &
  WithProperties<{content: string}>;
aDialog.content = 'Hello, world!';
aDialog.content = 123; // <-- ERROR: TypeScript knows this should be a string.
aDialog.body = 'News'; // <-- ERROR: TypeScript knows there is no `body` property on `aDialog`.

Это хороший способ быстро получить возможности TypeScript, такие как проверка типов и автодополнение, для custom element. Но это может быть громоздко, если нужно в нескольких местах, поскольку приведение типа нужно делать при каждом использовании.

Альтернативный способ, требующий определения типа каждого custom element только один раз, — расширение HTMLElementTagNameMap, который TypeScript использует для вывода типа возвращаемого элемента по имени тега (для DOM-методов вроде document.createElement(), document.querySelector() и т.д.):

declare global {
  interface HTMLElementTagNameMap {
    'my-dialog': NgElement & WithProperties<{content: string}>;
    'my-other-element': NgElement & WithProperties<{foo: 'bar'}>;
    …
  }
}

Теперь TypeScript может вывести правильный тип так же, как для встроенных элементов:

document.createElement('div'); //--> HTMLDivElement (built-in element)
document.querySelector('foo'); //--> Element        (unknown element)
document.createElement('my-dialog'); //--> NgElement & WithProperties<{content: string}> (custom element)
document.querySelector('my-other-element'); //--> NgElement & WithProperties<{foo: 'bar'}>      (custom element)

Ограничения

Следует быть осторожным при уничтожении и повторном присоединении custom elements, созданных с @angular/elements, из-за проблем с callback disconnect(). Случаи, когда может возникнуть эта проблема:

• Рендеринг компонента в ng-if или ng-repeat в AngularJS
• Ручное отсоединение и повторное присоединение элемента к DOM