Angular 17+ 高级教程 – Component 组件 の Query Elements

<p #var1></p>                       <!-- localNames : ['var1', -1], value: HTMLParagraphElement 实例 -->
<p appDir1 #var2></p>               <!-- localNames : ['var2', -1], value: HTMLParagraphElement 实例 -->
<p appDir1 #var3="appDir1"></p>     <!-- localNames : ['var3', 57], value: Dir1Directive 实例 -->

<app-c1 #var4 />                    <!-- localNames : ['var4', 41], value: C1Component 实例 -->
<app-c1 appDir1 #var5 />            <!-- localNames : ['var5', 41], value: C1Component 实例 -->
<app-c1 appDir1 #var6="appDir1" />  <!-- localNames : ['var6', 57], value: Dir1Directive 实例 -->

<ng-template #var7></ng-template>   <!-- localNames : ['var7', -1], value: TemplateRef 实例 -->
<ng-container #var8></ng-container> <!-- localNames : ['var8', -1], value: Comment 实例 --> 

<p #var1></p>                       <!-- @ViewChildren('var1') value: ElementRef<HTMLParagraphElement> 实例 -->
<p appDir1 #var2></p>               <!-- @ViewChildren('var2') value: ElementRef<HTMLParagraphElement> 实例 -->
<p appDir1 #var3="appDir1"></p>     <!-- @ViewChildren('var3') value: Dir1Directive 实例 -->

<app-c1 #var4 />                    <!-- @ViewChildren('var4') value: C1Component 实例 -->
<app-c1 appDir1 #var5 />            <!-- @ViewChildren('var5') value: C1Component 实例 -->
<app-c1 appDir1 #var6="appDir1" />  <!-- @ViewChildren('var6') value: Dir1Directive 实例 -->

<ng-template #var7></ng-template>   <!-- @ViewChildren('var7') value: TemplateRef 实例 -->
<ng-container #var8></ng-container> <!-- @ViewChildren('var8') value: ElementRef<Comment> 实例 --> 

@ViewChild(Service1)
value!: Service1;
// 上面等同于下面
@ViewChild(Service1, { read: Service1 })
value!: Service1;

class C1Component extends HTMLElement {
  connectedCallback() {
    const shadow = this.attachShadow({ mode: 'open' });
    const template = document.querySelector<HTMLTemplateElement>('template[name="app-c1"]')!;
    const view = template.content.cloneNode(true);
    shadow.append(view);

    // 1. 结果是 0
    console.log(shadow.querySelectorAll('h1').length);
  }
}
customElements.define('app-c1', C1Component);

<template name="app-c1">
  <slot></slot>
</template>

console.log(
  shadow
    .querySelector('slot')!
    .assignedElements()
    .filter(el => el.matches('h1')).length,
); // 1

回到 C1 Definition

结束。

Query static options

由于这个 options 通常只用于 <ng-template> (Dynamic Component 章节得内容，下一篇教)，所以我放到本篇的结尾。

我们看一看省略版的流程

1. 执行 renderView 函数

2. 创建 TQuery

3. 执行 template 方法

4. 创建 TNode，并且与 TQuery 做 matching。

5. 递归 renderView for descendant

6. refreshView

7. PreOrderHooks (e.g. OnInit)

8. ViewHooks (e.g. AfterViewInit)

在 refreshView 之前，TQuery 就已经 matching 完毕了。

假如 Angular 在 PreOrderHooks 之前就执行 ɵɵloadQuery 和 ɵɵqueryRefresh 函数，

那在 PreOrderHooks 阶段，QueryList 就已经会有 results 了，不管是 ElementRef、组件、指令、Provider，通通都拿得到。

只是这个阶段 binding 还没有开始，子组件的 @Input，RNode 的 Interpolation 这些通通都还没有 binding，所以即便可以拿到，也只是一个半成品。

但是，如果它不需要 binding，是一个 "static" 的话，那能早一点拿到它也不是坏事儿。

于是 Angular 提供了一个 static options.

App Template

App 组件

使用 static options 就可以在 PreOrderHooks 阶段拿到 query value，但要记得这个 value 是还没有经过 binding 的。@Input 或 Interpolation 这些都还没有 binding 进去。

逛一逛源码

没有 static options

是 5 号。

有 static options

变 7 号。

