宣告參考

本指南的目的是教導您如何撰寫高品質的定義檔案。本指南的結構是透過展示一些 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 物件可以記錄到檔案或顯示警示。你可以提供 LogOptions 給 .log(...) 和警示選項給 .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;
  }
}

類別

文件

你可以透過實例化 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 包含目前小工具的數量。

程式碼

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;