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

前言

在 Attribute Directives 属性型指令文章中，我们学习过了指令。指令是没有 HTML 和 CSS 的组件，它单纯用于封装 JS 的部分。

这一篇我们将继续学习另一种指令 -- Structural Directive 结构型指令。

就代码而言，Structural Directive 和 Attribute Directives 是完全一样的，只是用途不同，因此进行了区分。

Attribute Directives 通常用于监听事件，修改 class，styles 等等。

而 Structural Directive 则主要用于修改 DOM 结构。

在 Dynamic Component 和 ng-template 文章中，我们学习了如何用 MVVM 的方式动态输出/移除组件和模板，

在本文中，我们将继续利用 Structural Directive 来封装这一过程，使其变得可复用。

ngComponentOutlet

ngComponentOutlet 是 Angular built-in 的 Structural Directive，它的作用就是输出 Dynamic Component。

App Template

<button (click)="showComponent = SayHiComponent">show say hi</button>

<button (click)="showComponent = HelloWorldComponent">show hello world</button>

<ng-container [ngComponentOutlet]="showComponent">

有 2 个 Dynamic Component，一个是 SayHi 组件，一个是 HelloWorld 组件。

点击其中一个按钮它就会 createComponent -> insert to <ng-container />。如果 <ng-container /> 已经有组件，它还会先 remove 掉组件再插入新的。

AppComponent

export class AppComponent {

  showComponent!: typeof SayHiComponent | typeof HelloWorldComponent;

  SayHiComponent = SayHiComponent;

  HelloWorldComponent = HelloWorldComponent;

}

效果

如果我们自己写代码实现的话，我们要 query template/container，要 create hostView，要 insert to container，要 remove from container，非常的繁琐，用 ngComponentOutlet 就方便多了。

它也支持传入其它的 options，比如 projectableNodes、inputs 等等。

ngTemplateOutlet

ngTemplateOutlet 也是 Angular built-in 的 Structure Directive，它的用途是输出 ng-template。

App Template

<ng-template #template let-name="name">

  <h1>Hi, {{ name }}</h1>

</ng-template>

<ng-container [ngTemplateOutlet]="template" [ngTemplateOutletContext]="{ name: 'Derrick' }" />

<ng-container [ngTemplateOutlet]="template" [ngTemplateOutletContext]="{ name: 'Alex' }" />

<ng-container [ngTemplateOutlet]="template" [ngTemplateOutletContext]="{ name: 'Richard' }" />

AppComponent 无需任何代码。

效果

底层原理很简单，就是 createEmbeddedView。

令人好奇的是，ngTemplateOutletContext 是 @Input，整个对象是可以替换的。

但我们知道在 createEmbededView 时，我们只能传入一次 TemplateContext 对象，之后只能修改这个对象的属性值，无法替换整个对象。

那 ngTemplateOutlet 是如何做到替换对象的呢？难不成每一次替换都 re-createEmbededView？

不，是它用了 Proxy

相关源码在 ng_template_outlet.ts。

Control Flow 特别提示

下面教的 NgIf、NgForOf、NgSwtich 指令在 Angular v17 版本后已经被 Control Flow 取代了，Control Flow 下一篇会教。

虽然如此，我觉得作为学习 Angular，这 3 个指令是相当不错的，大家不妨看一看。

Show/Hide Element の NgIf 指令

效果

App Template

<button (click)="toggle()">Toggle</button>

<ng-template #template>

  <h1>Hi, Derrick</h1>

</ng-template>

AppComponent

export class AppComponent {

  @ViewChild('template')

  templateRef!: TemplateRef<void>;

  @ViewChild('template', { read: ViewContainerRef })

  viewContainerRef!: ViewContainerRef;

  toggle() {

    if (this.viewContainerRef.length === 0) {

      this.viewContainerRef.createEmbeddedView(this.templateRef);

    } else {

      this.viewContainerRef.clear();

    }

  }

}

很简单的代码，但有一个点值得注意，<ng-template> 这个节点也被用作 ViewContainer。

还记得吗？ViewContainer 可以是任何节点，不一定要是 <ng-container />。其它的比如 <div>, <my-component>, <ng-template> 都是可以作为 ViewContainer 的。

接着把它封装成 Structure Directive。

创建 ShowHide 指令

ng g d show-hide

App Template

<button (click)="show = !show">Toggle</button>

<ng-template [appShowHide]="show">

  <h1>Hi, Derrick</h1>

</ng-template>

我们用一个 show 属性来表示 show or hide。

ShowHideDirective

@Directive({

  selector: '[appShowHide]',

  standalone: true,

})

export class ShowHideDirective implements OnChanges {

  @Input('appShowHide')

  show = false;

