Angular 依赖注入实战：ElementRef、HOST_TAG_NAME 与 forwardRef 三大进阶技巧

本篇指南聚焦 Angular 依赖注入（DI）中三个进阶但高频使用的特性：通过 ElementRef 令牌注入组件/指令自身的 DOM 元素、通过 HOST_TAG_NAME 令牌读取宿主元素的标签名，以及用 forwardRef() 函数解决类之间的循环引用问题。读完本文，你将掌握这三个特性的正确用法、适用前提、边界情况（如 ng-container 场景下的可选注入），并能从 Angular 源码 层面理解其底层实现机制，避免在实际项目中踩坑。

一、注入组件自身的 DOM 元素：ElementRef

虽然开发中通常应避免直接操作 DOM，但某些视觉效果和第三方工具仍要求你直接访问 DOM。此时可以通过注入 ElementRef 令牌来获取 @Component 或 @Directive 所对应的底层 DOM 元素：

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

@Directive({
  selector: '[appHighlight]',
})
export class HighlightDirective {
  private element = inject(ElementRef);

  update() {
    this.element.nativeElement.style.color = 'red';
  }
}

上面的示例定义了一个高亮指令：通过字段初始化器中的 inject(ElementRef) 拿到元素引用，再在 update() 方法中直接把文字颜色设为红色。

源码视角：ElementRef 如何被解析

在 packages/core/src/linker/element_ref.ts 中，ElementRef 被实现为对原生元素的轻量包装类：

export class ElementRef<T = any> {
  public nativeElement: T;

  constructor(nativeElement: T) {
    this.nativeElement = nativeElement;
  }

  /**
   * @internal
   * @nocollapse
   */
  static __NG_ELEMENT_ID__: () => ElementRef = injectElementRef;
}

几个值得注意的实现细节：

1. nativeElement 泛型可自定义：ElementRef<T = any> 允许注入时指定元素类型，例如 inject(ElementRef<HTMLDivElement>)，让 nativeElement 获得更精确的类型推导。
2. __NG_ELEMENT_ID__ 静态方法：这是 Ivy 渲染引擎识别“当前节点相关”特殊令牌的约定钩子。注入 ElementRef 时，DI 系统会调用 injectElementRef()，它通过 getCurrentTNode() 获取当前正在初始化的指令/组件所绑定的节点，再用 getNativeByTNode() 从视图中取出对应的真实 DOM 元素。因此 ElementRef 始终解析为“当前注入点所在节点”的元素，这与下文 HOST_TAG_NAME 的解析策略一致。
3. 安全警告：源码注释中明确提示，直接访问 DOM 可能让应用更易受 XSS 攻击，建议在使用 ElementRef 时结合 DomSanitizer 做防护，并将其作为“最后一招”而非首选方案。

此外，源码还提供了 unwrapElementRef() 工具函数：若传入值是 ElementRef 则解包返回 nativeElement，否则原样返回。这在需要兼容“模板引用变量”（模板引用变量本身可能返回 ElementRef）的公共 API 中非常有用。

二、注入宿主元素的标签名：HOST_TAG_NAME

有些指令会同时挂载到 <button>、<a> 等不同元素上，需要根据宿主元素的标签名采取不同行为。此时注入 HOST_TAG_NAME 令牌即可拿到标签名：

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

@Directive({
  selector: '[roleButton]',
})
export class RoleButtonDirective {
  private tagName = inject(HOST_TAG_NAME);

  onAction() {
    switch (this.tagName) {
      case 'button':
        // Handle button action
        break;
      case 'a':
        // Handle anchor action
        break;
      default:
        // Handle other elements
        break;
    }
  }
}

宿主节点可能没有标签名：必须可选注入

注意：如果宿主元素可能没有标签名（例如 ng-container 或 ng-template），必须将注入标记为可选，否则会抛出运行时错误：

tagName: string | null = inject(HOST_TAG_NAME, {optional: true});

这一点可以从 packages/core/src/di/host_tag_name_token.ts 的源码得到印证——HOST_TAG_NAME 令牌上手工挂载了一个 __NG_ELEMENT_ID__ 解析函数：

(HOST_TAG_NAME_TOKEN as any).__NG_ELEMENT_ID__ = (flags: InternalInjectFlags) => {
  const tNode = getCurrentTNode();
  if (tNode === null) {
    throw new RuntimeError(
      RuntimeErrorCode.INVALID_INJECTION_TOKEN,
      ngDevMode &&
        'HOST_TAG_NAME can only be injected in directives and components ' +
          'during construction time (in a class constructor or as a class field initializer)',
    );
  }
  if (tNode.type & TNodeType.Element) {
    return tNode.value;
  }
  if (flags & InternalInjectFlags.Optional) {
    return null;
  }
  throw new RuntimeError(
    RuntimeErrorCode.INVALID_INJECTION_TOKEN,
    ngDevMode &&
      `HOST_TAG_NAME was used on ${getDevModeNodeName(tNode)} which doesn't have an underlying element in the DOM. ...`,
  );
};

从源码可以明确看到三条约束：

