Skip to content

Latest commit

 

History

History
127 lines (98 loc) · 3.55 KB

global.d.ts.md

File metadata and controls

127 lines (98 loc) · 3.55 KB
Raw

全局代码库

全局代码库可以通过全局作用域来访问（例如，不使用任何形式的import语句）。 许多代码库只是简单地导出一个或多个供使用的全局变量。 比如，如果你使用jQuery，那么可以使用$变量来引用它。

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

你通常能够在文档里看到如何在 HTML 的 script 标签里引用代码库：

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

目前，大多数流行的全局代码库都以 UMD 代码库发布。 UMD 代码库与全局代码库很难通过文档来识别。 在编写全局代码库的声明文件之前，确保代码库不是 UMD 代码库。

从代码来识别全局代码库

通常，全局代码库的代码十分简单。 一个全局的“Hello, world”代码库可以如下：

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

或者这样：

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

在阅读全局代码库的代码时，你会看到：

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

你不会看到：

  • 检查或使用了模块加载器，如require或define
  • CommonJS/Node.js 风格的导入语句，如var fs = require("fs");
  • define(...)调用
  • 描述require或导入代码库的文档

全局代码库的示例

由于将全局代码库转换为 UMD 代码库十分容易，因此很少有代码库仍然使用全局代码库风格。 然而，小型的代码库以及需要使用 DOM 的代码库仍然可以是全局的。

全局代码库模版

你可以看到如下声明文件的示例：

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