Angular 18+ 高级教程 – Component 组件 の ng-template

前言

上一篇 Dynamic Component 我们有提到，作为 MVVM 框架的 Angular 需要有方法替代掉 2 个 DOM Manipulation：

  1. document.createElement 

  2. template.content.clone

Dynamic Component 便是替代 document.createElement 的方案。

而这篇我们要讲的 ng-template 则是 template.content.clone 的替代方案。

 

ng-template の 简单使用

我们从浅入深，一个一个特性介绍，最后才逛源码，看看原理机制。

提醒：为了更容易体会到细节，我把 ngZone 关了，所有组件都设置成 ChangeDetectionStrategy.OnPush。

App Template

AppComponent

效果

整体流程相当简单，所有用到的技能，我们在前几篇文章都学过了

  1. query template（Query Elements 文章里学过了）

  2. use template create view (和 createComponent 大同小异，Dynamic Component 文章里学过了)

  3. append view (ViewContainerRef 在 Dynamic Component 文章里学过了)

 

Template Context

上面例子缺少了一个重要的角色 -- Template Context (a.k.a ViewModel)。

我们拿一个组件来观摩

Template binding with Template Context = DOM

对于组件来说，所谓的 Template Context 就是组件实例。

那 ng-template 也要有 Template Context 才可以搞 Template Binding Syntax。

首先我们需要定义 Template Context 的类型结构，我们不需要用 class，用 interface 就可以了，因为我们只需要类型。

interface TemplateContext {
  title: string;
  description: string;
}

接着把 ng-template 改成这样

<ng-template #template let-title="title" let-description="description">
  <h1>{{ title }}</h1>
  <p>{{ description }}</p>
</ng-template>

let-title 表示定义一个 internal variable，它的值来自于 templateContext['title']。

它是一个 mapping 来的

那为什么需要声明 internal variable 呢？为什么不像组件那样直接可以引用 templateContext？

这个原因我们下一 part 会讲解。

接着在创建 EmbeddedView 时传入 Template Context。

效果

 

Template Context Type Guard

参考：

Stack Overflow – ng-template - typed variable

Docs – Making in-template type requirements more specific with template guards

对类型敏感的朋友可能已经发现到了，let-variable 的类型始终是 any

这是因为 Angular 不够聪明，我们可以通过一些 workaround 让它显示正确类型。

首先创建一个 TemplateContextTypeGuard 指令

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

@Directive({
  selector: 'ng-template[templateContextType]',
  standalone: true,
})
export class TemplateContextTypeGuardDirective<T> {
  @Input('templateContextType')
  type!: T;

  static ngTemplateContextGuard<T>(
    _dir: TemplateContextTypeGuardDirective<T>,
    ctx: unknown
  ): ctx is T {
    return true;
  }
}

我们不需要懂原理，照着用就可以了。上面最关键的是 static ngTemplateContextGuard，Angular 就是靠它来搞类型的。

接着 AppComponent

属性用 declare 就可以了，因为它不用于 runtime。

接着 App Template

这样类型就出来了。

TemplateContextTypeGuardDirective 是泛型，所以是通用的，我们只需要每一次繁琐的 apply 指令传入不同的 Templete Context Type 就可以了。

 

$implicit 的用法

没有人喜欢写 mapping，尤其是 let-whatever="whatever" 这种，又长，又没有意义。

于是，Angular 搞了一个潜规则，叫 $implicit，implicit 就是 "隐含" 的意思。

把 Template Context 类型改成这样

$implicit 是 Angular 认得的一个特殊属性，我们把之前的 title 和 description 移进去。

接着 App Template

没有声明 mapping path 的 let-whatever 会被 Angular 识别为 let-whatever="$implicit"。

这样就不需要写一堆的 mapping 了。

小总结：

  1. same key

    let-title="title" 

    const title = templateContext['title']

  2. different key

    let-whatever="title" 

    const whatever = templateContext['title']

  3. child key

    let-childTitle="child.title"

    const childTitle = templateContext['child']['title']

  4. implicit

    let-whatever

    let-whatever="$implicit"

    const whatever = templateContext['$implicit']

 

