簡(jiǎn)介

聲明文件是以.d.ts為后綴的文件，開發(fā)者在聲明文件中編寫類型聲明，TypeScript根據(jù)聲明文件的內(nèi)容進(jìn)行類型檢查。（注意同目錄下最好不要有同名的.ts文件和.d.ts，例如lib.ts和lib.d.ts，否則模塊系統(tǒng)無法只根據(jù)文件名加載模塊）

為什么需要聲明文件呢？我們知道TypeScript根據(jù)類型聲明進(jìn)行類型檢查，但有些情況可能沒有類型聲明：

• 第三方包，因?yàn)榈谌桨虬蠖际荍avaScript語(yǔ)法，而非TypeScript，沒有類型。
• 宿主環(huán)境擴(kuò)展，如一些hybrid環(huán)境，在window變量下有一些bridge接口，這些接口沒有類型聲明。

如果沒有類型聲明，在使用變量、調(diào)用函數(shù)、實(shí)例化類的時(shí)候就沒法通過TypeScript的類型檢查。

聲明文件就是針對(duì)這些情況，開發(fā)者在聲明文件中編寫第三方模塊的類型聲明/宿主環(huán)境的類型聲明。讓TypeScript可以正常地進(jìn)行類型檢查。

除此之外，聲明文件也可以被導(dǎo)入，使用其中暴露的類型定義。

總之，聲明文件有兩種用法：

• 被通過import導(dǎo)入，使用其中暴露的類型定義和變量聲明。
• 和相關(guān)模塊關(guān)聯(lián)，為模塊進(jìn)行類型聲明。

對(duì)于第二種用法，聲明文件如何同相關(guān)模塊關(guān)聯(lián)呢？

比如有個(gè)第三方包名字叫"foo"，那么TypeScript會(huì)在node_modules/foo中根據(jù)其package.json的types和typing字段查找聲明文件查找到的聲明文件被作為該模塊的聲明文件；TypeScript也會(huì)在node_modules/@types/foo/目錄中查找聲明文件，如果能找到就被作為foo模塊的聲明文件；TypeScript還會(huì)在我們的項(xiàng)目中查找.d.ts文件，如果遇到declare module 'foo'語(yǔ)句，則該聲明被用作foo模塊的聲明。

總結(jié)一下，TypeScript會(huì)在特定的目錄讀取指定的聲明文件。

• 在內(nèi)部項(xiàng)目中，TypeScript會(huì)讀取tsconfig.json中的文件集合，在其中的聲明文件才會(huì)被處理。
• 讀取node_modules中各第三方包的package.json的types或者typing指定的文件。
• 讀取@types目錄下同名包的聲明文件。

聲明文件中的代碼不會(huì)出現(xiàn)在最終的編譯結(jié)果中，編譯后會(huì)把轉(zhuǎn)換后的JavaScript代碼輸出到"outDir"選項(xiàng)指定的目錄中，并且把 .ts模塊中使用到的值的聲明都輸出到"declarationDir"指定的目錄中。

而在.ts文件中的聲明語(yǔ)句，編譯后會(huì)被去掉，如

declare let a: number;

export default a;

會(huì)被編譯為

"use strict";
exports.__esModule = true;
exports["default"] = a;

TypeScript編譯過程不僅將TypeScript語(yǔ)法轉(zhuǎn)譯為ES6/ES5，還會(huì)將代碼中.ts文件中用到的值的類型輸出到指定的聲明文件中。如果你需要實(shí)現(xiàn)一個(gè)庫(kù)項(xiàng)目，這個(gè)功能很有用，因?yàn)橛玫侥愕膸?kù)的項(xiàng)目可以直接使用這些聲明文件，而不需要你再為你的庫(kù)寫聲明文件。

語(yǔ)法

內(nèi)容

TypeScript中的聲明會(huì)創(chuàng)建以下三種實(shí)體之一：命名空間，類型或值。

命名空間最終被編譯為全局變量，因此我們也可以認(rèn)為聲明文件中其實(shí)創(chuàng)建了類型和值兩種實(shí)體。即定義類型或者聲明值。