  private templateRef: TemplateRef<void> = inject(TemplateRef);

  private viewContainerRef = inject(ViewContainerRef);

  ngOnChanges(changes: SimpleChanges): void {

    if (changes['show'].currentValue) {

      this.viewContainerRef.createEmbeddedView(this.templateRef);

    } else {

      this.viewContainerRef.clear();

    }

  }

}

3个点：

利用 @Input 与外部联系，看什么时候要 show 什么时候要 hide
利用 OnChanges Hook 监听 @input 变化
利用 inject 获取 TemplateRef 和 ViewContainerRef，之前是在 App 所以是用 @ViewChildren，现在位置换了，所以改成用 inject。

效果

NgIf 指令

show / hide 实在是一个太过普遍的需求了，所以 Angular 也有 built-in 指令 -- ngIf，我们不需要自己封装。

<button (click)="show = !show">Toggle</button>

<ng-template [ngIf]="show">

  <h1>Hi, Derrick</h1>

</ng-template>

把指令改成 [ngIf] 就可以了。

另外，我们不需要在 AppComponent imports NgIf 指令哦，因为它已经包含在 CommomModule 里了，至于什么是 Module? 这个在之后的 NgMoudle 章节会教。

ngIfElse

<button (click)="show = !show">Toggle</button>

<ng-template #elseTemplate>

  <h1>else template</h1>

</ng-template>

<ng-template [ngIf]="show" [ngIfElse]="elseTemplate">

  <h1>Hi, Derrick</h1>

</ng-template>

除了 true 的模板，我们还可以提供一个 else 的模板，在 false 的情况下它就会显示 elseTemplate。

效果

NgIfContext

ngIf 除了可以传入 true / false 以外，还可以传入一个 Context 对象，作为判断条件。

<ng-template [ngIf]="{ name: 'Derrick' }" [ngIfElse]="elseTemplate" let-person>

  <h1>Hi, {{ person.name }}</h1>

</ng-template>

当 ngIf 是 false、0、empty string、null 或 undefined 时，它会进入 elseTemplate，

其它情况会作为 ng-template 的 context.$implicit。

再一个例子

<ng-template #loadingTemplate>

  <p>loading...</p>

</ng-template>

<ng-template [ngIf]="person" [ngIfElse]="loadingTemplate" let-person>

  <h1>Hi, {{ person.name }}</h1>

</ng-template>

一开始 person 是 null，所以会显示 loading，当 person 有值后就显示 say hi template。

export class AppComponent {

  person!: { name: string };

  constructor() {

    setTimeout(() => {

      this.person = {

        name: 'Derrick',

      };

    }, 3000);

  }

}

效果

ngTemplateContextGuard

ngIf 指令设置了 static ngTemplateContextGuard 属性，所以 context 是有类型的，ngTemplateContextGuard 我们在 ng-template 文章中里有学过。

NgIf 的源码在 ng_if.ts

Repeating Element の NgForOf 指令

App Template

<div class="card-list">

  <div class="card">

    <p>index: 0</p>

    <p>name: Derrick</p>

    <p>age: 10</p>

  </div>

  <div class="card">

    <p>index: 1</p>

    <p>name: Alex</p>

    <p>age: 15</p>

  </div>

  <div class="card">

    <p>index: 2</p>

    <p>name: Richard</p>

    <p>age: 18</p>

  </div>

</div>

上面有 3 张卡片，element 的结构是相同的，只是数据不同，这种情况就可以使用 NgForOf 指令封装模板。

AppComponent

interface Person {

  name: string;

  age: number;

}

@Component({

  selector: 'app-root',

  standalone: true,

  imports: [CommonModule],

  templateUrl: './app.component.html',

  styleUrl: './app.component.scss',

})

export class AppComponent {

  people: Person[] = [

    { name: 'Derrick', age: 11 },

    { name: 'Alex', age: 18 },

    { name: 'Richard', age: 15 },

  ];

}

把数据抽出来，接着写模板

<div class="card-list">

  <ng-template let-person let-index="index">

    <div class="card">

      <p>index: {{ index }}</p>

      <p>name: {{ person.name }}</p>

      <p>age: {{ person.age }}</p>

    </div>

  </ng-template>

</div>

接着添加 NgForOf 指令

<ng-template ngFor [ngForOf]="people" let-person let-index="index">

NgForOf 指令需要 2 个 attributes 哦，一个 ngFor 和一个 ngForOf。

效果

NgForOf 指令除了 index 和 data，它还包含了许多常用的 variables，比如: count (总数)、first (是不是第一条, boolean)、last、odd (是不是单数)、even。

TrackByFunction

trackByFunction 是用来帮助 NgForOf 指令内部做优化的，我们需要提供一个识别对象的方式。

