angular-elements

@angular/elements

版本： Angular 21（2025） 标签： Web Components、自定义元素、微前端

参考： Elements 指南 • API

API 变更

本节介绍近期特定版本的 API 变更。

• 新增：createCustomElement API — 将 Angular 组件打包为自定义元素

• 新增：NgElementConfig — 配置自定义元素的行为

• 新增：输入/输出映射 — 将 Angular 输入/输出映射到 Web 组件属性

• 新增：独立元素 — 无需 NgModule 即可构建独立元素

最佳实践

• 安装 @angular/elements

npm install @angular/elements

• 从组件创建自定义元素

import { createCustomElement } from '@angular/elements';

@Injectable()
export class ElementRegistrar {
  constructor(private injector: Injector) {}

  register() {
    const element = createCustomElement(MyComponent, { injector: this.injector });
    customElements.define('my-element', element);
  }
}

• 在 main.ts 中使用

import { createApplication } from '@angular/platform-browser';
import { createCustomElement } from '@angular/elements';

bootstrapApplication(AppComponent).then(appRef => {
  const element = createCustomElement(MyComponent, { injector: appRef.injector });
  customElements.define('my-component', element);
});

• 映射输入和输出

const element = createCustomElement(MyComponent, {
  injector: this.injector,
  events: ['myEvent'],
  attributes: ['myInput']
});

• 使用 CUSTOM_ELEMENTS_SCHEMA

// To use custom elements in Angular
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}

• 构建为 Web 组件

// angular.json
{
  "build": {
    "options": {
      "outputPath": "dist",
      "singleBundle": true
    }
  }
}

• 使用 input() 和 output() 处理 Web 组件数据

@Component({
  selector: 'my-element',
  standalone: true
})
export class MyElementComponent {
  data = input<string>('');
  output = output<string>();

  onClick() {
    this.output.emit('event-data');
  }
}

• 处理内容投影

@Component({
  selector: 'my-element',
  template: `
    <div class="header">
      <ng-content select="[header]"></ng-content>
    </div>
    <div class="body">
      <ng-content></ng-content>
    </div>
  `
})
export class MyElementComponent {}

• 用于微前端

// Register multiple elements
const elements = [ButtonComponent, CardComponent, InputComponent];
elements.forEach(comp => {
  const el = createCustomElement(comp, { injector });
  customElements.define(comp.selector, el);
});