// 類型 接口
interface Person {name: string;}

// 類型 類型別名
type Fruit = {size: number};

// 值 變量
declare let a: number;

// 值 函數(shù)
declare function log(message: string): void;

// 值 類
declare class Person {name: string;}

// 值 枚舉
declare enum Color {Red, Green}

// 值 命名空間
declare namespace person {let name: string;}

我們注意到類型可以直接定義，但是值的聲明需要借助declare關(guān)鍵字，這是因?yàn)槿绻挥胐eclare關(guān)鍵字，值的聲明和初始化是一起的，如

let a: number;

// 編譯為
var a;

但是編譯結(jié)果是會(huì)去掉所有的聲明語(yǔ)句，保留初始化的部分，而聲明文件中的內(nèi)容只是起聲明作用，因此需要通過declare來標(biāo)識(shí)，這只是聲明語(yǔ)句，編譯時(shí)候直接去掉即可。

TypeScript也約束聲明文件中聲明一個(gè)值必須要用declare，否則會(huì)被認(rèn)為存在初始化的內(nèi)容，從而報(bào)錯(cuò)。

// foo.d.ts
let a: number = 1; // error TS1039: Initializers are not allowed in ambient contexts.

declare也允許出現(xiàn)在.ts文件中，但一般不會(huì)這么做，.ts文件中直接用let/const/function/class就可以聲明并初始化一個(gè)變量。并且.ts文件編譯后也會(huì)去掉declare的語(yǔ)句，所以不需要declare語(yǔ)句。

注意，declare多個(gè)同名的變量是會(huì)沖突的

declare let foo: number; // error TS2451: Cannot redeclare block-scoped variable 'a'.

declare let foo: number; // error TS2451: Cannot redeclare block-scoped variable 'a'.

除了使用declare聲明一個(gè)值，declare還可以用來聲明一個(gè)模塊和全局的插件，這兩種用法都是在特定場(chǎng)景用來給第三方包做聲明。

declare module用來給一個(gè)第三方模進(jìn)行類型聲明，比如有一個(gè)第三方包foo，沒有類型聲明。我們可以在我們項(xiàng)目中實(shí)現(xiàn)一個(gè)聲明文件來讓TypeScript可以識(shí)別模塊類型：foo.d.ts

// foo.d.ts
declare module 'foo' {
    export let size: number;
}

然后我們就可以使用了：

import foo from 'foo';

console.log(foo.size);

declare module除了可以用來給一個(gè)模塊聲明類型，還可以用來實(shí)現(xiàn)模塊插件的聲明。后面小節(jié)中會(huì)做介紹。

declare global用來給擴(kuò)展全局的第三方包進(jìn)行聲明，后面小節(jié)介紹。

模塊化

模塊語(yǔ)法

聲明文件的模塊化語(yǔ)法和.ts模塊的類似，在一些細(xì)節(jié)上稍有不同。.ts導(dǎo)出的是模塊（typescript會(huì)根據(jù)導(dǎo)出的模塊判斷類型），.d.ts導(dǎo)出的是類型的定義和聲明的值。

聲明文件可以導(dǎo)出類型，也可以導(dǎo)出值的聲明

// index.d.ts

// 導(dǎo)出值聲明
export let a: number;

// 導(dǎo)出類型
export interface Person {
    name: string;
};

聲明文件可以引入其他的聲明文件，甚至可以引入其他的.ts文件（因?yàn)?ts文件也可能導(dǎo)出類型）

// Person.d.ts
export default interface Person {name: string}

// index.d.ts
import Person from './person';

export let p: Person;

如果聲明文件不導(dǎo)出，默認(rèn)是全局可以訪問的

// person.d.ts
interface Person {name: string}
declare let p: Person;

// index.ts
let p1: Person = {name: 'Sam'};
console.log(p);

如果使用模塊導(dǎo)出語(yǔ)法（ESM/CommJS/UMD），則不解析為全局（當(dāng)然UMD還是可以全局訪問）。