• 只能在构造期注入：它必须在指令/组件的构造函数或字段初始化器中注入，因为解析依赖 getCurrentTNode() 这一“当前节点”状态，构造完成后该状态不可用。
• 节点必须是真实 DOM 元素：解析函数检查 tNode.type & TNodeType.Element，只有真实元素节点才返回标签名；<ng-container>（ElementContainer）、<ng-template>（Container）或 @let 声明等“无底层 DOM 元素”的节点会走异常分支。
• 可选注入返回 null：若注入时带了 {optional: true}，对无标签名的节点会返回 null 而不是抛错，这正是文档中 NOTE 提示的底层依据。

另外，源码用 @__PURE__ IIFE 包裹令牌定义，注释说明这是为了让令牌保持可被 tree-shaking：如果应用中没有任何地方注入 HOST_TAG_NAME，打包器可以安全地把整个块丢弃。

三、用 forwardRef 解决循环依赖

在 TypeScript 中，类声明的先后顺序很重要：一个类在定义之前无法被直接引用。如果你遵循“每个文件一个类”的规范，这通常不是问题，但有些场景下循环引用不可避免——例如类 A 引用类 B，同时类 B 又引用类 A，二者中必有一个要先定义。

Angular 的 forwardRef() 函数会创建一个间接引用，由 Angular 稍后再解析。

一个典型的自引用场景是：类在自己的 providers 数组中引用自身。providers 是 @Component() 装饰器函数的属性，必须出现在类定义之前，而此时类名尚不可用，因此需要 forwardRef：

providers: [
  {
    provide: PARENT_MENU_ITEM,
    useExisting: forwardRef(() => MenuItem),
  },
],

上面代码中，MenuItem 组件在 providers 里通过 useExisting 把自己暴露为 PARENT_MENU_ITEM 令牌对应的实现，而 forwardRef(() => MenuItem) 保证这段代码在类定义完成前也能安全书写。

源码视角：forwardRef 的实现机制

packages/core/src/di/forward_ref.ts 中，forwardRef 的本质只是给传入的函数打上一个标记属性：

const __forward_ref__ = getClosureSafeProperty({__forward_ref__: getClosureSafeProperty});

export function forwardRef(forwardRefFn: ForwardRefFn): Type<any> {
  (<any>forwardRefFn).__forward_ref__ = forwardRef;
  if (ngDevMode) {
    (<any>forwardRefFn).toString = function () {
      return stringify(this());
    };
  }
  return <Type<any>>(<any>forwardRefFn);
}

配套的判定与解析函数则是：

export function resolveForwardRef<T>(type: T): T {
  return isForwardRef(type) ? type() : type;
}

export function isForwardRef(fn: any): fn is () => any {
  return (
    typeof fn === 'function' &&
    Object.hasOwn(fn, __forward_ref__) &&
    fn.__forward_ref__ === forwardRef
  );
}

工作机制可以归纳为：forwardRef() 只是给函数打上 __forward_ref__ 标记并原样返回；真正“延迟求值”发生在 resolveForwardRef() 被调用时——它先判断参数是否为 forward ref，是则调用该函数拿到真实类，否则原样返回（恒等函数行为）。

那么谁在调用 resolveForwardRef()？从源码搜索可以看到，解析被集中散布在 DI 容器内部，例如 packages/core/src/di/r3_injector.ts 中：

provider = resolveForwardRef(provider);
// ...
resolveForwardRef(provider.useExisting)

以及 packages/core/src/di/injector_compatibility.ts 中解析 useFactory 依赖时：

const arg = resolveForwardRef(types[i]);

这说明 forwardRef 并非在装饰器求值时立即展开，而是在 R3Injector 真正解析 provider（provide/useExisting/useClass/工厂依赖）的时刻才惰性求值，从而绕开了“类尚未声明”的时间窗口。相关行为在测试 packages/core/test/di/forward_ref_spec.ts 与 packages/core/test/acceptance/di_forward_ref_spec.ts 中有覆盖。

补充：独立组件循环导入

forwardRef 的文档注释中还给出了另一类典型场景——打破独立组件（standalone components）之间 imports 数组的循环引用：

@Component({
  imports: [ChildComponent],
  selector: 'app-parent',
  template: `<app-child [hideParent]="hideParent()"/>`,
})
export class ParentComponent {
   hideParent = input.required<boolean>();
}

@Component({
  imports: [forwardRef(() => ParentComponent)],
  selector: 'app-child',
  template: `
   @if(!hideParent()) {
      <app-parent/>
   }
  `,
})
export class ChildComponent {
   hideParent = input.required<boolean>();
}

即子组件的 imports 通过 forwardRef(() => ParentComponent) 引用尚未声明完成的父组件。这与 provider 场景同理：装饰器属性求值时只需要一个“占位”引用，真正解析推迟到编译/运行时 DI 层。

小结

本文覆盖的三个特性构成了 Angular DI 的实用工具箱：

特性	令牌/函数	典型用途	关键约束
获取自身 DOM 元素	ElementRef	视觉特效、对接操作 DOM 的第三方库	应谨慎使用，注意 XSS 风险；结合 DomSanitizer
获取宿主标签名	HOST_TAG_NAME	同一指令适配多种宿主元素	仅构造期可注入；宿主无真实元素时须 {optional: true}
打破循环引用	forwardRef()	provider 自引用、独立组件循环导入	惰性求值，由 DI 容器在解析 provider 时展开

更全面的 InjectionToken 与自定义 provider 定义，参见仓库中的 定义依赖 provider 指南；实现细节可进一步查阅 packages/core/src/di/host_tag_name_token.ts 与 packages/core/src/di/forward_ref.ts。