外部声明（Ambient Declarations）是 TypeScript 中的一种机制，用于描述在 TypeScript 项目中使用的外部代码库的类型信息。通过外部声明，你可以为 JavaScript 库或其他外部资源定义类型，确保在使用它们时获得类型检查和自动补全的好处。本文将详细介绍 TypeScript 的外部声明，并通过示例代码说明每个概念的使用方法和应用场景。

什么是外部声明

外部声明使用 declare 关键字来描述外部代码库的类型信息。这些声明不会编译成 JavaScript 代码，它们仅存在于编译阶段，帮助 TypeScript 编译器进行类型检查。

示例

declare function fetch(url: string): Promise<Response>;

在上面的例子中，declare 关键字用于声明一个全局的 fetch 函数，其参数和返回值的类型被明确指出。

外部模块声明

对于外部模块，TypeScript 提供了模块声明的语法，可以为整个模块定义类型。

示例

// axios.d.ts
declare module 'axios' {
    export interface AxiosRequestConfig {
        url: string;
        method?: string;
    }
    export interface AxiosResponse {
        data: any;
    }
    export function get(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
}

在上面的例子中，我们为 axios 库定义了一个模块声明，描述了 AxiosRequestConfig 接口和 get 函数的类型。

使用外部声明

当你在 TypeScript 项目中使用未定义类型信息的外部库时，可以创建外部声明文件，通常以 .d.ts 为后缀。

示例

// math.d.ts
declare module 'math' {
    export function add(a: number, b: number): number;
    export function subtract(a: number, b: number): number;
}

// app.ts
import { add, subtract } from 'math';
console.log(add(2, 3)); // 5
console.log(subtract(5, 3)); // 2

全局外部声明

除了模块声明，还可以为全局变量、函数、对象等定义外部声明。

示例

// globals.d.ts
declare const API_URL: string;
declare function log(message: string): void;
declare class User {
    constructor(name: string);
    getName(): string;
}

// app.ts
console.log(API_URL); // 假设 API_URL 在外部脚本中定义
log('Hello, world!'); // 假设 log 在外部脚本中定义
const user = new User('Alice');
console.log(user.getName()); // Alice

使用 DefinitelyTyped

DefinitelyTyped 是一个社区维护的外部声明仓库，包含了许多流行 JavaScript 库的类型定义。你可以通过 @types 包快速添加这些声明。

安装示例

npm install @types/lodash

// app.ts
import * as _ from 'lodash';
const arr = [1, 2, 3, 4];
console.log(_.reverse(arr)); // [4, 3, 2, 1]

外部声明的最佳实践

1. 使用社区维护的类型定义：优先使用 DefinitelyTyped 上的类型定义，避免重复定义和维护类型。
2. 适当使用全局声明：尽量使用模块声明，减少全局变量，避免命名冲突。
3. 为常用库定义类型：如果使用的库没有类型定义，可以为其定义类型，并考虑贡献给社区。

示例：贡献类型定义

// custom-library.d.ts
declare module 'custom-library' {
    export function customFunction(param: string): void;
    export interface CustomInterface {
        property: number;
    }
}

扩展已有类型

有时你需要扩展已有库的类型定义。你可以通过模块扩展（Module Augmentation）来实现。

示例

// axios-extensions.d.ts
import 'axios';
declare module 'axios' {
    export interface AxiosRequestConfig {
        customProperty?: string;
    }
}

// app.ts
import axios from 'axios';
axios.get('/api', {
    customProperty: 'customValue'
});

类型声明文件的结构

类型声明文件（.d.ts）通常包含以下内容：

• 全局声明：使用 declare 关键字声明全局变量、函数、类等。
• 模块声明：使用 declare module 关键字声明模块。
• 命名空间：使用 declare namespace 关键字组织全局声明。
• 类型别名：使用 type 关键字定义类型别名。
• 接口：使用 interface 关键字定义接口。
• 类：使用 class 关键字定义类。

示例

// example.d.ts
declare namespace ExampleNamespace {
    interface ExampleInterface {
        property: string;
    }
    class ExampleClass {
        constructor(param: string);
        method(): void;
    }
}
declare module 'example-module' {
    export function exampleFunction(param: number): void;
    export interface ExampleModuleInterface {
        property: number;
    }
}

结论

外部声明是 TypeScript 中的重要特性，提供了描述外部代码库类型信息的机制。通过外部声明，你可以在 TypeScript 项目中使用 JavaScript 库或其他外部资源时，获得类型检查和自动补全的好处。在实际开发中，合理使用外部声明可以提高代码的类型安全性和可维护性。