TypeScript声明文件 #

一、声明文件基础 #

1.1 什么是声明文件 #

声明文件（.d.ts）用于描述JavaScript代码的类型信息，不包含实现代码。

typescript

declare function greet(name: string): string;

declare const version: string;

declare class User {
    constructor(name: string);
    name: string;
    greet(): string;
}

1.2 声明文件的作用 #

为JavaScript库提供类型信息
描述模块的类型结构
扩展全局类型

二、基本声明 #

2.1 变量声明 #

typescript

declare const name: string;
declare let age: number;
declare var isDone: boolean;

declare const config: {
    apiUrl: string;
    timeout: number;
};

2.2 函数声明 #

typescript

declare function greet(name: string): string;

declare function add(a: number, b: number): number;

declare function fetch(url: string, options?: {
    method?: string;
    headers?: Record<string, string>;
}): Promise<Response>;

2.3 类声明 #

typescript

declare class User {
    constructor(name: string, age: number);
    name: string;
    age: number;
    greet(): string;
    static create(name: string): User;
}

2.4 枚举声明 #

typescript

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

declare const enum Status {
    Pending = 'PENDING',
    Approved = 'APPROVED'
}

2.5 接口声明 #

typescript

declare interface User {
    id: number;
    name: string;
    email: string;
}

declare interface Config {
    apiUrl: string;
    timeout?: number;
}

三、模块声明 #

3.1 模块声明 #

typescript

declare module 'my-library' {
    export function greet(name: string): string;
    export function add(a: number, b: number): number;
    export const version: string;
    export default class User {
        constructor(name: string);
    }
}

3.2 模块扩展 #

typescript

declare module 'express' {
    interface Request {
        user?: {
            id: string;
            name: string;
        };
    }
}

3.3 声明文件结构 #

text

node_modules/
├── my-library/
│   ├── index.js
│   └── index.d.ts

types/
├── my-library/
│   └── index.d.ts

四、全局声明 #

4.1 全局变量 #

typescript

declare const myApp: {
    version: string;
    init(): void;
};

myApp.init();

4.2 全局函数 #

typescript

declare function $(selector: string): HTMLElement;

$('#app');

4.3 全局接口扩展 #

typescript

declare global {
    interface Window {
        myApp: {
            version: string;
        };
    }
    
    namespace NodeJS {
        interface ProcessEnv {
            API_URL: string;
        }
    }
}

window.myApp = { version: '1.0.0' };

五、命名空间声明 #

5.1 命名空间声明 #

typescript

declare namespace MyLibrary {
    interface Options {
        debug: boolean;
    }
    
    function init(options: Options): void;
    
    class User {
        constructor(name: string);
        name: string;
    }
}

5.2 嵌套命名空间 #

typescript

declare namespace App {
    namespace Models {
        interface User {
            name: string;
        }
    }
    
    namespace Services {
        class UserService {
            create(user: Models.User): void;
        }
    }
}

六、类型声明 #

6.1 type声明 #

typescript

declare type ID = string | number;

declare type User = {
    id: ID;
    name: string;
};

declare type EventHandler = (event: Event) => void;

6.2 泛型声明 #

typescript

declare type Box<T> = {
    value: T;
};

declare function identity<T>(arg: T): T;

declare class Container<T> {
    value: T;
    get(): T;
    set(value: T): void;
}

七、第三方库声明 #

7.1 @types包 #

bash

npm install --save-dev @types/node
npm install --save-dev @types/react
npm install --save-dev @types/lodash

7.2 创建声明文件 #

typescript

declare module 'untyped-library' {
    export function doSomething(value: string): number;
    export const version: string;
}

7.3 any类型模块 #

typescript

declare module 'untyped-library';

八、实用示例 #

8.1 jQuery声明 #

typescript

declare const $: {
    (selector: string): JQuery;
    ajax(options: {
        url: string;
        method?: string;
        data?: any;
        success?(data: any): void;
        error?(error: any): void;
    }): void;
};

interface JQuery {
    html(): string;
    html(value: string): JQuery;
    on(event: string, handler: (e: Event) => void): JQuery;
    click(handler: (e: Event) => void): JQuery;
}

8.2 Express扩展 #

typescript

import 'express';

declare module 'express' {
    interface Request {
        user?: {
            id: string;
            name: string;
            role: string;
        };
    }
    
    interface Response {
        success(data: any): void;
        error(message: string): void;
    }
}

8.3 环境变量 #

typescript

declare namespace NodeJS {
    interface ProcessEnv {
        NODE_ENV: 'development' | 'production' | 'test';
        API_URL: string;
        DATABASE_URL: string;
        JWT_SECRET: string;
    }
}

九、最佳实践 #

9.1 使用@types #

bash

npm install --save-dev @types/node

9.2 项目内声明文件 #

text

src/
├── types/
│   ├── global.d.ts
│   ├── express.d.ts
│   └── window.d.ts

9.3 tsconfig配置 #

json

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"]
  }
}

十、总结 #

本章介绍了TypeScript声明文件：

声明类型 #

变量声明
函数声明
类声明
模块声明
命名空间声明

最佳实践 #

使用@types包
项目内组织声明文件
合理配置typeRoots