Declaration Template Context

上图，ng-template 没有定义 let-value，那 {{ value }} 会拿到什么值呢？

答案是 appComponent.value

ng-template 不只能访问本身的 Template Context，它还可以访问到它的 Declaration Template Context (而且是所有组件层的 Declaration Template Context)。

Declaration 指的是 ng-template 被声明的地方。

比如上图，这个 ng-template 是在 App Template 被声明的，所以它的 Declaration 指的就是 App Template。

App Template Context 指的是 App 组件实例，所以 {{ value }} 会先找本身的 Template Context 找，找不到就去 App 组件实例找。

再一个嵌套的例子

变量查找会一层一层往上，依据它们被 Declaration 声明的地方。

这也是为什么，每个 ng-template 都需要 let-whatever，没有 let- 就等于这个 ng-template 没有自身的 Template Context，那 binding syntax 就会直接往上找了。

ng-template as a function

把 ng-template 看成是 function 也有助于我们的理解。

Child Template 被 compile 后长这样

从这里可以看出它如何从每一层的 Template Context 抽出 value 赋值 let-variable 和最终的 binding to DOM。

 

ng-template 用于 Dynamic Component 的 Content Projection

在上一篇 Dyanmic Component 中，我们有一个 Content Projection 的例子，里面使用了原生的 template DOM Manipulation。

这里补上一个 ng-template 的版本。

SayHi Template

App Template

需求很简单，动态创建 SayHi 组件，把 ng-template 里的 3 个 paragraph 传进去 ng-content。

关键就是 rootNodes 属性会得到 Node Array。

效果

 

当 ng-template 遇上 Query Elements

上一篇我们说过 Dynamic Component 是无法通过 @ViewChildren query 出来的。

那 ng-template 呢？

可以！

效果

小心坑

上面的例子是这样的

  1. ng-template 被 declare 在 App Template
  2. ng-template 被插入到 App Template（因为 ng-container 在 App Template 里）
  3. @ViewChildren 也在 AppComponent

全部在一起，query 没有问题。

我们换一个场景

当我们把 ng-template 和 ng-container (插入的位置) 分别放到不同的组件时，结果只有 ng-template declare 的 C1 组件可以 query 到 ng-template 里的内容。

这里就涉及到 Query ng-template 的机制了，我们下面逛源码的时候才解答，这里我们只要记住，没有人可以从 ng-container 里 query 出任何东西。

Dynamic Component 和 ng-template 都不行。ng-template 可以被 query 是在 declare 它的地方，而不是在它插入的地方。

 

当 ng-template 遇上 Change Detection

同样一个跨组件的例子

C1 声明 ng-template，C2 insert

这个 ng-template 内有用到本身的 Template Context (C2 传入) 也有用到 Declaration Template Context (来自 C1)

C1 update value 并且 detectChanges，ng-template 内容没有更新，因为 C2 没有跟着 detectChanges。

我们知道 detectChanges 是往下的，sibling 的 C2 没有跟着 detectChanges 是正常的。

C2 update value 并且 detectChanges，有效果，正常。

当 C2 detectChanges 时，ng-template 内容连 C1 的 value 都一起更新了。

结论

  1. C2 作为 ng-template insert 的地方，只要它 refreshView，那么 ng-template 也一定会 refreshView。

  2. C1 作为 ng-template declare 的地方，即便它 refreshView，ng-template 也未必会 refreshView。

上面的结论有一个前提，那就是我们关闭了 ngZone 并且指定了组件做 detectChanges。

如果我们开启 ngZone 让它跑 tick，那么在 C1 refreshView 之后，C2 作为 ng-template insert 的地方也会被 refreshView。

这是因为 Angular 做了特别的处理，下面逛源码时会讲解。

 

逛源码 の declare ng-template

要深入理解 ng-template 最好的方式自然是逛源码咯😱...或者至少看一看它在 TView、LView、TNode 里的长相。

我们一样由浅入深。

View Information

App Template

单看 View (视图)，组件和 ng-template 其实很像，毕竟组件也有 Template，所以我们可以借助原先对组件的认知来理解 ng-template。