// ESM

interface Person {name: string}

export let p: Person;

export default Person;

// CommonJS
interface Person {name: string}

declare let p: Person;

export = p;

// UMD
interface Person {name: string}

declare let p: Person;

export = p;
export as namespace p;

注意：UMD包export as namespace語(yǔ)法只能在聲明文件中出現(xiàn)。

三斜線指令

聲明文件中的三斜線指令，用于控制編譯過程。

三斜線指令僅可放在包含它的文件的最頂端。

如果指定--noResove編譯選項(xiàng)，預(yù)編譯過程會(huì)忽略三斜線指令。

reference

reference指令用來表明聲明文件的依賴情況。

/// <reference path="..." />用來告訴編譯器依賴的其他聲明文件。編譯器預(yù)處理時(shí)候會(huì)將path指定的聲明文件加入進(jìn)來。路徑是相對(duì)于文件自身的。引用不存在的文件或者引用自身，會(huì)報(bào)錯(cuò)。

/// <reference types="node" />用來告訴編譯器它依賴node_modules/@types/node/index.d.ts。如果你的項(xiàng)目里面依賴了@types中的某些聲明文件，那么編譯后輸出的聲明文件中會(huì)自動(dòng)加上這個(gè)指令，用以說明你的項(xiàng)目中的聲明文件依賴了@types中相關(guān)的聲明文件。

/// <reference no-default-lib="true"/>，

這涉及兩個(gè)編譯選項(xiàng)，--noLib，設(shè)置了這個(gè)編譯選項(xiàng)后，編譯器會(huì)忽略默認(rèn)庫(kù)，默認(rèn)庫(kù)是在安裝TypeScript時(shí)候自動(dòng)引入的，這個(gè)文件包含 JavaScript 運(yùn)行時(shí)（如window）以及 DOM 中存在各種常見的環(huán)境聲明。但是如果你的項(xiàng)目運(yùn)行環(huán)境和基于標(biāo)準(zhǔn)瀏覽器運(yùn)行時(shí)環(huán)境有很大不同，可能需要排除默認(rèn)庫(kù)，一旦你排除了默認(rèn)的 lib.d.ts 文件，你就可以在編譯上下文中包含一個(gè)命名相似的文件，TypeScript 將提取該文件進(jìn)行類型檢查。

另一個(gè)編譯選項(xiàng)是--skipDefaultLibCheck這個(gè)選項(xiàng)會(huì)讓編譯器忽略包含了/// <reference no-default-lib="true"/>指令的聲明文件。你會(huì)注意到在默認(rèn)庫(kù)的頂端都會(huì)有這個(gè)三斜線指令，因此如果采用了--skipDefaultLibCheck編譯選項(xiàng)，也同樣會(huì)忽略默認(rèn)庫(kù)。

amd-module

amd-module相關(guān)指令用于控制打包到amd模塊的編譯過程

///<amd-module name='NamedModule'/>這個(gè)指令用于告訴編譯器給打包為AMD的模塊傳入模塊名（默認(rèn)情況是匿名的）

///<amd-module name='NamedModule'/>
export class C {
}

編譯結(jié)果為

define("NamedModule", ["require", "exports"], function (require, exports) {
    var C = (function () {
        function C() {
        }
        return C;
    })();
    exports.C = C;
});

場(chǎng)景

這里我們將自己的項(xiàng)目代碼稱為“內(nèi)部項(xiàng)目”，引入的第三方模塊，包括npm引入的和script引入的，稱為“外部模塊”。

1. 在內(nèi)部項(xiàng)目中給內(nèi)部項(xiàng)目寫聲明文件

自己項(xiàng)目中，給自己的模塊寫聲明文件，例如多個(gè)模塊共享的類型，就可以寫一個(gè)聲明文件。這種場(chǎng)景通常不必要，一般是某個(gè).ts文件導(dǎo)出聲明，其他模塊引用聲明。

2. 給第三方包寫聲明文件

給第三方包寫聲明文件又分為在內(nèi)部項(xiàng)目中給第三方包寫聲明文件和在外部模塊中給外部模塊寫聲明文件。

