如果库的实现未与 TS 项目集成,如何使用 d.ts 文件导出的常量类型?
How to consume a d.ts file's exported const types if the library's implementation is not integrated with the TS project?
DefinitelyTyped 有许多库的类型定义,但当 Javascript 实现与 Typescript 分开时,我经常找不到使用它们的好方法,比如当库将自己分配给 属性 的 window 到
<script src="https://example.com/library.js">
tag,当我管理的 JS 包在另一个单独的脚本中时。 (尽管将所有内容捆绑在一起 包括 库是标准且可靠的方法,但为了这个问题假设我没有将库正确导入我的 TS 项目的选项。 ) 例如,假设我为名为 myLib
:
的库找到了一个漂亮的定义文件
// 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,例如:
// index.ts
import { AnInterface } from './my-lib';
const something: AnInterface = { foo: 'foo' };
console.log(something.foo);
这可行,但我想访问实际库对象的形状及其 属性 值(函数和字符串等),而不仅仅是接口。如果我这样做
import * as myLib from './my-lib';
然后 myLib
标识符变成了一个命名空间,我可以从中引用导出的接口,但就像上面一样,我仍然无法访问 export const
和 export function
形状来自 my-lib.d.ts
。 (当然,尝试使用导入的命名空间来声明库对象是行不通的:Cannot use namespace 'myLib' as a type.
即使我可以这样做,也不一定是安全的,因为为浏览器打包的库可能我们的结构与库的 Node 导出对象略有不同)
如果我手动将 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 项目集成,从而使库及其类型都可以 import
ed 和使用而不会大惊小怪,但如果那样的话不可能,我还有 good 选项吗?我可以检查真实库对象的属性并向定义文件添加一个接口,其中包括所有这些属性及其类型,但是必须修改 DT 接受并被其他人使用的半规范源定义文件感觉错误的。我希望能够导入定义文件导出的形状,并在不修改原始文件的情况下从中创建界面,但这可能是不可能的。
是否有更优雅的解决方案,或者我碰巧遇到的定义文件根本不适合我的目标,因此必须修改?
如果模块有 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 即可访问模块导出。如果全局导出与我期望的浏览器兼容,这将起作用。
你在处理什么
when a library assigns itself to a property of the window
这叫做 UMD 包。这些是通过在文档中的 <script />
标记内添加 link 而消耗的,它们将自身附加到全局范围。
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
或使用通配符 (*
) 导入整个命名空间导入。
脚本和模块有什么区别?
脚本 将是HTML 文档中<script />
标记内的JavaScript 运行 的一部分。它可以内联或从文件加载。这就是 JavaScript 在浏览器中一直使用的方式。
A module 是一个 JavaScript (TypeScript) 文件,至少有一个 import
或 export
语句。它们是 ECMAScript 标准的一部分,并非在任何地方都受支持。通常,您在项目中创建 modules,然后让像 Webpack 这样的捆绑器创建一个捆绑包供您的应用程序使用。
正在使用 UMD 包
通过访问全局 Foo
命名空间使用脚本、变量和类型(就像 jQuery 和 $
):
const bar = Foo.bar;
const meaningOfLife: Foo.MeaningOfLife = 42;
一个脚本,bar
的类型是使用导入类型语法导入的:
const baz: typeof import ('foo').bar = 'hello';
一个模块,bar
变量是使用命名导入导入的。
import { bar } from 'foo';
bar.toUpperCase();
一个模块,整个包作为命名空间导入:
import * as foo from 'foo';
foo.bar.toUpperCase();
全局范围与 window
如果这样的库类型正确,作为消费者的您无需执行任何操作即可使其正常工作。它将自动在您的全局范围内可用,并且不需要 Window
的扩充。
但是,如果您想明确地将图书馆的内容附加到 window
,您也可以这样做:
declare global {
interface Window {
Foo: typeof import('foo');
}
}
window.Foo.bar;
DefinitelyTyped 有许多库的类型定义,但当 Javascript 实现与 Typescript 分开时,我经常找不到使用它们的好方法,比如当库将自己分配给 属性 的 window 到
<script src="https://example.com/library.js">
tag,当我管理的 JS 包在另一个单独的脚本中时。 (尽管将所有内容捆绑在一起 包括 库是标准且可靠的方法,但为了这个问题假设我没有将库正确导入我的 TS 项目的选项。 ) 例如,假设我为名为 myLib
:
// 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,例如:
// index.ts
import { AnInterface } from './my-lib';
const something: AnInterface = { foo: 'foo' };
console.log(something.foo);
这可行,但我想访问实际库对象的形状及其 属性 值(函数和字符串等),而不仅仅是接口。如果我这样做
import * as myLib from './my-lib';
然后 myLib
标识符变成了一个命名空间,我可以从中引用导出的接口,但就像上面一样,我仍然无法访问 export const
和 export function
形状来自 my-lib.d.ts
。 (当然,尝试使用导入的命名空间来声明库对象是行不通的:Cannot use namespace 'myLib' as a type.
即使我可以这样做,也不一定是安全的,因为为浏览器打包的库可能我们的结构与库的 Node 导出对象略有不同)
如果我手动将 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 项目集成,从而使库及其类型都可以 import
ed 和使用而不会大惊小怪,但如果那样的话不可能,我还有 good 选项吗?我可以检查真实库对象的属性并向定义文件添加一个接口,其中包括所有这些属性及其类型,但是必须修改 DT 接受并被其他人使用的半规范源定义文件感觉错误的。我希望能够导入定义文件导出的形状,并在不修改原始文件的情况下从中创建界面,但这可能是不可能的。
是否有更优雅的解决方案,或者我碰巧遇到的定义文件根本不适合我的目标,因此必须修改?
如果模块有 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 即可访问模块导出。如果全局导出与我期望的浏览器兼容,这将起作用。
你在处理什么
when a library assigns itself to a property of the window
这叫做 UMD 包。这些是通过在文档中的 <script />
标记内添加 link 而消耗的,它们将自身附加到全局范围。
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
的变量
脚本和模块有什么区别?
脚本 将是HTML 文档中<script />
标记内的JavaScript 运行 的一部分。它可以内联或从文件加载。这就是 JavaScript 在浏览器中一直使用的方式。
A module 是一个 JavaScript (TypeScript) 文件,至少有一个 import
或 export
语句。它们是 ECMAScript 标准的一部分,并非在任何地方都受支持。通常,您在项目中创建 modules,然后让像 Webpack 这样的捆绑器创建一个捆绑包供您的应用程序使用。
正在使用 UMD 包
通过访问全局 Foo
命名空间使用脚本、变量和类型(就像 jQuery 和 $
):
const bar = Foo.bar;
const meaningOfLife: Foo.MeaningOfLife = 42;
一个脚本,bar
的类型是使用导入类型语法导入的:
const baz: typeof import ('foo').bar = 'hello';
一个模块,bar
变量是使用命名导入导入的。
import { bar } from 'foo';
bar.toUpperCase();
一个模块,整个包作为命名空间导入:
import * as foo from 'foo';
foo.bar.toUpperCase();
全局范围与 window
如果这样的库类型正确,作为消费者的您无需执行任何操作即可使其正常工作。它将自动在您的全局范围内可用,并且不需要 Window
的扩充。
但是,如果您想明确地将图书馆的内容附加到 window
,您也可以这样做:
declare global {
interface Window {
Foo: typeof import('foo');
}
}
window.Foo.bar;