宣告參考

本指南旨在教您如何編寫高質量的宣告檔案。指南的結構是展示某些 API 的文件，並附帶該 API 的示例用法，同時解釋如何編寫相應的宣告。

這些示例大致按複雜程度遞增的順序排列。

具有屬性的物件

文件

全域性變數 myLib 擁有一個用於建立問候語的函式 makeGreeting，以及一個表示迄今為止已建立問候語數量的屬性 numberOfGreetings。

程式碼

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

宣告

使用 declare namespace 來描述透過點標記法訪問的型別或值。

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

函式過載

文件

getWidget 函式接受一個數字並返回一個 Widget，或者接受一個字串並返回一個 Widget 陣列。

程式碼

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

宣告

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

可重用型別（介面）

文件

指定問候語時，必須傳遞一個 GreetingSettings 物件。該物件具有以下屬性：

1 - greeting: 必選字串

2 - duration: 可選的時間長度（以毫秒為單位）

3 - color: 可選字串，例如 ‘#ff00ff’

程式碼

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

宣告

使用 interface 定義具有屬性的型別。

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

可重用型別（類型別名）

文件

在任何期望得到問候語的地方，您都可以提供一個 string、一個返回 string 的函式或一個 Greeter 例項。

程式碼

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

宣告

您可以使用類型別名為型別建立簡寫形式。

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

組織型別

文件

greeter 物件可以記錄到檔案或顯示警告。您可以向 .log(...) 提供 LogOptions，向 .alert(...) 提供警告選項。

程式碼

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

宣告

使用名稱空間來組織型別。

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

您也可以在一個宣告中建立巢狀的名稱空間。

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

類 (Classes)

文件

您可以透過例項化 Greeter 物件來建立一個 greeter，或者透過繼承它來建立一個自定義的 greeter。

程式碼

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

宣告

使用 declare class 來描述類或類物件。類可以擁有屬性和方法，也可以擁有建構函式。

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

全域性變數

文件

全域性變數 foo 包含了當前存在的視窗小部件（widgets）數量。

程式碼

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

宣告

使用 declare var 來宣告變數。如果變數是隻讀的，可以使用 declare const。如果變數是塊級作用域的，也可以使用 declare let。

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

全域性函式

文件

您可以使用字串呼叫 greet 函式，向用戶顯示問候語。

程式碼

ts
greet("hello, world");

宣告

使用 declare function 來宣告函式。

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