在內(nèi)部項(xiàng)目中給第三方包寫聲明文件： 如果第三方包沒有TS聲明文件，則為了保證使用第三方包時(shí)候能夠通過類型檢查，也為了安全地使用第三方包，需要在內(nèi)部項(xiàng)目中寫第三方包的聲明文件。

在外部模塊中給外部模塊寫聲明文件： 如果你是第三方庫(kù)的作者，無論你是否使用TypeScript開發(fā)庫(kù)，都應(yīng)該提供聲明文件以便用TypeScript開發(fā)的項(xiàng)目能夠更好地使用你的庫(kù)，那么你就需要寫好你的聲明文件。

這兩種情況的聲明文件的語(yǔ)法類似，只在個(gè)別聲明語(yǔ)法和文件的處理上有區(qū)別：

• 內(nèi)部項(xiàng)目給第三方包寫聲明文件時(shí)候，以.d.ts命名即可，然后在tsconfig.json中的files和include中配置能夠包含到文件即可，外部模塊的聲明文件需要打包到輸出目錄，并且在package.json中的type字段指定聲明文件位置；或者上傳到@types/<moduleName>中，使用者通過npm install @types/<moduleName>安裝聲明文件。redux就在tsconfig.json中指定了declarationDir為./types，TypeScript會(huì)將項(xiàng)目的聲明都打包到這個(gè)目錄下，目錄結(jié)構(gòu)和源碼一樣，然后redux源碼入口處導(dǎo)出了所有的模塊，因此types目錄下也有一個(gè)入口的聲明文件index.d.ts，并且包含了所有的導(dǎo)出模塊聲明，redux在package.json中指定types字段（或者typings字段）為入口的聲明文件：./types/index.d.ts。這樣就實(shí)現(xiàn)了自動(dòng)生成接口的聲明文件。
• 內(nèi)部項(xiàng)目給第三方寫聲明文件時(shí)候，如果是通過npm模塊引入方式，如import moduleName from 'path';則需要通過declare module '<moduleName>'語(yǔ)法來聲明模塊。而外部模塊的聲明文件都是正常的類型導(dǎo)出語(yǔ)法（如export default export =等），如果聲明文件在@types中，會(huì)將與模塊同名的聲明文件作為模塊的類型聲明；如果聲明文件在第三方包中，那么就TypeScript模塊就將它作為這個(gè)第三方包模塊的模塊聲明，當(dāng)使用者導(dǎo)入并使用這個(gè)模塊時(shí)候，TypeScript就根據(jù)相應(yīng)地聲明文件進(jìn)行類型提示和類型檢查。

根據(jù)第三方包類型可以分成幾種

全局變量的第三方庫(kù)

我們知道如果不使用模塊導(dǎo)出語(yǔ)法，聲明文件默認(rèn)的聲明都是全局的。

declare namespace person {
    let name: string
}

或者

interface Person {
    name: string;
}

declare let person: Person;

使用：

console.log(person.name);

修改全局變量的模塊的第三方庫(kù)的聲明

如果有第三方包修改了一個(gè)全局模塊（這個(gè)第三方包是這個(gè)全局模塊的插件），這個(gè)第三方包的聲明文件根據(jù)全局模塊的聲明，有不同的聲明方式

如果全局模塊使用命名空間聲明

declare namespace person {
    let name: string
}

根據(jù)命名空間的聲明合并原理，插件模塊可以這樣聲明

declare namespace person {
  	// 擴(kuò)展了age屬性
    let age: number;
}

如果全局模塊使用全局變量聲明

interface Person {
    name: string;
}

declare let person: Person;

根據(jù)接口的聲明合并原理，插件模塊可以這樣聲明

interface Person {
  	// 擴(kuò)展了age屬性
    age: number;
}

上面的全局模塊的插件模塊的聲明方式可以應(yīng)用于下面的場(chǎng)景：