假设上图是一个 <app-say-hi>

那这里 renderView 后会产生

  1. TNode（type = Element）
  2. RNode (<app-say-hi>)
  3. TView
  4. LView

那换成 <ng-template> 它会产生

  1. TNode (type = Container)
  2. RNode （<!--container-->）
  3. TView
  4. LContainer（注：这里不是 LView 哦）

DOM

App LView

App TView.data

SayHi 和 ng-template 的差异

  1. SayHi TView 存放在 SayHi Definition.tView

    而 ng-template TView 存放在 ng-template TNode.tView。

    合理，因为 ng-template 没有 Definition。

  2. SayHi 有 LView，ng-template 没有。

    合理，因为 ng-template 的 LView 要等到 TemplateRef.createEmbeddedView 时才会创建。

  3. ng-template RNode 是 Comment 节点

    合理，因为 ng-template 不是原生 tag。就如同 <ng-container /> 那样，也是 Comment 节点。

  4. SayHi TNode 类型是 Element (1 号)，ng-template TNode 类型是 Container (4号)。

    注：<ng-container /> 的 TNode 类型是 ElementContainer (8号)

  5. ng-template 生成了一个 LContainer

    Dynamic Component 文章中，我们知道 @ViewChildren + read: ViewContainerRef 不管 query 任何 RNode 都会生成 LContainer。

    它用于 ViewContainerRef.insert 插入 Dynamic Component。

    这里 ng-template 也会生成 LContainer，不过用途和 ViewContainerRef 不同，下一 part 会讲。

    但有一点要 highlight，当 ng-template + @ViewChildren + read: ViewContainerRef 同时出现时，

    它两会公用同一个 LContainer 哦。

相关源码

app.component.js

ng-template 的 template 方法

ɵɵtemplate 函数的源码在 template.ts

templateFirstCreatePass 函数和 elementStartFirstCreatePass (以前研究过的) 函数大同小异

回到 ɵɵtemplate 函数

 

逛源码 の createEmbeddedView

继续由浅入深，上一 part declare ng-template，这一 part 我们 create and insert。

View Information

App Template

<ng-template #template>
  <h1>Hello</h1>
</ng-template>
<button (click)="append()" >append</button>
<ng-container #container />

AppComponent

export class AppComponent {
  @ViewChild('template')
  templateRef!: TemplateRef<null>;

  @ViewChild('container', { read: ViewContainerRef })
  viewContainerRef!: ViewContainerRef;

  cdr = inject(ChangeDetectorRef);

  append() {
    const embeddedView = this.templateRef.createEmbeddedView(null);
    console.log((embeddedView as any)._lView);
    // this.viewContainerRef.insert(embeddedView); // 先不插入，看 Embedded LView 先
  }
}

ng-template LView (a.k.a Embedded LView)

有 7 个是和 ng-template 息息相关的

几个点需要留意：

  1. Declaration View 指的是这个 ng-template 被声明的地方，上面例子中 ng-template 是在 App Template 里被声明的，所以它的 Declaration View 是 App LView。 

    如果是嵌套 ng-template

    那 ng-template2 的 Declaration View 则是 ng-template1 的 LView。

    在 createLView 函数里，LView 创建时 Parent 和 Declaration View 就是当前的 parentLView。

    注：Parent 会在插入 <ng-container /> 后变成 LContainer。

  2. Declaration Component View 一定是组件 LView，上面 template1 和 template2 的 Declaration Component View 都是 App LView。

    另外一点，组件的 Declaration Component View 一定指向自己。

  3. Embedded View Injector 下面会教，这里我们略过。

接着插入到 <ng-container />

this.viewContainerRef.insert(embeddedView);

<ng-container /> LContainer

<ng-container /> LContainer 没什么特别的，上一篇 Dyanmic Component 我们研究过了，

唯一的区别是组件是 hostView，ng-template 是 embeddedView，不过看抽象它俩都是 ViewRef。

ng-template LContainer

如果 ng-template LView 不是插入到它自己的 LContainer，那这个 LView 被称为 Moved View，
这个 ng-template LView 自己的 LContainer 会保留这个 LView as a reference 在 LContainer[9]。