export class AppComponent {

  people: Person[] = [

    { name: 'Derrick', age: 11 },

    { name: 'Alex', age: 18 },

    { name: 'Richard', age: 15 },

  ];

  trackByName: TrackByFunction<Person> = (_index, person) => {

    return person.name;

  };

}

<ng-template ngFor [ngForOf]="people" [ngForTrackBy]="trackByName" let-person let-index="index">

NgForOf 指令会以 person.name 作为识别 person 对象的 key，在 people 发生变成 (比如排序) 时，以 ViewContainerRef.move 取代 ViewContainerRef.createEmbededView 来进行需改，这样性能就会比较好。

NgSwitch 指令

NgSwitch 也是 Angular built-in 指令，顾名思义。

<button (click)="status = 'Pending'">status to completed</button>

<button (click)="status = 'Completed'">status to pending</button>

<ng-container [ngSwitch]="status">

  <ng-template [ngSwitchCase]="'Completed'">

    <p>complete</p>

  </ng-template>

  <ng-template [ngSwitchCase]="'Pending'">

    <p>pending</p>

  </ng-template>

  <ng-template ngSwitchDefault>

    <p>none</p>

  </ng-template>

</ng-container>

当 status 变化，它会选择对应的模板作为展现。

有 2 点要注意：

[ngSwtich] 可以用于任何 element，不一定要是 <ng-container />

另外，ViewElementRef 并不是 <ng-container /> 哦，其实是 [ngSwitchCase] 和 ngSwtichDefault 的 ng-template。
ngSwtich 指令没有 fallthrough 的概念，match 到后会自动 break。

指令微语法（Syntax Reference）

微语法是 Angular 为了让 Structure Directive 写起来比较好看而发明的。它的唯一用途就是比较好看而已。

我们来看一个 NgIf 指令的例子

AppComponent

interface Person {

  name: string;

}

export class AppComponent {

  person$ = new Observable<Person>((subscriber) => {

    setTimeout(() => {

      subscriber.next({ name: 'Derrick' });

      subscriber.complete();

    }, 2000);

  });

}

App Template

<ng-template #loadingTemplate>

  <p>loading...</p>

</ng-template>

<ng-template [ngIf]="person$ | async" let-person [ngIfElse]="loadingTemplate">

  <p>Hi, {{ person.name }}</p>

</ng-template>

person$ 是一个 RxJS 的 stream，我们用 AsyncPipe 去 subscribe 它，在它还没有 next 之前它是 null，所以会显示 loading template。

下面是用微语法的表达方式

<!-- 普通的 Structure Directive -->

<ng-template [ngIf]="person$ | async" let-person [ngIfElse]="loadingTemplate">

  <p>Hi, {{ person.name }}</p>

</ng-template>

<!-- 微语法 -->

<p *ngIf="person$ | async, let person, else loadingTemplate">Hi, {{ person.name }}</p>

语法解析是这样的：

* 星号会在 p 的外层 wrap 一个 <ng-template>
ngIf 就是指令 [ngIf]，只是省略了方括弧
person$ | async 作为传递给 NgIf 指令的参数
let person 就是 let-person
, 逗号是分割符，用分号 ; 也是可以，不放也是可以
else 会变成 [ngIfElse]，它以 ngIf 作为 prefix 把 else 拼接上去
loadingTemplate 是 [ngIfElse] 的参数

下面这些写法也是正确的

<p *ngIf="person$ | async let person else loadingTemplate">Hi, {{ person.name }}</p>

<p *ngIf="person$ | async else loadingTemplate let person">Hi, {{ person.name }}</p>

除了开头一定要是传递给指令的参数 expression 或者一个 let，后面的语法顺序就不太重要了。

再看一个 NgForOf 指令的微语法

<ng-template #loadingTemplate>

  <p>loading...</p>

</ng-template>

<ng-template [ngIf]="people$ | async" let-people [ngIfElse]="loadingTemplate">

  <!-- 普通的 Structure Directive -->

  <ng-template ngFor [ngForOf]="people" let-person let-index="index" let-isFirst="first" >

    <p>index: {{ index }}</p>

    <p>name: {{ person.name }}</p>

    <p>is first: {{ isFirst }}</p>

  </ng-template>

</ng-template>

外部一层 NgIf 指令负责 loading，有资料了才 for loop。

微语法长这样

<ng-container *ngFor="let person of people, let index = index, let isFirst = first">

  <p>index: {{ index }}</p>

  <p>name: {{ person.name }}</p>

  <p>is first: {{ isFirst }}</p>

</ng-container>

注意，ng-template 换成了 <ng-container>，因为 * 星号解析后会自动 wrap 一层 ng-template 在外面，wrap 了后里面不可以再是一个 ng-template，

