ae-internal-missing-underscore

"名称___应该以下划线开头，因为该声明标记为 @internal。"

备注

当一个声明标记为 @internal 时，最好在其名称前面加上下划线字符 ("_").

假设有一个名为 widget-lib 的库，它导出如下声明

/**
 * @internal
 */
export class Widget {
  public render(): void {}
}

/**
 * @public
 */
export class WidgetManager {
  /**
   * @internal
   */
  public initialize(): void {}
}

// Warning: The name "Widget" should be prefixed with an underscore because
// the declaration is marked as @internal.
// Warning: The name "initialize" should be prefixed with an underscore because
// the declaration is marked as @internal.

当调用者使用此 API 时，他们可能会意外尝试使用 Widget 或 initialize，而没有意识到它们是内部的。API 提取器的 .d.ts 修剪功能可以通过从 TypeScript IntelliSense 中删除这些声明来提供帮助，但是如果你没有使用该功能怎么办？或者，如果你的库被不执行类型检查的 JavaScript 代码使用怎么办？

在这些声明中添加下划线会立即清楚地表明这些 API 有什么特别之处

/**
 * @internal
 */
export class _Widget {
  // This method is @internal, but we don't add an underscore because
  // the container already has an underscore:
  public render(): void {}
}

/**
 * @public
 */
export class WidgetManager {
  /**
   * @internal
   */
  public _initialize(): void {}
}

消费者的代码可能如下所示

import { _Widget, WidgetManager } from 'widget-lib';

let widget = new _Widget(); // <-- bad

let widgetManager = new WidgetManager();
widgetManager._initialize(); // <-- bad

下划线使这个错误更容易发现。

请注意，我们不需要在 Widget 类的每个成员中添加下划线。这将是多余的，因为在 TypeScript 中，你无法在不引用其容器的情况下访问这些项目。因此，API 提取器只检查 ae-internal-missing-underscore 的最外层 @internal 容器。

如何修复

重命名内部声明，使其名称以下划线开头。

或者，如果更改 API 签名会造成太大破坏，你可以选择忽略此消息。默认情况下，它使用 addToApiReportFile 报告，这意味着它将被写入你的 API 报告以供跟踪目的。它不会产生控制台警告，因此不会破坏你的构建（假设你已将 apiReport.enabled 设置为 true）。