如果库的实现未与 TS 项目集成，如何使用 d.ts 文件导出的 const 类型？

Posted 2023-03-07

【中文标题】如果库的实现未与 TS 项目集成，如何使用 d.ts 文件导出的 const 类型？

【英文标题】：How to consume a d.ts file's exported const types if the library's implementation is not integrated with the TS project?

【发布时间】：2019-09-10 17:36:32

【问题描述】：

DefinitelyTyped 有许多库的类型定义，但是当 javascript 实现与 Typescript 分离时，我经常找不到使用它们的好方法，例如当库通过 a 将自身分配给窗口的属性时

<script src="https://example.com/library.js">

标签，当我管理的 JS 包在另一个单独的脚本中时。 （即使将所有内容捆绑在一起包括库是标准且可靠的方法，为了这个问题，假设我没有将库正确导入到我的 TS 项目中的选项。）例如，假设我为名为@9​​87654322@ 的库找到了一个漂亮的定义文件：

// my-lib.d.ts
export const doThing1: () => number;
export const doThing2: () => string;
export const version: string;
export interface AnInterface 
  foo: string;

export as namespace myLib;

在 JS 中，我可以通过调用 window.myLib.doThing1() 和 window.myLib.doThing2() 来使用 myLib。如何导入整个 window.myLib 对象的形状，以便我可以将其声明为 window 的属性？可以看到可以导入导出的interfaces，eg：

// index.ts
import  AnInterface  from './my-lib';
const something: AnInterface =  foo: 'foo' ;
console.log(something.foo);

这可行，但我想访问实际库对象的形状及其属性值（函数和字符串等），而不仅仅是接口。如果我这样做了

import * as myLib from './my-lib';

然后myLib 标识符变成一个命名空间，我可以从中引用导出的接口，但就像上面一样，我仍然无法访问来自my-lib.d.ts 的export const 和export function 形状。 （当然，尝试使用导入的命名空间来声明库对象是行不通的：Cannot use namespace 'myLib' as a type. 即使我可以这样做，那也不一定是安全的，因为为浏览器打包的库很可能是结构与库的节点导出对象略有不同）

如果我手动将d.ts 的部分内容复制并粘贴到我自己的脚本中，我可以拼凑出一些可行的东西：

// index.ts
declare global 
  interface Window 
    myLib: 
      doThing1: () => number;
      doThing2: () => string;
      version: string;
    ;
  

但这很麻烦，很耗时，而且肯定不是做这种事情的正确方法。当我遇到这种情况时，我希望喜欢能够做一些简短而优雅的事情，比如：

// index.ts
import myLibObjectInterface from './my-lib.d.ts'; // this line is not correct
declare global 
  interface Window 
    myLib: myLibObjectInterface
  

一些定义文件包含库对象的接口，例如 jQuery，它可以：

// index.d.ts
/// <reference path="JQuery.d.ts" />

// jQuery.d.ts
interface JQuery<TElement = htmlElement> extends Iterable<TElement> 
  // lots and lots of definitions

那么一切都很好 - 我可以使用 interface Window $: jQuery ，但许多最初不是为浏览器使用而创建的库不提供这样的接口。

如前所述，最好的解决方案是将库的实现与 TS 项目集成，允许库及其类型均为 imported 并轻松使用，但如果不可能，请执行我还有任何好的选项吗？我可以检查真实库对象上的属性并向定义文件添加一个接口，其中包括所有此类属性及其类型，但是必须修改 DT 接受并被其他人使用的半规范源定义文件感觉错误的。我希望能够导入定义文件导出的形状，并从它们创建一个界面而不修改原始文件，但这可能是不可能的。

是否有更优雅的解决方案，或者我碰巧遇到的定义文件根本不适合我的目标，因此必须修改？

【参考方案1】：

如果模块有export as namespace myLib，那么模块已经将库导出为全局对象。因此，您可以将库用作：

let a:myLib.AnInterface;
let b =  myLib.doThing1();

只要您使用库的文件本身不是模块本身（即它不包含import 和export 语句），这就是正确的。

export  // module now
let a:myLib.AnInterface; // Types are still ok without the import
let b =  myLib.doThing1(); // Expressions are not ok, ERR: 'myLib' refers to a UMD global, but the current file is a module. Consider adding an import instead.ts(2686)

您可以使用导入类型向Window 添加与库类型相同类型的属性（相信在2.9 中添加）

