Angular - Elements

什么是 Angular Element？

Angular elements 是可重用的组件，已被转换为 custom elements（也称为 Web Components）。Angular 提供了一种简单有效的方法来创建 Web components。

Web components 是原生 HTML 规范中可用的自定义 HTML 元素，用于扩展 HTML 文档的功能/标签。它可以通过 JavaScript 创建，并在 HTML 文档中可用。JavaScript 提供了创建自定义 HTML 元素的一些特殊方法。

使用 JavaScript 创建自定义 HTML 元素是一个冗长的过程，开发者需要了解自定义 HTML 元素和 Shadow DOM 概念的内部工作原理。Angular 通过最小化组件 class 的更改，简化了这一过程，将 Angular components 转换为 web components。

创建 Angular elements 意味着将一个 component 转换为 custom element。为此，使用 @angular/elements 包。该包导出了一个 createCustomElement() function，它将 component 转换为一个 class，该 class 可以注册到浏览器中作为 custom element。

示例 - 创建 Angular Elements

让我们学习如何在 Angular 中创建自定义 HTML 元素。

在这个示例中，我们将创建一个用于显示员工信息的组件（例如 EmpCard），并将其转换为自定义 HTML 元素。

步骤 1： 使用 Angular CLI 创建一个 Angular 应用，emp-card-web-component。

ng new emp-card-web-component

步骤 2： 使用 Angular CLI 创建 emp-card 组件。

ng generate component emp-card
CREATE src/app/emp-card/emp-card.spec.ts (562 bytes)
CREATE src/app/emp-card/emp-card.ts (204 bytes)
CREATE src/app/emp-card/emp-card.css (0 bytes)
CREATE src/app/emp-card/emp-card.html (24 bytes)

步骤 3： 在 @Component 装饰器中添加 encapsulation 选项，使用 ViewEncapsulation.ShadowDom 选项。ShadowDom 选项启用了 HTML 原生的 ShadowDom 概念，以保留组件的样式而不泄漏到 HTML 文档的其他部分。

@Component({
   // ...
   encapsulation: ViewEncapsulation.ShadowDom
})
export class EmpCard {
   // ...
}

步骤 4： 接下来，在 HTML 元素中添加两个输入属性，员工的 name 和 role。

export class EmpCard {
   @Input() name: string = '';
   @Input() role: string = '';
}

步骤 5： 组件的完整代码如下 −

emp-card.ts

import { Component, Input, ViewEncapsulation } from '@angular/core';

@Component({
  selector: 'app-emp-card',
  imports: [],
  templateUrl: './emp-card.html',
  styleUrl: './emp-card.css',
  encapsulation: ViewEncapsulation.ShadowDom
})
export class EmpCard {
   @Input() name: string = '';
   @Input() role: string = '';
}

步骤 6： 接下来，打开组件的模板文件，并添加标记来显示员工姓名和角色，如下所示 −

emp-card.html

<div class="card">
   <div class="container">
      <h4><b>{{ name }}</b></h4>
      <p>{{ role }}</p>
   </div>
</div>

步骤 7： 接下来，打开组件的样式文件，并添加 CSS 来为员工卡片显示阴影效果。

emp-card.css

.card {
   box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2);
}

.card:hover {
   box-shadow: 0 8px 16px 0 rgba(0,0,0,0.2);
}

.container {
   padding: 2px 16px;
   max-width: 200px;
}

步骤 8： 接下来，安装 Angular 团队提供的 @angular/elements 模块。@angular/elements 模块提供了从 Angular 组件创建自定义 HTML 元素的选项。

ng add @angular/elements
√ Determining Package Manager
  › Using package manager: npm
√ Searching for compatible package version
  › Found compatible package version: 21.0.0.
√ Loading package information from registry
√ Confirming installation
√ Installing package
Package installed successfully. The package does not provide any `ng add` actions, so no further actions were taken.
For more information about this package, visit its homepage at https://github.com/angular/angular#readme

步骤 9： 接下来，打开 main.ts 文件并移除所有样板代码。

步骤 10： 接下来，从 @angular/platform-browser 导入 createApplication。createApplication 将用于启动 Angular 应用。

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

步骤 11： 接下来，从 @angular/elements 模块导入 createCustomElement。createCustomElement 将用于从 Angular 组件创建自定义 HTML 元素。

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

步骤 12： 接下来，如下所示导入 EmpCard 组件 −

import { EmpCard } from './app/emp-card/emp-card'

步骤 13： 接下来，使用 createApplication() 方法通过输入 providers 和一个回调方法来创建应用。回调方法将用于从 Angular 组件创建自定义 HTML 元素。

createApplication({ providers: [] }).then((appRef) => {
   // ...
});

步骤 14： 实现回调方法，并使用 createCustomElement() 方法创建自定义元素。createCustomElement 接受要转换的组件和应用的 injector。

我们可以通过 createApplication() 方法返回的应用引用来获取 injector。

createApplication({ providers: [] }).then((appRef) => {
   const empCard = createCustomElement(
      EmpCardComponent,
      { injector: appRef.injector }
   );
});

步骤 15： 接下来，使用 JavaScript 原生方法 customElements.define() 来注册创建的自定义组件。

createApplication({ providers: [] }).then((appRef) => {
   const empCard = createCustomElement(
      EmpCardComponent,
      { injector: appRef.injector }
   );
   
   customElements.define('emp-card', empCard);
});

步骤 16： main.ts 文件的完整代码如下，

main.ts

import { createApplication } from '@angular/platform-browser';
import { createCustomElement } from '@angular/elements';
import { EmpCard } from './app/emp-card/emp-card'

createApplication({ providers: [] }).then((appRef) => {
   const empCard = createCustomElement(
      EmpCard,
      { injector: appRef.injector }
   );
   
   customElements.define('emp-card', empCard);
});

步骤 17： 接下来，使用 Angular CLI 的构建命令构建应用

ng build
Initial chunk files | Names         |  Raw size | Estimated transfer size
main-WKKDU3MJ.js    | main          | 101.87 kB |                30.60 kB
styles-5INURTSO.css | styles        |   0 bytes |                 0 bytes

                    | Initial total | 101.87 kB |                30.60 kB

Application bundle generation complete. [5.142 seconds] - 2025-11-21T14:43:54.251Z

Output location: D:\Angular\emp-card-web-component\dist\emp-card-web-component

步骤 18： 构建完成后，输出文件将位于 dist/emp-card-web-component 文件夹中。它包含以下文件（类似文件）以及一个 index.html 文件。

• main-5LWF45YA.js
• polyfills-FFHMD2TL.js
• styles-5INURTSO.css

步骤 19： 更新 src 文件夹中的 index.html 文件，添加新创建的组件，并检查输出是否正确。

index.html

<!doctype html>
<html lang="en">
<head>
   <meta charset="utf-8">
   <title>EmpCardWebComponent</title>
   <base href="/">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body>
   <emp-card name="John" role="Angular developer"></emp-card>
   <emp-card name="Maria" role="Frontend developer"></emp-card>
</body>
</html>

在这里，我们为 emp-card 标签添加了两个不同的员工详细信息。

步骤 20： 最后，运行应用并在浏览器中检查输出。

Summary

正如我们所学，在 Angular 中创建 web component 非常简单。我们只需像开发普通的 Angular component 一样开发组件。一旦组件的功能开发完成，我们需要在 main.ts 文件中添加一些 bootstrapping 代码，然后构建应用，以获取必要的自定义 HTML 元素，这些元素是一堆原生 JavaScript。我们可以在任何不使用 Angular 的网站上使用它。