总结：

  1. LContainer[8] 装的是 insert 进来的 ViewRef，比如组件 hostView 或者 ng-template embeddedView

  2. LContainer[10-n] 装的是 insert 进来的 LView

  3. LContainer[9] 装的是 Moved Views，这个比较绕，一步一步看。

    首先这个 [9] 只出现在 ng-template LContainer，如果是 <ng-container /> LContainer 那 [9] 一定是 null。

    那怎样才算 Moved View？

    如果一个 ng-template LView 被插入到它自己的 ng-template LContainer，那这不算是 Moved VIew。

    这个 LContainer[8] 和 [10] 会记入这个插入的 LView，但是 [9] 是空的。

    如果一个 ng-template LView 被插入到不是自己的 LContainer (不管是 <ng-container /> LContainer 还是其它 ng-template 的 LContainer)，这就算是 Moved View。

    这个 <ng-container /> LContainer[8] 和 [10] 会记入这个插入的 LView，同时这个 ng-template 自己的 LContainer[9] 也会记入这个 LView。

相关源码

TemplateRef.createEmbeddedView 方法源码在 template_ref.ts

createAndRenderEmbeddedLView 函数的源码在 view_manipulation.ts

ViewContainerRef.insert 源码我们上一篇逛过了，这里补充关于 ng-template 的部分就好。

insertView 函数的源码在 node_manipulation.ts

trackMovedView 函数

 

逛源码 の Template Context

App Template

<ng-template #template let-vm let-whatever="name">
  <h1>{{ appValue }}</h1>
  <h1>{{ vm.value }}</h1>
  <h1>{{ whatever }}</h1>
</ng-template>

app.component.js

let 和 Template Context 之间的 mapping 是靠 compile 完成的。

每一个 LView 都有属于自己的 Context，它存放在 LView[8]。

上面 ctx 便是 ng-template LView[8 Context] 也就是 TemplateRef.createEmbeddedView(templateContext) 传进去的 Template Context。

而 ɵɵnextContext 返回的则是 ng-template LView[14 Declaration LView][8 Context]，这个 Declaration LView 有可能是组件 LView 也有可能是 ng-template LView，不管哪个都会有 context 的。

我们看看 LView[8 Context]  的源码部分

创建 LView 时，context 会被传进去。

创建 ng-template 时，context 会一路传进去

TemplateRef.createEmbeddedView --> createEmbeddedViewImpl --> createAndRenderEmbeddedLView

组件分 2 个步骤，先创建 LView，此时 context 是 null，然后实例化组件，再把组件实例赋值到 LView[8 Context]。

addComponentLogic 函数

instantiateAllDirectives 函数

Dynamic Component 的流程是在 createRootComponentView 函数

createRootComponent 函数

 

逛源码 の Embedded View Injector

App Template

问：把 ng-template 插入 <ng-container /> 后，SayHi 组件可以 inject 到 App 组件吗？

答：可以

App Template & C1 组件 Template

问：把 App Template 里的 ng-template 插入到 C1 Template 里的 <ng-container /> 后，SayHi 组件可以 inject 到 C1 组件吗？

答：不可以！

为什么？

NodeInjector 查找规则的细节

我们在 NodeInjector 和 Dynamic Component 文章中讲解过 NodeInjector 的查找规则。