// myLibGlobal.d.ts
// must not be a module, must not contain import/ export 
interface Window 
    myLib: typeof import('./myLib') // lib name here



//usage.ts
export  // module
let a:myLib.AnInterface; // Types are still ok without the import (if we have the export as namespace
let b =  window.myLib.doThing1(); // acces through window ok now

编辑

显然，Typescript 团队实际上一直在为这个问题做一些事情。正如您在 PR 中所读到的，下一版本的 typescript 将包含 allowUmdGlobalAccess 标志。此标志将允许从模块访问 UMD 模块全局变量。将此标志设置为 true，此代码将有效：

export  // module now
let a:myLib.AnInterface; // Types are still ok without the import
let b =  myLib.doThing1(); // ok, on typescript@3.5.0-dev.20190425

这意味着您可以直接访问模块导出，而无需使用 window.如果全局导出与我期望的浏览器兼容，这将起作用。

【讨论】：

我不明白为什么typeof可以在那里安全使用

@CristianTraìna 不确定你的意思？ import('./myLib') 允许我们在不导入的情况下访问模块中的类型。 typeof import('./myLib') 为我们提供了导入对象的类型，而无需实际导入它。

谢谢，这很有帮助！我的消费者总是模块，因为它是一个更大项目的一部分，我没想过尝试创建一个仅具有副作用的非模块文件，这让我觉得很奇怪。

因此，为了避免修改原始定义文件，在非模块中，要么创建一个（全局）变量，其属性引用库的（const myLibObj = doThing1: myLib.doThing1, ...），要么创建一个（全局）接口以后可以用interface MyLib = doThing1: typeof import('myLib').doThing1 ...，让库的位置可以更灵活的描述。

@Snow 你不需要拼出库的所有成员（尽管如果你愿意也可以），typeof import('myLib') 表示一个包含模块所有值导出的对象（基本上是module.exports 的类型）。你对这个类型做什么取决于你，打字稿只会帮助你在类型中描述它，它不会以任何方式确保模块在运行时存在（即它不关心myLib 是如何存在的Window 在运行时，您必须确保它在那里，并且从我对问题window.myLib 已经工作的阅读来看，这只是一个打字问题）

【参考方案2】：

你在处理什么

当一个库将自己分配给窗口的一个属性时

这称为 UMD 包。这些是通过在文档中的 <script /> 标记内添加链接所消耗的，它们将自身附加到全局范围。

UMD 包不必以这种方式使用——它们也可以作为模块使用，使用import（或require）语句。

TypeScript 支持这两种用法。

UMD 包应该如何输入

declare namespace Foo 
  export const bar: string;
  export type MeaningOfLife = number;


export as namespace Foo;
export = Foo;

这个定义告诉 TypeScript：

如果消费文件是一个脚本，那么在全局范围内有一个名为bar的变量 如果消费文件是一个模块，那么您可以使用命名导入来导入bar，或者使用通配符(*) 导入来导入整个命名空间。

脚本和模块有什么区别？

script 是在 HTML 文档的 <script /> 标记内运行的一段 JavaScript。它可以内联或从文件加载。这就是 JavaScript 在浏览器中一直使用的方式。

模块 是一个 JavaScript (TypeScript) 文件，它至少有一个 import 或 export 语句。它们是 ECMAScript 标准的一部分，并非所有地方都支持。通常，您在项目中创建 模块，然后让 Webpack 之类的打包器创建一个包供您的应用程序使用。

使用 UMD 包

通过访问全局 Foo 命名空间（就像 jQuery 和 $）来使用脚本、变量和类型：

const bar = Foo.bar;
const meaningOfLife: Foo.MeaningOfLife = 42;

一个脚本，bar的类型是使用import type语法导入的：

const baz: typeof import ('foo').bar = 'hello';

一个模块，bar 变量是使用命名导入来导入的。

import  bar  from 'foo';

bar.toUpperCase();

一个模块，整个包作为命名空间导入：

import * as foo from 'foo';

foo.bar.toUpperCase();

全局范围与窗口

如果这样一个库的类型正确，作为消费者的你不需要做任何事情来让它工作。它将自动在您的全局范围内可用，无需对 Window 进行扩充。

但是，如果您想明确地将库的内容附加到 window，您也可以这样做：

declare global 
  interface Window 
    Foo: typeof import('foo');
  


window.Foo.bar;