TypeScript 聲明文件舉例

簡(jiǎn)介

這篇指南的目的是教你如何書(shū)寫(xiě)高質(zhì)量的TypeScript聲明文件。 我們?cè)谶@里會(huì)展示一些API的文檔，還有它們的使用示例， 并且闡述了如何為它們書(shū)寫(xiě)聲明文件。

這些例子是按復(fù)雜度遞增的順序組織的。

• 全局變量
• 全局函數(shù)
• 帶屬性的對(duì)象
• 函數(shù)重載
• 可重用類(lèi)型（接口）
• 可重用類(lèi)型（類(lèi)型別名）
• 組織類(lèi)型
• 類(lèi)

例子

全局變量

文檔

全局變量foo包含了存在組件總數(shù)。

代碼

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

聲明

使用declare var聲明變量。 如果變量是只讀的，那么可以使用 declare const。 你還可以使用 declare let如果變量擁有塊級(jí)作用域。

/** 組件總數(shù) */
declare var foo: number;

全局函數(shù)

文檔

用一個(gè)字符串參數(shù)調(diào)用greet函數(shù)向用戶顯示一條歡迎信息。

代碼

greet("hello, world");

聲明

使用declare function聲明函數(shù)。

declare function greet(greeting: string): void;

帶屬性的對(duì)象

文檔

全局變量myLib包含一個(gè)makeGreeting函數(shù)， 還有一個(gè)屬性 numberOfGreetings指示目前為止歡迎數(shù)量。

代碼

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

let count = myLib.numberOfGreetings;

聲明

使用declare namespace描述用點(diǎn)表示法訪問(wèn)的類(lèi)型或值。

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

函數(shù)重載

文檔

getWidget函數(shù)接收一個(gè)數(shù)字，返回一個(gè)組件，或接收一個(gè)字符串并返回一個(gè)組件數(shù)組。

代碼

let x: Widget = getWidget(43);

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

聲明

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

可重用類(lèi)型（接口）

文檔

當(dāng)指定一個(gè)歡迎詞時(shí)，你必須傳入一個(gè)GreetingSettings對(duì)象。 這個(gè)對(duì)象具有以下幾個(gè)屬性：

• greeting：必需的字符串
• duration: 可靠的時(shí)長(zhǎng)（毫秒表示）
• color: 可選字符串，比如‘#ff00ff’

代碼

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

聲明

使用interface定義一個(gè)帶有屬性的類(lèi)型。

interface GreetingSettings {
  greeting: string;
  duration?: number;
  color?: string;
}

declare function greet(setting: GreetingSettings): void;

可重用類(lèi)型（類(lèi)型別名）

文檔

在任何需要?dú)g迎詞的地方，你可以提供一個(gè)string，一個(gè)返回string的函數(shù)或一個(gè)Greeter實(shí)例。

代碼

function getGreeting() {
    return "howdy";
}
class MyGreeter extends Greeter { }

greet("hello");
greet(getGreeting);
greet(new MyGreeter());

聲明

你可以使用類(lèi)型別名來(lái)定義類(lèi)型的短名：

type GreetingLike = string | (() => string) | Greeting;

declare function greet(g: GreetingLike): void;

組織類(lèi)型

文檔

greeter對(duì)象能夠記錄到文件或顯示一個(gè)警告。 你可以為 .log(...)提供LogOptions和為.alert(...)提供選項(xiàng)。

代碼

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

聲明

使用命名空間組織類(lèi)型。

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

你也可以在一個(gè)聲明中創(chuàng)建嵌套的命名空間：

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

類(lèi)

文檔

你可以通過(guò)實(shí)例化Greeter對(duì)象來(lái)創(chuàng)建歡迎詞，或者繼承Greeter對(duì)象來(lái)自定義歡迎詞。

代碼

const myGreeter = new Greeter("hello, world");
myGreeter.greeting = "howdy";
myGreeter.showGreeting();

class SpecialGreeter extends Greeter {
    constructor() {
        super("Very special greetings");
    }
}

聲明

使用declare class描述一個(gè)類(lèi)或像類(lèi)一樣的對(duì)象。 類(lèi)可以有屬性和方法，就和構(gòu)造函數(shù)一樣。

declare class Greeter {
    constructor(greeting: string);

    greeting: string;
    showGreeting(): void;
}