构建Angular独立指令库并本地使用时出现TypeError错误

问题概述 #

构建Angular 18独立指令库后，将其安装到新项目中使用时触发以下错误：

TypeError: Cannot read properties of null (reading '11')
    at ɵɵlistener (core.mjs:25618:34)
    at Object.RutDirective_HostBindings [as hostBindings] (rut.directive.ts:8:26)
    at invokeHostBindingsInCreationMode (core.mjs:12436:9)
    at invokeDirectivesHostBindings (core.mjs:12420:9)
    at createDirectivesInstances (core.mjs:11821:5)
    at ɵɵelementStart (core.mjs:23561:5)
    at InputLibraryComponent_Template (input-library.component.html:12:1)
    at executeTemplate (core.mjs:11785:5)
    at renderView (core.mjs:12947:7)
    at renderComponent (core.mjs:12893:3)

但将指令代码直接复制到项目中可正常运行，仅库中的指令出现该问题，同库的管道功能无异常。尝试改用host配置替代@HostListener后仍报相同错误。

核心原因 #

该错误源于Angular Ivy编译链中，库生成的宿主绑定代码存在兼容性问题。通常是由于库的构建配置未正确适配Ivy的编译要求，导致消费项目无法正确解析指令的宿主监听器逻辑。

解决方案 #

1. 检查库的angular.json构建配置 #

确保库的构建启用Ivy（Angular 18默认启用，但需确认配置未被修改）：
打开项目根目录的angular.json，找到对应库的构建配置，确保enableIvy设为true：

"projects": {
  "ngx-test-library": {
    "architect": {
      "build": {
        "options": {
          "enableIvy": true,
          ...
        }
      }
    }
  }
}

2. 验证tsconfig.lib.json配置 #

确保库的TypeScript配置符合Angular库的标准要求：

• compilerOptions.target设为ES2022或更高版本
• compilerOptions.module设为ES2022
• 开启declaration和declarationMap以生成类型定义
  示例关键配置：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "declaration": true,
    "declarationMap": true,
    "outDir": "../../out-tsc/lib",
    "lib": ["ES2022", "dom"],
    ...
  },
  "angularCompilerOptions": {
    "enableIvy": true,
    "compilationMode": "partial"
  }
}

3. 重新构建并更新库 #

执行以下步骤清理并重新构建库：

1. 清理旧构建产物：

ng clean

2. 重新构建库：

ng build ngx-test-library

3. 本地测试时，使用npm link或直接替换消费项目node_modules中的库文件；发布则重新推送新版本。

4. 确保版本一致性 #

确认消费项目与库的Angular版本完全一致（均为18.x.x），版本不匹配可能引发Ivy编译兼容性问题。

5. 优化指令宿主监听器写法 #

添加空值检查并调整参数传递逻辑，提升代码鲁棒性：

import { Directive, EventEmitter, Output } from '@angular/core';
import { rutClean, rutFormat } from './rut-utils';

@Directive({
  selector: '[formatRut]',
  standalone: true,
  host: {
    '(blur)': '_handleBlur($event)',
    '(focus)': '_handleFocus($event)',
    '(input)': '_handleInput($event)',
  },
})
export class RutDirective {
  @Output() public rutChange: EventEmitter<string> = new EventEmitter();

  private _handleBlur(event: FocusEvent): void {
    const input = event.target as HTMLInputElement;
    if (!input) return;
    input.value = rutFormat(input.value) || '';
  }

  private _handleFocus(event: FocusEvent): void {
    const input = event.target as HTMLInputElement;
    if (!input) return;
    input.value = rutClean(input.value);
  }

  private _handleInput(event: InputEvent): void {
    const input = event.target as HTMLInputElement;
    if (!input) return;
    this.rutChange.emit(rutClean(input.value));
  }
}

验证步骤 #

1. 重新构建库并安装到消费项目
2. 启动消费项目，检查错误是否消失
3. 测试指令的focus、blur、input功能是否正常

内容的提问来源于stack exchange，提问作者Jordan Porras