.d.ts 卷积

本文继续来自“什么是 API 提取器？”页面的教程。建议从那里开始。

我们将讨论的下一个 API 提取器输出是“.d.ts 卷积”。回想一下，我们的示例项目有以下 TypeScript 源文件

• src/index.ts
• src/log/Log.ts
• src/log/ILogHandler.ts

上述每个文件都构建成一组对应的中间输出

• lib/index.d.ts
• lib/index.js
• lib/log/Log.d.ts
• lib/log/Log.js
• lib/log/ILogHandler.d.ts
• lib/log/ILogHandler.js

我们可以使用像 Webpack 这样的链接器将*.js 文件卷积成一个组合的捆绑文件：dist/sp-core-library.js

同样，API 提取器可以为您的*.d.ts 文件生成卷积：dist/sp-core-library.d.ts

可选地，我们还可以启用 .d.ts “修剪”，它会排除标记为 @beta 的声明出现在卷积文件中：dist/sp-core-library-public.d.ts

修剪后的文件内容将如下所示

dist/sp-core-library-public.d.ts

/* Excluded from this release type: ILogHandler */

/**
 * The Log class provides static methods for logging messages at different levels (verbose,
 * info, warning, error) and with context information. Context information helps identify
 * which component generated the messages and makes the messages useful and filterable.
 * @public
 */
export declare class Log {
  private static _logHandler;

  /* Excluded from this release type: initialize */

  /**
   * Logs a verbose message
   * @param   source - the source from where the message is logged, e.g., the class name.
   *          The source provides context information for the logged message.
   *          If the source's length is more than 20, only the first 20 characters are kept.
   * @param   message - the message to be logged
   *          If the message's length is more than 100, only the first 100 characters are kept.
   */
  public static verbose(source: string, message: string, scope?: ServiceScope): void;

  . . .
  public static info(source: string, message: string): void;

  . . .
  public static warn(source: string, message: string): void;

  . . .
  public static error(source: string, error: Error): void;
}

启用修剪后，开发人员不再需要担心在他们针对生产环境时意外地依赖不稳定的 Log.initialize() 函数。该函数甚至不会出现在他们的 VS Code IntelliSense 中！如果他们想使用 @beta API，他们将明确选择加入“beta”版本。对于真实的 @microsoft/sp-core-library 包，“选择加入”是通过安装带有 -plusbeta 后缀的 特殊版本号 来完成的（但是，其他方法也是可行的）。

API 提取器的 .d.ts 卷积功能相当复杂。例如，它支持

• 导出名称与原始定义不同的声明
• 从其他包导入的类型
• export * from 与其他包的关系
• 合并的声明

对于 .d.ts 卷积来说，一个重要的限制是假设您的包只有一个入口点。（如果不是这种情况，您可能无法使用 API 提取器的此功能，但您仍然可以使用 API 报告和文档生成功能。）