Back to Details

angular-elements

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

@angular/elements

@angular/elements

Version: Angular 21 (2025) Tags: Web Components, Custom Elements, Micro-frontends
References: Elements Guide • API
版本： Angular 21 (2025) 标签： Web Components, Custom Elements, 微前端
参考文档： Elements指南 • API文档

API Changes

API变更

This section documents recent version-specific API changes.
  • NEW: createCustomElement API — Package Angular components as custom elements
  • NEW: NgElementConfig — Configure custom element behavior
  • NEW: Input/Output mapping — Map Angular inputs/outputs to web component attributes
  • NEW: Standalone elements — Build standalone elements without NgModule
本部分记录了近期对应版本的专属API改动内容。
  • 新增：createCustomElement API —— 将Angular组件打包为自定义元素
  • 新增：NgElementConfig —— 配置自定义元素的行为逻辑
  • 新增：Input/Output映射 —— 将Angular的inputs/outputs映射到web component属性
  • 新增：独立元素 —— 无需NgModule即可构建独立元素

Best Practices

最佳实践

  • Install @angular/elements
bash
npm install @angular/elements
  • Create custom element from component
ts
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);
  }
}
  • Use in main.ts
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);
});
  • Map inputs and outputs
ts
const element = createCustomElement(MyComponent, {
  injector: this.injector,
  events: ['myEvent'],
  attributes: ['myInput']
});
  • Use CUSTOM_ELEMENTS_SCHEMA
ts
// To use custom elements in Angular
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}
  • Build as web component
json
// angular.json
{
  "build": {
    "options": {
      "outputPath": "dist",
      "singleBundle": true
    }
  }
}
  • Use input() and output() for web component data
ts
@Component({
  selector: 'my-element',
  standalone: true
})
export class MyElementComponent {
  data = input<string>('');
  output = output<string>();

  onClick() {
    this.output.emit('event-data');
  }
}
  • Handle content projection
ts
@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 {}
  • Use for micro-frontends
ts
// Register multiple elements
const elements = [ButtonComponent, CardComponent, InputComponent];
elements.forEach(comp => {
  const el = createCustomElement(comp, { injector });
  customElements.define(comp.selector, el);
});
  • 安装@angular/elements
bash
npm install @angular/elements
  • 从组件创建自定义元素
ts
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中使用
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);
});
  • 映射inputs和outputs
ts
const element = createCustomElement(MyComponent, {
  injector: this.injector,
  events: ['myEvent'],
  attributes: ['myInput']
});
  • 使用CUSTOM_ELEMENTS_SCHEMA
ts
// To use custom elements in Angular
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}
  • 构建为web component
json
// angular.json
{
  "build": {
    "options": {
      "outputPath": "dist",
      "singleBundle": true
    }
  }
}
  • 使用input()和output()处理web component数据
ts
@Component({
  selector: 'my-element',
  standalone: true
})
export class MyElementComponent {
  data = input<string>('');
  output = output<string>();

  onClick() {
    this.output.emit('event-data');
  }
}
  • 处理内容投影
ts
@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 {}
  • 用于微前端场景
ts
// Register multiple elements
const elements = [ButtonComponent, CardComponent, InputComponent];
elements.forEach(comp => {
  const el = createCustomElement(comp, { injector });
  customElements.define(comp.selector, el);
});