全局 .d.ts

全局库

¥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 声明

    ¥Top-level var statements or function declarations

  • window.someName 的一项或多项任务

    ¥One or more assignments to window.someName

  • 假设存在像 document 或 window 这样的 DOM 基础类型

    ¥Assumptions that DOM primitives like document or window exist

你不会看到：

¥You won’t see:

  • 检查或使用模块加载器，如 require 或 define

    ¥Checks for, or usage of, module loaders like require or define

  • 表单 var fs = require("fs"); 的 CommonJS/Node.js 样式导入

    ¥CommonJS/Node.js-style imports of the form var fs = require("fs");

  • define(...) 调用

    ¥Calls to define(...)

  • 描述如何 require 或导入库的文档

    ¥Documentation describing how to require or import the library

全局库的示例

¥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);
}