在 renderView 里执行 ɵɵviewQuery 函数时

在 renderView 函数

关键就是这里提早执行了 viewQuery 方法 by update mode。本来应该是 refreshView 环节才执行的，现在是提早到 renderView 环节就执行了。

ɵɵqueryRefresh 函数

Limitation & Risk

只有 @ViewChild 和 @ContentChild 有 static options，@Viewchildren 和 @ContentChildren 都没有。

static 只会在 renderView 时，执行一次 ɵɵqueryRefresh，此后每一次 refreshView 执行，它都不会执行。

所以当我们声明式 static，那就真的要是 static，否者可能会掉坑。

Angular 设计这个 static 是专门给 <ng-template> 用的，其它地方最好还是别用了。相关提问 Stack Overflow – How should I use the new static option for @ViewChild in Angular 8?

Query Dynamic Component

Dynamic Component 下一篇才教，不过它和 Query 有一点点关系，不得不说，所以我把这部非放到本篇的结尾。

所谓的 Dynamic Component 就是 document.createElement，document.append，document.removeChild，动态 创建 / 插入 / 移除 组件或者 HTML 元素。

试想想，App Template 原本有 2 个 <p>，我们 Query View 得到了这 2 个 <p>，

后来某 action 通过 Dynamic Component 的方式动态 create + append 了另一个 <p>，现在变成有 3 个 <p> 了。

问：我们的 QueryList 会更新成 3 个 <p> 吗？

答：QueryList 的刷新依赖 refreshView，只要当前 LView 被 refresh 那 QueryList 就会更新变成 3 个 <p>，至于 create + append 是否会导致 LView refresh，下一篇 Dynamic Component 会讲解。

问：我们可以监听到 QueryList 的变化吗？

答：可以，通过 QueryList.changes 方法，它会返回一个 RxJS Observable，subscribe 它就可以了，每当 QueryList 有变化 (append / removeChild) 它就会发布。

console.log('Old Length', this.titleQueryList.length);

this.titleQueryList.changes.subscribe(() => {
  console.log('New Length', this.titleQueryList.length);
});

Signal-based Query (a.k.a Signal Queries)

Signal-based Query 是 Angular v17.2.0 推出的新 Query View 和 Query Content 写法。

大家先别慌，它只是上层写法换了，底层逻辑还是上面教的那一套。

viewChild

before Signal

@ViewChild('title', { read: ElementRef })
titleElementRef!: ElementRef<HTMLHeadingElement>;

after Signal

titleElementRef2 = viewChild.required('title', {
  read: ElementRef<HTMLHeadingElement>,
});

有 3 个变化：

1. Decorator 没了，改成了函数调用。从 v14 的 inject 函数取代 @Inject Decorator 开始，大家都预料到了，有朝一日 Angular Team 一定会把 Decorator 赶尽杀绝的😱。

2. titleElementRef 类型从 ElementRef<HTMLHeadingElement> 变成了 Signal 对象 -- Signal<ElementRef<HTMLHeadingElement>>。

   不过目前 TypeScript 类型推导好像有点问题，titleElementRef2 的类型是 Signal<ElementRef<any>>，它没有办法推导出泛型，所以 read ElementRef 时不够完美。

   我们只能自己声明类型来解决

   titleElementRef2 = viewChild.required<string, ElementRef<HTMLHeadingElement>>('title', {
     read: ElementRef,
   });

   泛型第一个参数是 'title' 的类型，第二个是 read 的类型。

3. titleElementRef! 结尾的 ! 惊叹号变成了 viewChild.required。没有惊叹号就不需要 .required。

   惊叹号或 required 表示一定能 Query 出 Result，不会出现 undefined。

viewChildren

// before Signal
@ViewChildren('title', { read: ElementRef })
titleQueryList!: QueryList<ElementRef<HTMLHeadingElement>>;

// after Signal
titleArray = viewChildren<string, ElementRef<HTMLHeadingElement>>('title', {
  read: ElementRef,
});

2 个知识点：

1. before Signal 返回的类型是 QueryList 对象，after Signal 类型变成了 Signal Array -- Signal<readonly ElementRef<HTMLHeadingElement>[]>。

2. ! 惊叹号不需要 viewChildren.required，因为 @ViewChild 和 viewChildren 即便 Query 不出 Result，也会返回 QueryList 对象或 Signal Empty Array。