虽然都对，但是不够细，这里我们补上几个细节。

  1. 在没有 Dynamic Component 和 ng-template 的场景下，LView 的 parent LView 和 Declaration View 一定是相同的。

    在这个前提下，我们可以说 "parent Injector 在 parent LView 里"，也可以说 "parent injector 在 Declaration View 里"。两句都是正确的。

    但是，如果脱离了这个前提，那只有后一句 "parent injector 在 Declaration View 里" 是肯定正确的，前一句未必是正确的。

    因为在 getParentInjectorView 函数中，查找用的是 parentLView[DECLARATION_VIEW] 而不是 parentLView[PARENT]。

  2. 动态创建的组件会有 2 个 LView，一个是组件 Host LView，一个是组件 LView。

    在还没有插入 <ng-container /> 前，Host LView 的 parent LView 和 Declaration LView 都是 null。

    在插入 <ng-container /> 后，Host LView 的 parent LView 变成了 <ng-container /> LContainer，但 Declaration LView 依然是 null。

    也因为这样，组件 NodeInjector 无法往 LContainer 路线去查找，因为它的路线是 Declaration LView 而不是 parent LView，

    我们从 Host LView 的 NodeInjector 资料也可以看出。

    所以动态组件 inject 查找的路线主要是依靠我们传进去的 elementInjector。

  3.  回到 ng-template 的提问

    SayHi 组件的 Declaration View 是 App LView，虽然 C1 里的 <ng-container /> LContainer 是它的 parent LView，但 NodeInjector 找的是 Declaration View，不是 parent LView。

    所以 SayHi 组件只能 inject 到 App 组件不能 inject 到 C1 组件。

Embedded View Injector

在动态创建组件时，我们可以传入 environmentInjector 和 elementInjector。在创建 ng-template 时我们也可以传入 embeddedViewInjector。

embeddedViewInjector 的作用和 elementInjector 是一样的，为了扩展 NodeInjector。

比如上面的例子

SayHi 本来是 inject 不到 C1 组件。

但在 createEmbeddedView 时传入 C1 NodeInjector，这样 SayHi 就可以 inject 到 C1 了。

相关源码在 TemplateRef.createEmbeddedView 过程中的 createAndRenderEmbeddedLView 函数

createLView 倒数第二个参数传入 embeddedViewInjector

在 SayHi 组件 inject(C1Component) 过程中的 getOrCreateInjectable 函数

Embedded View Injector 查找路线是蛮特别的，我们用一个例子配上源码一步一步看
例子：

ng-template 在创建时传入了一个 embededViewInjector，然后在 C3 组件 inject Provider，我们看看它的查找路线图。

lookupTokenUsingEmbeddedInjector 函数的源码在 di.ts

上面第一轮的 white TNode 是 C3，第二轮是 C2，第三轮是 C1，我们直接进入第三轮 C1，因为 C2 和 C3 流程是一样的。

小感悟

当许多场景叠加在一起时，复杂度就上升了。原本 NodeInjector 就蛮多规则的了，再加上 ng-template，再加上 Content Projection，再加上嵌套 ng-template。

上面找 Embedded View Injector 完全没有使用 NodeInjector Bloom 的概念，它就只是单纯一层一层往上找，为此 Angular Team 还特别写了注释

可见框架的实现与维护是很有难度的。

ViewContainerRef.createEmbeddedView

我们在 Dynamic Component 文章中介绍了所有 ViewContainerRef 的功能，唯独遗漏了 createEmbeddedView 方法，因为这个和 ng-template 相关，所以放到本篇才介绍。

我们知道，使用 ViewContainerRef.createComponent 来动态创建组件，它会把 ViewContainerRef.parentInjector 用作 elementInjector。

由此推测，使用 ViewContainerRef.createEmbeddedView 来创建 EmbededView，它应该也会把 ViewContainerRef.parentInjector 用作 embeddedViewInjector 吧？

毕竟 Angular 总是追求统一，追求一致性的嘛👍

但是！你这样想就错了，因为你忘了 Angular 还喜欢挖坑😅

createEmbeddedView 方法的源码在 view_container_ref.ts

它没有使用 ViewContainerRef.parentInjector 作为 embededViewInjector。

所以，如果我们看回这个例子

使用 ViewContainerRef.createEmebedView 的话，SayHi 组件是 inject 不到 C1 组件的。

 

逛源码 の Query Elements

我们在 Query Elements 文章中翻过 Query 的源码，大致的流程是

bootstrapApplication --> renderView --> 创建 TQuery 和 LQuery --> 组件 template 方法 --> 创建 TNode 同时 matching with TQueries -->

refreshView --> refreshQuery --> 拿 matched index 去 LQuery 拿最终的 value 放到 QueryList。

上面有一个重点，matching 在 renderView 结束时就完成了，也就是说它没有 cover 到 Dynamic Component 和 ng-template 的场景。

