Angular中嵌套Web组件的正确用法及异常修复

问题场景 #

页面已引入两个Web组件脚本：

<script src="preview.js"></script>
<script src="map.js"></script>

<app-preview data="data"></app-preview>

尝试在<app-preview>内部嵌套<app-map>时，通过document.createElement在onInit()中创建组件实例：

this._map = this.document.createElement('app-map') as HTMLMapElement;

再通过@ViewChild将其添加到模板，出现以下异常：

• 仅外层<app-preview>正常显示，内部<app-map>仅在hover时触发渲染
• 事件触发逻辑异常（鼠标移出区域才触发事件）
• <app-map>中依赖maploaded$ | async渲染的MORE COMPONENTS区域无响应，点击、hover均不触发Angular渲染

但单独使用两个组件时完全正常：

<app-preview data="data"></app-preview>
<app-map></app-map>

问题原因 #

1. 直接使用原生document.createElement创建Web组件，绕过了Angular的变更检测机制，Angular无法追踪组件状态变化，导致渲染和事件绑定异常
2. 动态创建的组件未正确纳入Angular视图树，@ViewChild的使用方式错误，异步状态（maploaded$）的变更无法触发视图更新
3. Web组件的Shadow DOM可能与Angular的视图封装产生冲突，导致事件冒泡和渲染上下文异常

修复步骤 #

1. 改用Angular动态组件创建API #

放弃原生DOM创建方式，使用ViewContainerRef.createComponent将组件纳入Angular视图树：

import { Component, ViewChild, ViewContainerRef, OnInit } from '@angular/core';
import { HTMLMapElement } from './path-to-map-component';

@Component({
  selector: 'app-preview',
  template: '<ng-template #mapContainer></ng-template>'
})
export class AppPreviewComponent implements OnInit {
  @ViewChild('mapContainer', { read: ViewContainerRef }) mapContainer!: ViewContainerRef;

  ngOnInit() {
    // 创建app-map实例并挂载到容器
    const componentRef = this.mapContainer.createComponent<HTMLMapElement>(HTMLMapElement);
    // 传递输入属性（如果需要）
    // componentRef.instance.width = '600px';
    // componentRef.instance.target = 'preview-inner-map';
  }
}

2. 配置自定义元素兼容Schema #

在使用Web组件的Angular模块中添加CUSTOM_ELEMENTS_SCHEMA，避免Angular抛出未知元素错误：

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  declarations: [AppPreviewComponent],
  imports: [],
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class PreviewModule { }

3. 确保异步状态触发变更检测 #

如果<app-map>的maploaded$是自定义异步流，确保状态变更能触发Angular变更检测：

• 若使用BehaviorSubject或Observable，模板中async管道会自动触发变更检测（前提是组件在Angular视图树中）
• 如需手动触发，可注入ChangeDetectorRef：

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

constructor(private cdr: ChangeDetectorRef) {}

// 状态变更后调用
this.maploaded$.next(true);
this.cdr.detectChanges();

Angular嵌套Web组件的正确实践 #

• 优先模板直接嵌套：无需动态创建时，直接在<app-preview>模板中写入<app-map>，Angular会自动处理视图和变更检测：

<!-- app-preview.component.html -->
<div class="preview-wrapper">
  <app-map [width]="'500px'" [target]="'preview-map'"></app-map>
</div>

• 动态创建必用Angular API：避免原生DOM操作，确保组件处于Angular视图树中，保障变更检测、事件绑定、输入输出正常工作
• 处理Shadow DOM冲突：若Web组件使用封闭Shadow DOM，优先使用组件提供的API进行交互，或配置事件穿透逻辑
• 规范自定义元素打包：若<app-map>是Angular组件打包的Web组件，需开启Ivy并正确注册自定义元素

内容的提问来源于stack exchange，提问作者Araviz