contentChild 和 contentChildren

content 的写法和 view 是一样的。把 view 改成 content 就可以了。这里就不给例子了。

Replacement for QueryList and Lifecycle Hook

我们先理一下 QueryList 的特性：

1. QueryList 是在 renderView 阶段创建的，理论上来说，组件在 constructor 阶段肯定还拿不到 QueryList，但从 OnInit Lifecycle Hook 开始就应该可以拿到 QueryList 了。

   但是

   

   这是因为 Angular 是在 refreshView 阶段才将 QueryList 赋值到组件属性的，所以 OnInit 和 AfterContentInit 时组件属性依然是 undefined。

2. QueryList Result Index 是在 renderView 结束时收集完毕的。理论上来说，只要在这个时候调用 ɵɵqueryRefresh 函数，QueryList 就可以拿到 Result 了。

   但是 Angular 一直等到 refreshView 结束后才执行 ɵɵqueryRefresh 函数。

3. 综上 2 个原因，我们只能在 AfterViewInit 阶段获取到 QueryList 和 Query Result。

4. Angular 这样设计的主要原因是不希望让我们拿到不完整的 Result，尽管 renderView 结束后已经可以拿到 Result，但是这些 Result 都是还没有经过 refreshView 的，

   组件没有经过 refreshView 那显然是不完整的，所以 Angular 将时间推迟到了最后，在 AfterViewInit 阶段所有 Query 到的组件都是已经 refreshView 了的。

5. QueryList.changes 只会在后续的改动中发布，第一次是不发布的。

Replacement for QueryList

Signal-based Query 不再曝露 QueryList 对象了 (这个对象依然还在，只是不在公开而已)，取而代之的是 Signal 对象，那我们要怎样监听从前的 QueryList.changes 呢？

QueryList 没了，不要紧，我们多了个 Signal 嘛，Signal 也可以监听丫，要监听 Signal 可以使用 effect 函数。

export class AppComponent {
  titles = viewChildren<string, ElementRef<HTMLHeadingElement>>('title', {
    read: ElementRef,
  });

  constructor() {
    effect(() => {
      console.log(this.titles());
    });
  }
}

每当内部的 QueryList 发生变化 (包括第一次哦，这点和 QueryList.changes 不同)，Signal 就会发布新值，监听 Signal 值的 effect 就会触发。

提醒：effect 只能在 constructor 里执行，因为它依赖 inject 函数。

Replacement for Lifecycle Hook

除了隐藏 QueryList 之外，Signal-based Query 也修改了执行顺序。

export class AppComponent implements OnInit, AfterContentInit, AfterViewInit {
  titles = viewChildren<string, ElementRef<HTMLHeadingElement>>('title', {
    read: ElementRef,
  });

  constructor() {
    console.log(this.titles().length);   // 0
    effect(() => {
      console.log(this.titles().length); // 1
    });
  }
  ngOnInit(): void {
    console.log(this.titles().length);    // 1
  }
  ngAfterContentInit(): void {
    console.log(this.titles().length);    // 1
  }
  ngAfterViewInit(): void {
    console.log(this.titles().length);    // 1
  }
}

在 renderView 结束后，Angular 就执行了 ɵɵqueryRefresh，所以从 OnInit 开始就可以获取到 Query Result 了。(注：此时的 Query Result 依然属于不完整状态，组件还没有 refreshView 的)

Angular 修改这个顺序主要是因为它想把职责交还给我们，它提早给，我们可以选择要不要用，它不给，我们连选择的机会都没有。

Signal-based Query 源码逛一逛

App 组件

export class AppComponent {
  titles = viewChildren<string, ElementRef<HTMLHeadingElement>>('title', {
    read: ElementRef,
  });

  @ViewChildren('title', { read: ElementRef })
  titleQueryList!: ElementRef<HTMLHeadingElement>;
}

一个 Signal-based，一个 Decorator-based，我们做对比。

yarn run ngc -p tsconfig.json

app.component.js

2 个区别：

1. Decorator-based 在 refreshView 阶段做了 2 件事，Signal-based 一件也没有。

   第一件事是赋值给组件属性，Signal-based 改成了在 constructor 阶段完成。

   所以在 constructor 阶段 Decorator-based 的 QueryList 属性是 undefined，而 Signal-based 的 Signal 属性是有 Signal 对象的。

   第二件事是刷新 Query Result，Signal-based 改成了去监听 Dyanmic Component 的 append 和 removeChild，当插入和移除时就会刷新 Query Result。

