ts类型声明文件的正确使用姿势

ts声明文件类型

DefinitelyTyped社区已定义

npm install @types/jquery --save-dev

与npm一同发布

解释： package.json 中有 types 字段，或者有一个 index.d.ts 声明文件

自给自足型

创建一个 node_modules/@types/foo/index.d.ts 文件，存放 foo 模块的声明文件。不太建议用这种方案，一般只用作临时测试。
创建一个 types 目录，专门用来管理自己写的声明文件，将 foo 的声明文件放到 types/foo/index.d.ts 中。这种方式需要配置下 tsconfig.json 中的 paths 和 baseUrl 字段。

  /path/to/project
    ├── src
    |  └── index.ts
    ├── types
    |  └── foo
    |     └── index.d.ts
    └── tsconfig.json

  {
    "compilerOptions": {
        "module": "commonjs",
        "baseUrl": "./",
        "paths": {
            "*": ["types/*"]
        }
    }
}

ts声明文件书写姿势

全局型

# let 
declare let jQuery: (selector: string) => any;

# function 
declare function jQuery(selector: string): any;

#class 
declare class Animal {
    name: string;
    constructor(name: string);
    sayHi(): string;
}

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

#namespace 
declare namespace jQuery {
    function ajax(url: string, settings?: any): void;
    namespace fn {
        function extend(object: any): void;
    }
}

npm包型 - export

// types/foo/index.d.ts
export const name: string;
export function getName(): string;
export class Animal {
    constructor(name: string);
    sayHi(): string;
}
export enum Directions {
    Up,
    Down,
    Left,
    Right
}
export interface Options {
    data: any;
}
export namespace foo {
    const name: string;
    namespace bar {
        function baz(): string;
    }
}

npm包型 - export default

// types/foo/index.d.ts
# function、class 和 interface 可以直接默认导出，其他的变量需要先定义出来，再默认导出
export default function foo(): string;

export default Directions;
declare enum Directions {
    Up,
    Down,
    Left,
    Right
}

npm包型 - 先声明，在export

// types/foo/index.d.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 前是不需要 declare
interface Options {
    data: any;
}

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

module 拓展

// types/foo-bar.d.ts

declare module 'foo' {
    export interface Foo {
        foo: string;
    }
}

declare module 'bar' {
    export function bar(): string;
}

// src/index.ts

import { Foo } from 'foo';
import * as bar from 'bar';

let f: Foo;
bar.bar();

三斜线指令

书写一个全局变量的声明文件
依赖一个全局变量的声明文件

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

/// <reference types="jquery" />

declare function foo(options: JQuery.AjaxSettings): string;

ts文件tsc自动生成声明文件

命令行参数

--declaration（简写 -d）

tsconfig.json

{
    "compilerOptions": {
        "module": "commonjs",
        "outDir": "lib",
        "declaration": true,
    }
}

ts发布

发布到社区

@types 是统一由 DefinitelyTyped 管理的。要将声明文件发布到 @types 下，就需要给 DefinitelyTyped 创建一个 pull-request，其中包含了类型声明文件，测试代码，以及 tsconfig.json 等。

与源码一起（依次查找*.d.ts）
- 1. 给 package.json 中的 types 或 typings 字段指定一个类型声明文件地址
- 1. 在项目根目录下，编写一个 index.d.ts 文件
- 1. 针对入口文件（package.json 中的 main 字段指定的入口文件），编写一个同名不同后缀的 .d.ts 文件

参考

declaration-files

本文作者：前端漫谈

联系邮箱：simple2012hcz@126.com