diff --git a/docs/documentation/zh/declaration-files/templates/global.d.ts.md b/docs/documentation/zh/declaration-files/templates/global.d.ts.md index 210996d..25bdd5a 100644 --- a/docs/documentation/zh/declaration-files/templates/global.d.ts.md +++ b/docs/documentation/zh/declaration-files/templates/global.d.ts.md @@ -4,7 +4,7 @@ layout: docs permalink: /zh/docs/handbook/declaration-files/templates/global-d-ts.html --- -## Global Libraries +## 全局库 -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](https://jquery.com/), the `$` variable can be used by simply referring to it: +全局库是可以从全局范围访问的库(即不使用任何形式的 `import`)。许多库只是简单地公开一个或多个全局变量供使用。例如,如果你正在使用 [jQuery](https://jquery.com/),则可以通过简单地引用 `$` 变量来使用: ```ts $(() => { - console.log("hello!"); + console.log("你好!"); }); ``` -You'll usually see guidance in the documentation of a global library of how to use the library in an HTML script tag: +你通常会在全局库的文档中看到如何在 HTML 脚本标签中使用库的指导: ```html ``` -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. +如今,大多数流行的全局访问库实际上是以 UMD 库的形式编写的(请参见下文)。UMD 库文档很难与全局库文档区分开来。在编写全局声明文件之前,请确保库实际上不是 UMD。 -## Identifying a Global Library from Code +## 从代码中识别全局库 -Global library code is usually extremely simple. -A global "Hello, world" library might look like this: +全局库代码通常非常简单。一个全局的 "Hello, world" 库可能如下所示: ```js function createGreeting(s) { - return "Hello, " + s; + return "你好," + s; } ``` -or like this: +或者像这样: ```js window.createGreeting = function (s) { - return "Hello, " + s; + return "你好," + s; }; ``` -When looking at the code of a global library, you'll usually see: +在查看全局库的代码时,你通常会看到: -- Top-level `var` statements or `function` declarations -- One or more assignments to `window.someName` -- Assumptions that DOM primitives like `document` or `window` exist +- 顶层的 `var` 语句或 `function` 声明 +- 一个或多个对 `window.someName` 的赋值 +- 假设 DOM 原语如 `document` 或 `window` 存在 -You _won't_ see: +你*不会*看到: -- Checks for, or usage of, module loaders like `require` or `define` -- CommonJS/Node.js-style imports of the form `var fs = require("fs");` -- Calls to `define(...)` -- Documentation describing how to `require` or import the library +- 检查或使用像 `require` 或 `define` 这样的模块加载器 +- CommonJS/Node.js 风格的导入形式,如 `var fs = require("fs");` +- 调用 `define(...)` +- 描述如何 `require` 或导入库的文档 -## Examples of Global Libraries +## 全局库示例 -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. +因为通常很容易将全局库转换为 UMD 库,所以很少有流行的库仍然以全局样式编写。但是,需要 DOM(或没有依赖性)的小型库可能仍然是全局的。 -## Global Library Template +## 全局库模板 -You can see an example DTS below: +以下是一个示例类型定义(Type Definitions, DTS): ```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. +/*~ 如果这个库可以调用(例如,可以像 myLib(3) 一样调用), + *~ 请在这里包含这些调用签名。 + *~ 否则,删除此部分。 */ 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. + *~ 例如,这允许我们写 'var x: myLib'; + *~ 确保这实际上是有意义的!如果没有意义,删除此声明并 + *~ 在下面的命名空间中添加类型。 */ interface myLib { name: string; @@ -103,30 +97,30 @@ interface myLib { 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;' + //~ 我们可以写 'myLib.timeout = 50;' let timeout: number; - //~ We can access 'myLib.version', but not change it + //~ 我们可以访问 'myLib.version',但不能更改它 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) { ... } + //~ 有一个类可以通过 'let c = new myLib.Cat(42)' 创建 + //~ 或引用,例如 'function f(c: myLib.Cat) { ... }' class Cat { constructor(n: number); - //~ We can read 'c.age' from a 'Cat' instance + //~ 我们可以从 'Cat' 实例中读取 'c.age' readonly age: number; - //~ We can invoke 'c.purr()' from a 'Cat' instance + //~ 我们可以从 'Cat' 实例中调用 'c.purr()' purr(): void; } - //~ We can declare a variable as + //~ 我们可以将变量声明为 //~ 'var s: myLib.CatSettings = { weight: 5, name: "Maru" };' interface CatSettings { weight: number; @@ -134,11 +128,11 @@ declare namespace myLib { tailLength?: number; } - //~ We can write 'const v: myLib.VetID = 42;' - //~ or 'const v: myLib.VetID = "bob";' + //~ 我们可以写 'const v: myLib.VetID = 42;' + //~ 或 'const v: myLib.VetID = "bob";' type VetID = string | number; - //~ We can invoke 'myLib.checkCat(c)' or 'myLib.checkCat(c, v);' + //~ 我们可以调用 'myLib.checkCat(c)' 或 'myLib.checkCat(c, v);' function checkCat(c: Cat, s?: VetID); } ```