所以只好借助 <ng-container>。相等于下面这个写法

<ng-template ngFor [ngForOf]="people" let-person let-index="index" let-isFirst="first">

  <ng-container>

    <p>index: {{ index }}</p>

    <p>name: {{ person.name }}</p>

    <p>is first: {{ isFirst }}</p>

  </ng-container>

</ng-template>

虽然 <ng-container> 没有任何作用，但也没有任何副作用。

另外，切记开头第一句一定要是 let 或者是给指令的 expression 哦，像下面这样是错误的语法。

<ng-container *ngFor="of people, let person, let index = index, let isFirst = first">

下面这些则都可以

<ng-container *ngFor="let person let index = index let isFirst = first of people">

<ng-container *ngFor="let index = index let person let isFirst = first of people">

as Syntax

这句

<ng-container *ngFor="let person of people, let index = index, let isFirst = first">

和这句是等价的

<ng-container *ngFor="let person of people, index as index, first as isFirst">

first as isFirst 等价于 let isFirst = first

as syntax 除了可以当 let 用，还有一个特别的玩法

<ng-container *ngFor="let value of [1, 2, 3] as numbers">

  <pre>{{ numbers | json }}</pre>

</ng-container>

numbers 指向 array [1, 2, 3]，什么原理？

of ... as 是一套的，它会变成 let-numbers="ngForOf"

NgForOfContext 特别设置了这么一个属性。

再一个例子

*ngIf="person$ | async as person"

ngIf...as person，它会变成 let-person="ngIf"

下面这两句的结果是一样的

<p *ngIf="person$ | async, let person">Hi, {{ person.name }}</p>

<p *ngIf="person$ | async as person">Hi, {{ person.name }}</p>

但原理其实不一样，let-person 指的是 context.$implicit，而 as person 指的是 context.ngIf，只是 NgIf 指令的 context.$implicit 刚巧等于 context.ngIf 而已。

小心坑

如果 pipe async 后要判断值，该怎么写？

<h1 *ngIf="(number$ | async) === 5">Hello World 123</h1>

<h1 *ngIf="number$ | async; as number === 5">Hello World 1234</h1>

哪一句是正确的？

答案是第一句。

第二句完全是错误的语法 (虽然没有 error)

它 compile 后长这样

所以，不要写错哦。

一个节点只能有一个微语法

 <!-- 正确 -->

<ng-template

  *ngIf="people$ | async as people else loadingTemplate"

  ngFor [ngForOf]="people" let-person let-index="index" let-isFirst="first">

  <p>index: {{ index }}</p>

  <p>name: {{ person.name }}</p>

  <p>is first: {{ isFirst }}</p>

</ng-template>

<!-- 错误 -->

<ng-template

  *ngIf="people$ | async as people else loadingTemplate"

  *ngFor="let person of people; let index = index, let isFirst=first">

  <p>index: {{ index }}</p>

  <p>name: {{ person.name }}</p>

  <p>is first: {{ isFirst }}</p>

</ng-template>

微语法与 ng-template 的小区别

<ng-template [ngIf]="true">

  <h1>Hello World</h1>

</ng-template>

<h1 *ngIf="true">Hello World</h1>

这两句几乎是等价的，唯一的区别是它们的 tag name 的。

我们看看 compile 之后的代码

我们通常可以忽视这种小区别，但在某些场景，它可能会出现一起反直觉的现象哦。

我们来看个奇葩例子，体会一下。

App Template

<app-test>

  <ng-template [ngIf]="true">

    <h1>Hello World</h1>

  </ng-template>

</app-test>

Test Template

<ng-content select="h1" />

问：<ng-content /> 可以 select 到 h1 吗？

答：不可以，因为 h1 被 ng-template wrap 起来了，<ng-content /> 只能 select 到 first layer child (这个 limitation 我们以前讲过的)。

好，我们换成微语法

<app-test>

  <h1 *ngIf="true">Hello World</h1>

</app-test>

这样 <ng-content /> 就可以 select 到 h1 了，因为微语法后，它的 tag 不再是 ng-template 而是 h1。

微语法总结

微语法只是一种简化的写法而已，其原理依旧是 Structure Directive ng-template + 指令 + [Input] + let。

总结

Structure Directive 其实是一个灵活的方案，而且也不难理解。

只是大部分人入门时都是直接学微语法和 built-in 的 Structure Directive，没有学习 ng-template，

所以往往不懂原理，无法灵活运用。

Angular 为此也推出了 Control Flow 来替代 NgIf、NgForOf、NgSwtich 指令。这种高度的封装虽然牺牲了灵活性，但也降低了新手的学习和试错成本。

下一篇就让我们一起来学习 Control Flow 吧。