TypeScript 聲明文件舉例

簡介

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

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

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

例子

全局變量

文檔

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

代碼

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

聲明

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

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

全局函數(shù)

文檔

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

代碼

greet("hello, world");

聲明

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

declare function greet(greeting: string): void;

帶屬性的對象

文檔

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

代碼

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

let count = myLib.numberOfGreetings;

聲明

使用declare namespace描述用點表示法訪問的類型或值。

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

函數(shù)重載

文檔

getWidget函數(shù)接收一個數(shù)字，返回一個組件，或接收一個字符串并返回一個組件數(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[];

可重用類型（接口）

文檔

當指定一個歡迎詞時，你必須傳入一個GreetingSettings對象。 這個對象具有以下幾個屬性：

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

代碼

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

聲明

使用interface定義一個帶有屬性的類型。

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

declare function greet(setting: GreetingSettings): void;

可重用類型（類型別名）

文檔

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

代碼

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

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

聲明

你可以使用類型別名來定義類型的短名：

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

declare function greet(g: GreetingLike): void;

組織類型

文檔

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

代碼

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

聲明

使用命名空間組織類型。

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

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

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

類

文檔

你可以通過實例化Greeter對象來創(chuàng)建歡迎詞，或者繼承Greeter對象來自定義歡迎詞。

代碼

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

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

聲明

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

declare class Greeter {
    constructor(greeting: string);

    greeting: string;
    showGreeting(): void;
}