• 內(nèi)部項(xiàng)目使用了插件，但插件沒有聲明文件，我們可以在內(nèi)部項(xiàng)目中自己實(shí)現(xiàn)聲明文件。
• 給插件模塊寫聲明文件并發(fā)布到@types。

如果是插件模塊的作者，希望在項(xiàng)目中引用全局模塊并且將擴(kuò)展的類型輸出到聲明文件，以便其他項(xiàng)目使用?？梢赃@樣實(shí)現(xiàn)

// plugin/index.ts

// 注意這樣聲明才會(huì)讓TypeScript將類型輸出聲明文件
declare global {
  	// 假設(shè)全局模塊使用全局變量的方式聲明
    interface Person {
        age: number
    }
}

console.log(person.age);

export {};

注意，declare global寫在聲明文件中也可以，但是要在尾部加上export {}或者其他的模塊導(dǎo)出語(yǔ)句，否則會(huì)報(bào)錯(cuò)。另外declare global在聲明文件中寫的話，編譯后不會(huì)輸出到聲明文件中。

修改window

window的類型是interface Window {...}，在默認(rèn)庫(kù)中聲明，如果要擴(kuò)展window變量（如一些hybrid環(huán)境）可以這樣實(shí)現(xiàn)

// window.d.ts

// 聲明合并	
interface Window {
		bridge: {log(): void} 
}

// 或者
declare global {
    interface Window {
        bridge: {log(): void} 
    }
}

或者

// index.ts

declare global {
    interface Window {
        bridge: {log(): void} 
    }
}

window.bridge = {log() {}}

export {};

ESM和CommonJS

給第三方的ESM或者CommonJS模塊寫聲明文件，使用ESM導(dǎo)出或者CommonJS模塊語(yǔ)法導(dǎo)出都可以，不管第三方包是哪種模塊形式。

看下面示例

interface Person {
    name: string;
}

declare let person: Person;
 
export = person;
// 也可以使用export default person;

import person from 'person';

console.log(person.name);

上面的聲明文件是放在node_modules/@types/person/index.d.ts中，或者放在node_modules/person/package.json的types或者typings字段指定的位置。

如果在自己項(xiàng)目中聲明，應(yīng)該使用declare module實(shí)現(xiàn)

declare module 'person' {
    export let name: string;
}

UMD

UMD模塊，在CommonJS聲明的基礎(chǔ)上加上export as namespace ModuleName;語(yǔ)句即可。

看下面的ESM的例子

// node_modules/@types/person/index.d.ts
interface Person {
    name: string;
}

declare let person: Person;

export default person;

export as namespace person;

可以通過import導(dǎo)入來訪問

// src/index.ts
import person from 'person';

console.log(person.name);

也可以通過全局訪問

// src/index.ts

// 注意如果用ESM導(dǎo)出，全局使用時(shí)候先訪問defalut屬性。
console.log(person.default.name);

下面是CommonJS的例子

// node_modules/@types/person/index.d.ts

interface Person {
    name: string;
}

declare let person: Person;

export default person;

export as namespace person;

可以通過import引入訪問

// src/index.ts

import person from 'person';

console.log(person.name);

也可以全局訪問

// src/index.ts

console.log(person.name);

模塊插件

上面我們提到，declare module不僅可以用于給一個(gè)第三方模塊聲明類型，還可以用來給第三方模塊的插件模塊聲明類型。

// types/moment-plugin/index.d.ts

// 如果moment定義為UMD，就不需要引入，直接能夠使用
import * as moment from 'moment';

declare module 'moment' {
    export function foo(): moment.CalendarKey;
}

// src/index.ts

import * as moment from 'moment';
import 'moment-plugin';

moment.foo();

比如作為redux的插件的redux-thunk的聲明文件extend-redux.d.ts，就是這樣聲明的

// node_modules/redux-thunk/extend-redux.d.ts

declare module 'redux' {
		// declaration code......
}

總結(jié)

到此這篇關(guān)于TypeScript聲明文件的語(yǔ)法與場(chǎng)景詳解的文章就介紹到這了,更多相關(guān)TS聲明文件內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論