在 TypeScript 开发中，我们经常需要为 JavaScript 库或全局变量添加类型支持。这时就需要用到类型声明（Declaration）。类型声明文件以 .d.ts 为扩展名（d 是 declare 的缩写），用于声明变量、函数、类、模块等的类型信息。它只包含类型声明，不包含具体实现，编译后也不会生成 JavaScript 代码。本文将详细介绍如何编写和使用类型声明文件。

一、基本介绍

1，什么是声明文件

// 示例：一个简单的声明文件
// hello.d.ts
declare function sayHello(name: string): void;

// 声明文件只描述类型，不包含实现
// 编译后不会生成任何 JavaScript 代码

2，三种类型声明位置

3，内置类型声明

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es5", "dom"]  // 手动指定需要的标准库
  }
}

4，外部类型声明

// 安装 React 的类型声明
npm install @types/react --save-dev

// 安装 lodash 的类型声明
npm install @types/lodash --save-dev

二、declare 声明全局变量、全局函数、全局类

1，什么是 declare

2，声明全局变量

<!-- public/index.html -->
<script>
  // 定义全局变量
  const appName = 'Vue.js 3 + TypeScript'
  const appVersion = '1.0.0'
</script>

// main.ts
console.log(appName)     // 报错：Cannot find name 'appName'
console.log(appVersion)  // 报错：Cannot find name 'appVersion'

// src/types/global.d.ts

// 声明全局变量，告诉编译器该变量已声明
declare const appName: string
declare const appVersion: string

3，声明全局函数

<!-- public/index.html -->
<script>
  // 定义全局函数
  function getAppName() {
    return appName
  }
</script>

// src/types/global.d.ts

// 声明全局函数
declare function getAppName(): string

// 或者使用函数类型声明
declare const getAppName: () => string

// main.ts
console.log(getAppName())  // ok

4，声明全局类

<!-- public/index.html -->
<script>
  // 定义全局类
  function Person(name, age) {
    this.name = name
    this.age = age
  }
</script>

// src/types/global.d.ts

// 声明全局类
declare class Person {
  name: string
  age: number
  constructor(name: string, age: number)
}

// main.ts
const p = new Person("hangge", 18)
console.log(p)

三、declare 声明文件与模块

1，声明导入的文件

// src/types/global.d.ts

// 声明导入图片文件
declare module '*.jpg'
declare module '*.jpeg'
declare module '*.png'
declare module '*.svg'
declare module '*.gif'

// 声明导入样式文件
declare module '*.css'
declare module '*.scss'
declare module '*.less'

// main.ts
import logoImg from './img/logo.png'  // ok
import './styles/main.css'              // ok

2，声明第三方模块

// 安装 lodash
npm install lodash --save

// 导入使用
import lodash from 'lodash'  // 报错：Could not find a declaration file for module 'lodash'

npm install @types/lodash --save-dev

// src/types/global.d.ts

// 声明 lodash 模块
declare module 'lodash' {
  // 导出模块中的函数
  export function join(args: any[]): any
  export function isEmpty(value: any): boolean
  // 可以继续导出 lodash 的其他方法
}

3，扩展模块类型

// src/types/axios.d.ts

import 'axios'

declare module 'axios' {
  interface AxiosInstance {
    // 添加自定义方法
    customGet(url: string): Promise<any>
  }
}

四、声明命名空间

1，declare namespace 语法

<!-- public/index.html -->
<!-- 引入 jQuery -->
<script src="https://cdn.bootcdn.net/ajax/libs/jquery/3.6.0/jquery.js"></script>

// src/types/global.d.ts

// 声明 $ 命名空间
declare namespace $ {
  function ajax(settings: any): void
  function get(url: string, callback: (res: any) => void): void
  function post(url: string, data: any, callback: (res: any) => void): void
}

// main.ts

// 全局使用 $ 函数不会提示报错
$.ajax({
  url: "https://api.example.com/get",
  success: (res: any) => {
    console.log(res)
  }
})

2，嵌套命名空间

// src/types/global.d.ts

declare namespace MyApp {
  // 嵌套命名空间
  namespace Utils {
    function formatDate(date: Date): string
    function parseJSON(str: string): any
  }
  
  namespace Config {
    const apiUrl: string
    const version: string
  }
}

// 使用
// MyApp.Utils.formatDate(new Date())
// console.log(MyApp.Config.apiUrl)

附：声明文件最佳实践

1，文件组织结构

my-project/
├── src/
│   ├── index.ts
│   └── types/
│       ├── global.d.ts      // 全局类型声明
│       ├── vue.d.ts          // Vue 相关声明
│       └── modules.d.ts      // 模块声明

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

2，发布 npm 包时的配置

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,   // 自动生成 .d.ts 文件
    "outDir": "dist"
  }
}

// package.json
{
  "name": "my-library",
  "main": "dist/index.js",
  "types": "dist/index.d.ts"  // 指定类型声明文件
}