上一篇 Dynamic Component 我们也说了，动态创建的组件是没有办法被 query 到的。

虽然 ng-template 也是动态生成的，但它却可以被 query 到。

只是它的机制和规则有一点点特别，下面就让我们通过源码来了解它。

renderView

App Template

AppComponent

依据上面讲的流程，在创建 ng-template TNode 时会顺便做 matching。

templateFirstCreatePass 函数源码在 template.ts

TQuery template 方法的源码在 query.ts

回到 templateFirstCreatePass 函数

TQueries.embeddedTView 方法源码在 query.ts

继续

TQuery.embeddedTView 方法的源码

回到 TQueries.embeddedTView

回到 templateFirstCreatePass 函数

以上就是在 bootstrapApplication --> renderView 后会发生的事情。

回到上面的例子，我们看看大家的 TView 里都装了些什么。

App 'h1' TQuery

ng-template TQuery (它在 App TView.data[25].tView.queries[0])

App 'template' TQuery

ng-template TQuery (它在 App TView.data[25].tView.queries[1])

createEmbeddedView

接着我们继续看 TemplateRef.createEmbeddedView 之后的源码

createEmbeddedView --> 创建 ng-template LView --> renderView --> ng-template 的 template 方法 --> 创建 TNode 顺便 matching ng-template TQuery

ng-template LQueries

App 在 refreshView 的时候会执行 App viewQuery 方法，注意，只有 App 有 viewQuery 方法，ng-template 是没有 viewQuery 方法的。

refreshView

接着 insert ng-template LView to <ng-container /> LContainer

App Template

AppComponent

ɵɵqueryRefresh 函数源码在 query.ts (这个源码我们在 Query Elements 文章中有研究过)

collectQueryResults 函数

 App LQueries

ng-template LQueries

总结

  1. App TQuery 和 ng-template TQuery 是有关联的

  2. 当 ng-template 被创建，ng-template TQuery 就会 matched

  3. 当 App refreshView 它除了 query App TQueries 也会 query 有关联的 ng-template TQueries

    所以也会 query 到 ng-template 的内容。

  4. Query 是通过 ng-template LContainer[10-n] 和 [9 Moved Views] 去找到 ng-template LView 的，

    所以不管 ng-template LView 被 insert 到哪一个 View Container 哪怕它在另外一个组件也能 Query 的到。

 

逛源码 の Change Detection

在 Change Detection 文章中，我们就研究过整个 Change Detection 源码和机制了，但是我们刻意避开了 ng-template 的部分。

好，这里就补上。我们直接进入重点 ApplicationRef.tick --> App ViewRef.detectChanges --> detectChangesInternal 函数

detectChangesInternal 函数源码在 change_detection.ts

refreshView 函数

markTransplantedViewsForRefresh 函数

回到 refreshView 函数

detectChangesInEmbeddedViews 函数

回到 detectChangesInternal 函数

总结

detectChanges 会有 2 轮遍历，第一轮来自 refreshView，第二轮来自 detectChangesInViewWhileDirty

refreshView 是 for 常规的更新，它有一套往下遍历的条件。

detectChangesInViewWhileDirty 是 for Signal 和 ng-template Moved Views。

refreshView 时，LContainer 里的 ng-template LView 会被 refreshView，另外 ng-template Moved Views 会被 markAncestorsForTraversal，

然后 detectChangesInViewWhileDirty 会 refreshView 这些 Moved Views。

所以，只要 ng-template LContainer 或者 insert ng-template 的 LContainer 其中一个 refreshView 就可以了。

 

 

目录

上一篇 Angular 18+ 高级教程 – Signals

下一篇 Angular 18+ 高级教程 – Component 组件 の Structural Directive (结构型指令) & Syntax Reference (微语法)

想查看目录，请移步 Angular 18+ 高级教程 – 目录

喜欢请点推荐👍，若发现教程内容以新版脱节请评论通知我。happy coding 😊💻

  

 

posted @ 2024-01-03 21:33  兴杰  阅读(1416)  评论(2)  编辑  收藏  举报