宣告檔案的定義

通俗地來講，在 TypeScript 中以.d.ts為字尾的檔案，我們稱之為 TypeScript 宣告檔案。它的主要作用是描述JavaScript模組內所有匯出介面的型別資訊。

什麼時候需要寫 TS 宣告檔案

在日常的開發中，絕大多數時候是不需要我們單獨去編寫一個 TS 宣告檔案的。如果我們的檔案本身是用 TS 編寫的，在編譯的時候讓 TS 自動生成宣告檔案，並在釋出的時候將.d.ts檔案一起釋出即可。

總結了以下三種情況，需要我們手動定義宣告檔案：

通過 script 標籤引入的第三方庫

一些通過 CDN 的當時映入的小的工具包，掛載了一些全域性的方法，如果在TS中直接使用的話，會報 TS語法錯誤，這時候就需要我們對這些全域性的方法進行 TS 宣告。

使用的第三方npm包，但是沒有提供宣告檔案

第三方 npm 包如果有提供宣告檔案的話，一般會以兩種形式存在：一是@types/xxx，另外是在原始碼中提供.d.ts宣告檔案。第一種的話一般是一些使用量比較高的庫會提供，可以通過npm i @type/xxx嘗試安裝。如果這兩種都不存在的話，那就需要我們自己來定義了。

自身團隊內比較優秀的js庫或外掛，為了提升開發體驗

https://www.98891.com/article-60-1.html

如何編寫 TS 宣告檔案

對於不同形式的宣告檔案，寫法上會有一定的差異。這裡需要特別注意一點的是：宣告檔案中只是對型別的定義，不能進行賦值。

:pushpin: 全域性變數

全域性變數的宣告檔案主要有以下幾種語法：

declare let/const  // 宣告全域性變數
declare function   // 宣告全域性方法
declare class      // 宣告全域性類
declare enum       // 宣告全域性列舉型別 
declare namespace  // 宣告（含有子屬性的）全域性物件
interface/type     // 宣告全域性型別

這裡需要注意的是隻是定義型別，不能進行賦值。

// 變數
declare let userName: string;

declare const wx: any;

// 函式、函式過載
declare function getName(uid: number): string;
declare function getName(): string;
declare function getName(cb: () => any): any;

// 類
declare class Course {
  cid: number;
  constructor(cid){};
  getCoursePrice(): number;
}

// 列舉
declare enum Status {
  Loading,
  Success,
  Failed,
}

// 介面 interface declare 可以不需要
interface CourseInfo {
  cid: number;
  name: string;
}

interface CGIData<T> {
  data: T;
  retcode: 0;
}

// 名稱空間
declare namespace User {
  // 區域性 Test.User
  interface User {
    name: string;
    age: number;
  }

  function getUserInfo(name: string): User {
    return "";
  }
  namespace fn {
    function extend(obj: any): any;
  }
}


// 宣告合併
declare function User(id: number): string;
 

:pushpin: npm 包

對於沒有提供宣告檔案的 npm 包，我們可以建立一個 types 目錄，來管理自己寫的宣告檔案，同時需要在配置檔案tsconfig.json中的 paths 和 basrUrl 中配置：

{
  "compilerOptions": {
    "module": "commonjs",
    "baseUrl": "./", // types資料夾的相對路徑
    "paths": { "*": ["types/*"]}
  }
}

npm 包的宣告檔案主要有以下幾種語法：

export const/let  // 匯出變數
export namespace  // 匯出（含有自屬性的）物件
export default    // ES6 預設匯出
export =          // commonjs 匯出模組

:pushpin: 拓展原有模組/全域性變數

對於已經有宣告定義的模組或者全域性變數，可以利用 TS 中的宣告合併對其進行拓展。

比如在 window 下掛載的一些全域性變數:

interface Window {
  readonly request?: any;
  readonly devToolsExtension?: any;
  readonly wx?: any;
}

對已有模組進行拓展：

declare module "querystring" {
  function escape(str: string): string;
  function unescape(str: string): string;
}

還可以使用三斜線的方式對宣告檔案進行引用：

/// <reference path=”custom.d.ts" />

最後

如何讓 TS 在編譯時自動生成.d.ts檔案呢？只需要在tsconfig.json配置檔案中開啟即可，TS編譯時就會自動生成.d.ts宣告檔案：

{
  "compilerOptions": {
    "declaration": true
  }
}