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 Componentng-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个点:

  1. 利用 @Input 与外部联系,看什么时候要 show 什么时候要 hide

  2. 利用 OnChanges Hook 监听 @input 变化

  3. 利用 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 点要注意:

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

    另外,ViewElementRef 并不是 <ng-container /> 哦,其实是 [ngSwitchCase] 和 ngSwtichDefault 的 ng-template。

  2. 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 吧。

 

 

目录

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

下一篇 Angular 18+ 高级教程 – Component 组件 の Control Flow

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

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

 

posted @ 2024-01-08 22:49  兴杰  阅读(417)  评论(0编辑  收藏  举报