2. 在 renderView 阶段，Decorator-based 会创建 QueryList，然后收集 Query Result Index，这些 Signal-based 也都会做，做法也都一模一样。

   Signal-based 唯一多做了的事是关联 QueryList 和 Signal。具体流程大致上是这样：

   当 Dynamic Component append 和 removeChild 时，它会 set QueryList to Dirty，Signal 会监听 QueryList Dirty，当 QueryList Dirty 后 Signal 会刷新 Query Result。

viewChildren 函数的源码在 queries.ts

createMultiResultQuerySignalFn 函数的源码在 query_reactive.ts

createQuerySignalFn 函数的源码在 query_reactive.ts

createQuerySignalFn 函数有点绕，一行一行很难讲解，我分几个段落讲解吧。

createComputed 函数是我们常用的 Signal computed 函数的 internal 版本

Computed Signal 的特色是它内部会依赖其它 Signal。

Computed Signal 内部

回到 app.component.js，ɵɵviewQuerySignal 函数的源码在 queries_signals.ts

createViewQuery 函数负责创建 TQuery、LQuery、QueryList。

Signal-based 和 Decorator-based 调用的是同一个 createViewQuery 函数，所以 Signal-based 的区别是在 bindQueryToSignal 函数。

bindQueryToSignal 函数的源码在 query_reactive.ts

总结

1. 有 2 个主要阶段

   第一个是 constructor 

   第二个是 renderView

2. 有 2 个主要对象

   第一个是 QueryList

   第二是 Computed Signal

3. constructor 阶段创建了 Computed Signal

   renderView 阶段创建了 QueryList

4. Computed Signal 负责刷新 Query Result，但刷新 Query Result 需要 QueryList (当然还有其它的，比如 LView 我就不一一写出来的，用 QueryList 做代表)。

   所以在 renderView 创建 QueryList 后，Computed Signal 和 QueryList 需要关联起来。

5. _dirtyCounter Signal 是一个小配角，因为 QueryList on Dirty 的时候要刷新 Query Result，

   而刷新 Query Result 是 Computed Signal 负责的，要触发一个 Signal 只能通过给它一个依赖的 Signal，所以就有了 _dirtyCounter Signal。

6. 最后：QueryList on Dirty 时 -> 通知 _dirtyCounter Signal -> Computed Signal 依赖 _dirtyCounter Signal -> Computed Signal 刷新 Query Result。

7. QueryList on Dirty 是什么时候触发的呢？

   LQueries 负责 set QueryList to Dirty 
   

   

   LQueries 的 insertView、detachView 方法是在 Dynamic Component 插入/移除时被调用的，下一篇才会叫 Dyanmic Component。

   finishViewCreation 会在 LView renderView 后，Child LView renderView 之前被调用。

Might be a bug

export class AppComponent {
  constructor() {
    const titles = viewChildren<string, ElementRef<HTMLHeadingElement>>('title', {
      read: ElementRef,
    });

    effect(() => {
      console.log(titles());
    })
  }
}

如果我们把 viewChildren 返回的 Signal assign to 一个 variable 而不是一个属性的话，compilation 出来的 App Definition 不会有 viewQuery 方法。

也不只是 assign to variable 才出问题，写法不一样它也 compile 不了。

export class AppComponent {
  titles: Signal<readonly ElementRef<HTMLHeadingElement>[]>;

  constructor() {
    this.titles = viewChildren<string, ElementRef<HTMLHeadingElement>>(
      'title', { read: ElementRef, }
    );

    effect(() => {
      console.log(this.titles());
    });
  }
}

像上面这样分开写也是不可以的。提交了 Github Issue，我猜 Angular Team 会说：是的，必须按照官方的 code style 去写，不然 compiler 解析不到。

这也是 compiler 黑魔法常见的问题，因为语法设计本来就是很复杂的，框架如果要支持各做逻辑会很耗精力。

目录

上一篇 Angular 17+ 高级教程 – Component 组件 の 生命周期钩子 (Lifecycle Hooks)

下一篇 Angular 17+ 高级教程 – Component 组件 の Dynamic Component 动态组件

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