声明参考手册

本指南的目的是教你如何编写高质量的定义文件。 本指南的结构是通过展示某些 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，表示到目前为止已经创建的问候次数。

代码

🌐 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 函数接受一个数字并返回一个 Widget，或者接受一个字符串并返回一个 Widget 数组。

🌐 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 对象。 该对象具有以下属性：

1 - greeting：必填字符串

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

3 - color：可选字符串，例如 ‘#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 实例。

代码

🌐 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(...) 提供日志选项，向 .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 对象来创建一个问候器，或者通过继承它来创建一个自定义的问候器。

代码

🌐 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 包含当前存在的小部件数量。

代码

🌐 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 并传入一个字符串来向用户显示问候。

代码

🌐 Code

ts
greet("hello, world");

声明

🌐 Declaration

使用 declare function 来声明函数。

🌐 Use declare function to declare functions.

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