如何编写一个d.ts文件

如何编写一个d.ts文件

.d.ts文件是ts模块，变量一系列的申明文件。比如要使用react，就需要安装"@types/react"，之后还会有提示。自定义全局声明文件，往往在根目录新建一个typings.d.ts文件

全局类型

• 变量

有一个全局变量，那对应的d.ts文件里面这样写。如果一个.ts、.d.ts文件如果没有用到import或者export语法的话，那么最顶层声明的变量就是全局变量。

declare var aaa:number
declare const pi:number = Math.PI

• 函数

由上面的全局变量的写法我们很自然的推断出一个全局函数的写法如下：

decalre function getName(id:number|string):string

• class

当然除了变量和函数外，我们还有类（class）。

declare class Person {

    static maxAge: number //静态变量
    static getMaxAge(): number //静态方法

    constructor(name: string, age: number)  //构造函数
    getName(id: number): string 
}

• 对象

对象的话，使用namespace命名空间来声明

declare namespace common{
    
}
// 还可以嵌套
declare namespace OOO{
    var aaa: number | string
    // ...
    namespace O2{
        let b:number
    }
}

• menu

使用 declare enum 定义的枚举类型也称作外部枚举

declare enum Directions {
    Up,
    Down,
    Left,
    Right
}

• interface 和 type

除了全局变量之外，可能有一些类型我们也希望能暴露出来。在类型声明文件中，我们可以直接使用 interface 或 type 来声明一个全局的接口或类型

interface AjaxSettings {
    method?: 'GET' | 'POST'
    data?: any;
}

暴露在最外层的 interface 或 type 会作为全局类型作用于整个项目中，我们应该尽可能的减少全局变量或全局类型的数量。故最好将他们放到 namespace

declare namespace jQuery {
    interface AjaxSettings {
        method?: 'GET' | 'POST'
        data?: any;
    }
    function ajax(url: string, settings?: AjaxSettings): void;
}

• 混合类型

有时候有些值既是函数又是class又是对象的复杂对象。比如我们常用的jquery有各种用法：

new $()
$.ajax()
$()

那么如下声明：

declare function $2(s:string): void

declare namespace $2{
    let aaa:number
}

• 模块化（CommonJS）

除了上面的全局的方式，我们有时候还是通过require的方式引入模块化的代码。如果要像如下引入代码：

let util = require('util')
util.setTitle("hello")

对应写法如下：

declare module "util" {
  export let a: number
  export function setTitle(title: string): void;
  export namespace c{
    let cd: string
  }
}

• export

npm 包的声明文件与全局变量的声明文件有很大区别。在 npm 包的声明文件中，使用 declare 不再会声明一个全局变量，而只会在当前文件中声明一个局部变量。只有在声明文件中使用 export 导出，然后在使用方 import 导入后，才会应用到这些类型声明

export 的语法与普通的 ts 中的语法类似，区别仅在于声明文件中禁止定义具体的实现

declare const name: string;
declare function getName(): string;
declare class Animal {
    constructor(name: string);
    sayHi(): string;
}
declare enum Directions {
    Up,
    Down,
    Left,
    Right
}
interface Options {
    data: any;
}

export { name, getName, Animal, Directions, Options };

• UMD

有一种代码，既可以通过全局变量访问到，也可以通过require的方式访问到。比如我们最常见的jquery：

declare namespace UUU{
    let a:number
}
 
declare module "UUU" {
    export =UUU
}

• 定义全局的

使用 declare global 可以在 npm 包或者 UMD 库的声明文件中扩展全局变量的类型

declare global {
    interface String {
        prependHello(): string;
    }
}

• 其他

有时候我们扩展了一些内置对象。比如我们给Date增加了一个format的实例方法：

let d = new Date()
d.format = function (f: string): string {
  return this.getFullYear().toString()
}

那么声明文件应该这么写：

interface Date {
    format(f: string): string
}

参考文献

• TypeScript入门教程