Angular中为自定义库已有类添加方法的编译问题

场景与问题 #

我有一个来自第三方库mat-fileupload的FileData类：

export class FileData {
  public name: string;
  public data: string;

  constructor(name: string, data: string) {
    this.name = name;
    this.data = data;
  }
}

为了实现深拷贝且不修改库代码（深拷贝是应用层需求，库仅负责文件上传），我在Angular应用的src/app/shared/models/extensions/file-data.ts中编写了模块扩充代码，为FileData添加clone方法：

import { FileData } from 'mat-fileupload';

declare module 'mat-fileupload' {
  interface FileData {
    clone(): FileData;
  }
}
if (!FileData.prototype.clone) {
  Object.defineProperty(FileData.prototype,
                        'clone',
                        { enumerable: false,
                          writable: false,
                          configurable: false,
                          value: function clone(this: FileData): FileData {
                            return new FileData(this.name, this.data);
                          } });
}

在Record类中使用该方法：

import { FileData } from 'mat-fileupload';

export class Record extends DataEntry {
  // 其他属性
  public img?: FileData;
  
  constructor(..., img?: FileData) {
    // 其他初始化逻辑
    this.img = img;
  }

  public clone(): Record {
    return new Record(..., this.img?.clone());
  }
}

VS Code的TypeScript编辑器无报错，但执行ng build或ng serve时，Angular编译器报错：

error TS2339: Property 'clone' does not exist on type 'FileData'.

编辑补充：对比rxjs扩展的差异 #

我尝试为rxjs的Observable添加subscribeAndLog方法，代码可正常运行：

// observable.ts
import { Observable } from 'rxjs';
import { Subscription } from 'rxjs';

declare module 'rxjs' {
  interface Observable<T> {
    subscribeAndLog<T>(this: Observable<T>,
                       next?: (value: T) => void,
                       error?: (error: any) => void,
                       complete?: () => void): Subscription;
  }
}

Observable.prototype.subscribeAndLog = function <T>(this: Observable<T>,
                                                    next?: (value: T) => void,
                                                    error?: (error: any) => void,
                                                    complete?: () => void): Subscription {
  console.log('Subscribing to Observable');
  const sub = this.subscribe(next, error, complete);
  return sub;
};

但对FileData做同样操作时，出现错误：

'FileData' only refers to a type, but is being used as a value here.

对应的FileData扩展代码：

// file-data.ts
import { FileData } from 'mat-fileupload';

declare module 'mat-fileupload' {
  interface FileData {
    clone(this: FileData): FileData;
  }
}

// 报错行：'FileData'仅指类型，却被当作值使用
FileData.prototype.clone = function(this: FileData): FileData {
  return new FileData(this.name, this.data);
};

我已在main.ts中导入两个扩展文件：

import './app/shared/models/extensions/file-data';
import './app/shared/models/extensions/observable';

在Record类中，subscribeAndLog可正常调用，但this.img?.clone()仍触发编译错误。

解决方案 #

1. 确保正确获取第三方库的类值 #

问题根源可能是第三方库未正确导出FileData的运行时值（仅导出了类型）。尝试通过模块整体导入来获取类：

import * as MatFileUpload from 'mat-fileupload';

declare module 'mat-fileupload' {
  interface FileData {
    clone(): MatFileUpload.FileData;
  }
}

if (!MatFileUpload.FileData.prototype.clone) {
  Object.defineProperty(MatFileUpload.FileData.prototype, 'clone', {
    enumerable: false,
    writable: false,
    configurable: false,
    value: function(this: MatFileUpload.FileData): MatFileUpload.FileData {
      return new MatFileUpload.FileData(this.name, this.data);
    }
  });
}

2. 确保扩展代码被Angular编译系统识别 #

• 在tsconfig.app.json的include数组中添加扩展文件路径，确保编译时包含：

  "include": [
    "src/app/shared/models/extensions/**/*.ts",
    "src/**/*.d.ts"
  ]
  

• 或者将扩展代码封装为NgModule，在共享模块中导入：

  // file-data-extension.module.ts
  import { NgModule } from '@angular/core';
  import './file-data';
  
  @NgModule({})
  export class FileDataExtensionModule {}
  

  然后在共享模块的imports中引入FileDataExtensionModule，确保代码在应用启动时执行。

3. 替代方案：使用工具函数避免原型扩展 #

如果原型扩展始终无法适配Angular的AOT编译，可以改用工具函数实现深拷贝：

// file-data.utils.ts
import { FileData } from 'mat-fileupload';

export function cloneFileData(file: FileData | undefined): FileData | undefined {
  if (!file) return undefined;
  return new FileData(file.name, file.data);
}

在Record类中使用：

import { cloneFileData } from './file-data.utils';

public clone(): Record {
  return new Record(..., cloneFileData(this.img));
}

为什么rxjs的扩展可以成功？ #

rxjs的Observable是作为类值正确导出的，且Angular编译系统对rxjs模块有特殊处理逻辑，确保类型扩充和原型修改能被正确识别。而自定义第三方库可能在编译配置或导出方式上存在差异，导致类型和运行时值分离，无法直接通过原型扩展。

内容的提问来源于stack exchange，提问作者Otto Abnormalverbraucher