声明参考手册

本指南的目的是教你如何编写高质量的定义文件。本指南的结构是展示一些 API 的文档，以及该 API 的示例用法，并解释如何编写相应的声明。

¥The purpose of this guide is to teach you how to write a high-quality definition file. This guide is structured by showing documentation for some API, along with sample usage of that API, and explaining how to write the corresponding declaration.

这些示例按复杂程度大致递增的顺序排列。

¥These examples are ordered in approximately increasing order of complexity.

具有属性的对象

¥Objects with Properties

文档

¥Documentation

全局变量 myLib 有一个函数 makeGreeting 用于创建问候语，还有一个属性 numberOfGreetings 表示到目前为止问候语的数量。

¥The global variable myLib has a function makeGreeting for creating greetings, and a property numberOfGreetings indicating the number of greetings made so far.

代码

¥Code

ts
let result = myLib.makeGreeting("hello, world");
console.log("The computed greeting is:" + result);
let count = myLib.numberOfGreetings;

声明

¥Declaration

使用 declare namespace 来描述通过点分表示法访问的类型或值。

¥Use declare namespace to describe types or values accessed by dotted notation.

ts
declare namespace myLib {
  function makeGreeting(s: string): string;
  let numberOfGreetings: number;
}

重载函数

¥Overloaded Functions

文档

¥Documentation

getWidget 函数接受一个数字并返回一个小部件，或者接受一个字符串并返回一个小部件数组。

¥The getWidget function accepts a number and returns a Widget, or accepts a string and returns a Widget array.

代码

¥Code

ts
let x: Widget = getWidget(43);
let arr: Widget[] = getWidget("all of them");

声明

¥Declaration

ts
declare function getWidget(n: number): Widget;
declare function getWidget(s: string): Widget[];

可重用类型（接口）

¥Reusable Types (Interfaces)

文档

¥Documentation

指定问候语时，必须传递 GreetingSettings 对象。该对象具有以下属性：

¥When specifying a greeting, you must pass a GreetingSettings object. This object has the following properties:

1 - 问候语：必填字符串

¥1 - greeting: Mandatory string

2 - 期间：可选的时间长度（以毫秒为单位）

¥2 - duration: Optional length of time (in milliseconds)

3 - 颜色：可选字符串，例如 ‘#ff00ff’

¥3 - color: Optional string, e.g. ‘#ff00ff’

代码

¥Code

ts
greet({
  greeting: "hello world",
  duration: 4000
});

声明

¥Declaration

使用 interface 定义具有属性的类型。

¥Use an interface to define a type with properties.

ts
interface GreetingSettings {
  greeting: string;
  duration?: number;
  color?: string;
}
declare function greet(setting: GreetingSettings): void;

可重用类型（类型别名）

¥Reusable Types (Type Aliases)

文档

¥Documentation

在任何需要问候语的地方，你都可以提供 string、返回 string 的函数或 Greeter 实例。

¥Anywhere a greeting is expected, you can provide a string, a function returning a string, or a Greeter instance.

代码

¥Code

ts
function getGreeting() {
  return "howdy";
}
class MyGreeter extends Greeter {}
greet("hello");
greet(getGreeting);
greet(new MyGreeter());

声明

¥Declaration

你可以使用类型别名来简化类型：

¥You can use a type alias to make a shorthand for a type:

ts
type GreetingLike = string | (() => string) | MyGreeter;
declare function greet(g: GreetingLike): void;

组织类型

¥Organizing Types

文档

¥Documentation

greeter 对象可以记录到文件或显示警报。你可以向 .log(...) 提供 LogOptions，向 .alert(...) 提供警报选项

¥The greeter object can log to a file or display an alert. You can provide LogOptions to .log(...) and alert options to .alert(...)

代码

¥Code

ts
const g = new Greeter("Hello");
g.log({ verbose: true });
g.alert({ modal: false, title: "Current Greeting" });

声明

¥Declaration

使用名称空间来组织类型。

¥Use namespaces to organize types.

ts
declare namespace GreetingLib {
  interface LogOptions {
    verbose?: boolean;
  }
  interface AlertOptions {
    modal: boolean;
    title?: string;
    color?: string;
  }
}

你还可以在一个声明中创建嵌套的命名空间：

¥You can also create nested namespaces in one declaration:

ts
declare namespace GreetingLib.Options {
  // Refer to via GreetingLib.Options.Log
  interface Log {
    verbose?: boolean;
  }
  interface Alert {
    modal: boolean;
    title?: string;
    color?: string;
  }
}

类

¥Classes

文档

¥Documentation

你可以通过实例化 Greeter 对象来创建欢迎程序，或者通过从它扩展来创建自定义的欢迎程序。

¥You can create a greeter by instantiating the Greeter object, or create a customized greeter by extending from it.

代码

¥Code

ts
const myGreeter = new Greeter("hello, world");
myGreeter.greeting = "howdy";
myGreeter.showGreeting();
class SpecialGreeter extends Greeter {
  constructor() {
    super("Very special greetings");
  }
}

声明

¥Declaration

使用 declare class 描述类或类类对象。类可以具有属性和方法以及构造函数。

¥Use declare class to describe a class or class-like object. Classes can have properties and methods as well as a constructor.

ts
declare class Greeter {
  constructor(greeting: string);
  greeting: string;
  showGreeting(): void;
}

全局变量

¥Global Variables

文档

¥Documentation

全局变量 foo 包含存在的小部件数量。

¥The global variable foo contains the number of widgets present.

代码

¥Code

ts
console.log("Half the number of widgets is " + foo / 2);

声明

¥Declaration

使用 declare var 声明变量。如果变量是只读的，则可以使用 declare const。如果变量是块作用域的，你也可以使用 declare let。

¥Use declare var to declare variables. If the variable is read-only, you can use declare const. You can also use declare let if the variable is block-scoped.

ts
/** The number of widgets present */
declare var foo: number;

全局函数

¥Global Functions

文档

¥Documentation

你可以使用字符串调用函数 greet 以向用户显示问候语。

¥You can call the function greet with a string to show a greeting to the user.

代码

¥Code

ts
greet("hello, world");

声明

¥Declaration

使用 declare function 声明函数。

¥Use declare function to declare functions.

ts
declare function greet(greeting: string): void;