TypeScript 中文网: 文档

全局库

🌐 Global Libraries

一个全局库是指可以从全局作用域访问的库（即无需使用任何形式的 import）。许多库只是暴露一个或多个全局变量以供使用。例如，如果你使用的是 jQuery，可以通过简单地引用 $ 变量来使用它：

🌐 A global library is one that can be accessed from the global scope (i.e. without using any form of import). Many libraries simply expose one or more global variables for use. For example, if you were using jQuery, the $ variable can be used by simply referring to it:

ts
$(() => {
  console.log("hello!");
});

你通常会在全局库的文档中看到有关如何在 HTML 脚本标记中使用该库的指南：

🌐 You’ll usually see guidance in the documentation of a global library of how to use the library in an HTML script tag:

html
<script src="http://a.great.cdn.for/someLib.js"></script>

如今，大多数全球可访问的流行库实际上都是以 UMD 库的形式编写的（见下文）。 UMD 库的文档很难与全局库的文档区分开来。在编写全局声明文件之前，确保该库实际上不是 UMD 库。

🌐 Today, most popular globally-accessible libraries are actually written as UMD libraries (see below). UMD library documentation is hard to distinguish from global library documentation. Before writing a global declaration file, make sure the library isn’t actually UMD.

从代码中识别全局库

🌐 Identifying a Global Library from Code

全局库代码通常非常简单。一个全局的“Hello, world”库可能看起来像这样：

🌐 Global library code is usually extremely simple. A global “Hello, world” library might look like this:

js
function createGreeting(s) {
  return "Hello, " + s;
}

或者像这样：

🌐 or like this:

js
window.createGreeting = function (s) {
  return "Hello, " + s;
};

查看全局库的代码时，你通常会看到：

🌐 When looking at the code of a global library, you’ll usually see:

顶层的 var 语句或 function 声明
一个或多个对 window.someName 的赋值
假设 DOM 原语如 document 或 window 存在

你不会看到：

🌐 You won’t see:

检查或使用诸如 require 或 define 之类的模块加载器
CommonJS/Node.js 风格的导入，形式为 var fs = require("fs");
对 define(...) 的调用
文档描述了如何 require 或导入该库

全局库的示例

🌐 Examples of Global Libraries

因为通常将一个全局库转换为 UMD 库很容易，所以很少有流行的库仍然以全局风格编写。然而，那些体积小且依赖 DOM（或没有任何依赖）的库仍可能是全局的。

🌐 Because it’s usually easy to turn a global library into a UMD library, very few popular libraries are still written in the global style. However, libraries that are small and require the DOM (or have no dependencies) may still be global.

全局库模板

🌐 Global Library Template

你可以在下面看到一个示例 DTS：

🌐 You can see an example DTS below:

ts
// Type definitions for [~THE LIBRARY NAME~] [~OPTIONAL VERSION NUMBER~]
// Project: [~THE PROJECT NAME~]
// Definitions by: [~YOUR NAME~] <[~A URL FOR YOU~]>
/*~ If this library is callable (e.g. can be invoked as myLib(3)),
 *~ include those call signatures here.
 *~ Otherwise, delete this section.
 */
declare function myLib(a: string): string;
declare function myLib(a: number): number;
/*~ If you want the name of this library to be a valid type name,
 *~ you can do so here.
 *~
 *~ For example, this allows us to write 'var x: myLib';
 *~ Be sure this actually makes sense! If it doesn't, just
 *~ delete this declaration and add types inside the namespace below.
 */
interface myLib {
  name: string;
  length: number;
  extras?: string[];
}
/*~ If your library has properties exposed on a global variable,
 *~ place them here.
 *~ You should also place types (interfaces and type alias) here.
 */
declare namespace myLib {
  //~ We can write 'myLib.timeout = 50;'
  let timeout: number;
  //~ We can access 'myLib.version', but not change it
  const version: string;
  //~ There's some class we can create via 'let c = new myLib.Cat(42)'
  //~ Or reference e.g. 'function f(c: myLib.Cat) { ... }
  class Cat {
    constructor(n: number);
    //~ We can read 'c.age' from a 'Cat' instance
    readonly age: number;
    //~ We can invoke 'c.purr()' from a 'Cat' instance
    purr(): void;
  }
  //~ We can declare a variable as
  //~   'var s: myLib.CatSettings = { weight: 5, name: "Maru" };'
  interface CatSettings {
    weight: number;
    name: string;
    tailLength?: number;
  }
  //~ We can write 'const v: myLib.VetID = 42;'
  //~  or 'const v: myLib.VetID = "bob";'
  type VetID = string | number;
  //~ We can invoke 'myLib.checkCat(c)' or 'myLib.checkCat(c, v);'
  function checkCat(c: Cat, s?: VetID);
}

全局 .d.ts

全局库

从代码中识别全局库

全局库的示例

全局库模板