TypeScript类型声明合并扩展全局Window对象

在TypeScript开发中，我们经常需要扩展全局Window对象来添加自定义属性或方法。本文将详细介绍如何使用TypeScript的类型声明合并功能来实现这一点。

基础概念

理解类型声明合并机制：
TypeScript允许合并不同声明的类型定义。当你在多个位置声明同一个接口时，TypeScript会将这些声明合并成一个完整的接口。这为我们扩展内置对象如Window提供了可能。

准备开发环境：
确保你的项目已经配置好TypeScript，并且有一个tsconfig.json文件。如果没有，创建一个新的TypeScript项目或运行以下命令初始化：

npm init -y
npm install typescript --save-dev
npx tsc --init

创建类型声明文件：
导航到你的项目根目录，创建一个types文件夹（如果不存在）。在这个文件夹中，添加一个window.d.ts文件，这是我们将用来扩展Window对象的声明文件。

// types/window.d.ts
interface Window {
  myApp: {
    version: string;
    init(): void;
  };
}

扩展Window对象

定义基本扩展：
在window.d.ts文件中，定义你想要添加到Window对象的属性和方法。上面的例子添加了一个名为myApp的属性，包含版本信息和初始化方法。

应用扩展后的Window：
在你的TypeScript代码中，现在可以正常使用这些扩展的属性：

// 使用扩展后的Window对象
window.myApp.init();
window.myApp.version = "1.0.0";

添加多个扩展：
创建额外的声明文件来进一步扩展Window对象：

// types/window-methods.d.ts
interface Window {
  myCustomMethod(): string;
  myCustomProp: number;
}

使用模块声明语法：
你也可以使用declare global语法来扩展Window对象，这在更大型的项目中更常见：

// types/global-extensions.ts
declare global {
  interface Window {
    myGlobalApp: {
      config: {
        apiKey: string;
        debug: boolean;
      };
    };
  }
}

处理第三方库扩展：
当你使用的第三方库扩展了全局Window对象时，创建相应的类型声明来包含这些扩展。例如，对于jQuery：

// types/jquery.d.ts
interface Window {
  jQuery: any;
  $: any;
}
```

## 实际应用场景

**实现**全局状态管理：
**设计**一个简单的全局状态管理系统：

```typescript
// types/store.d.ts
interface Window {
  store: {
    getState(): object;
    dispatch(action: object): void;
    subscribe(listener: () => void): () => void;
  };
}

// 使用示例
window.store.dispatch({ type: 'INCREMENT' });
const unsubscribe = window.store.subscribe(() => console.log('State changed!'));
```

**添加**调试工具：
**创建**一个开发环境的调试工具：

```typescript
// types/debug.d.ts
interface Window {
  __DEBUG__: {
    log(message: string): void;
    error(error: Error): void;
    isDev: boolean;
  };
}

// 使用示例
if (window.__DEBUG__.isDev) {
  window.__DEBUG__.log('App initialized');
}
```

**处理**自定义事件系统：
**实现**一个简单的全局事件系统：

```typescript
// types/events.d.ts
interface Window {
  eventBus: {
    on(event: string, callback: Function): void;
    off(event: string, callback: Function): void;
    emit(event: string, data?: any): void;
  };
}

// 使用示例
window.eventBus.on('userLoggedIn', (user) => {
  console.log(`User ${user.name} logged in`);
});

高级技巧

使用命名空间组织代码：
创建命名空间来组织复杂的类型定义：

// types/window-extensions.ts
declare global {
  namespace App {
    interface Config {
      apiKey: string;
      debug: boolean;
    }
  }

  interface Window {
    app: App.Config;
  }
}

// 使用示例
window.app.apiKey = "12345";

合并多个扩展：
在不同的声明文件中添加相同的扩展，TypeScript会自动合并它们：

// types/window-a.d.ts
interface Window {
  sharedProp: string;
  onlyA: number;
}

// types/window-b.d.ts
interface Window {
  sharedProp: string;
  onlyB: boolean;
}

// 最终合并结果
// Window接口将包含sharedProp, onlyA, onlyB三个属性

处理命名冲突：
避免多个扩展定义同名属性的不同类型。如果发生冲突，TypeScript会报错。解决方案是统一类型定义或使用不同的命名：

// 错误示例 - 类型不兼容
interface Window {
  myData: string;
}

interface Window {
  myData: number; // 错误：类型不兼容
}

// 正确示例 - 使用不同的命名
interface Window {
  myDataString: string;
}

interface Window {
  myDataNumber: number;
}

类型定义管理

安装类型定义包：
运行以下命令安装第三方库的类型定义：

npm install --save-dev @types/库名

配置TypeScript查找路径：
编辑tsconfig.json文件，添加自定义类型定义路径：

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

使用条件类型定义：
创建仅在特定条件下才可用的类型扩展：

// types/conditional.d.ts
interface Window {
  readonly inProduction: boolean;
}

// 仅在生产环境中可用的属性
type ProductionWindow = Window & {
  productionOnly: string;
};

// 使用示例
declare const win: ProductionWindow;
win.productionOnly = "value"; // 仅在inProduction为true时有效

调试和验证

验证类型定义：
运行TypeScript编译器检查你的代码类型正确性：

tsc --noEmit

使用类型断言：
在某些情况下，你可能需要使用类型断言来告诉TypeScript变量的类型：

const app = window.myApp as { version: string; init(): void };
app.init();

检查声明文件是否生效：
创建一个简单的测试文件来验证你的扩展是否工作：

// test.ts
window.myApp.init(); // 应该没有类型错误
console.log(window.myApp.version);

// 如果未定义的属性，TypeScript应该报错
console.log(window.undefinedProperty); // 应该有类型错误

最佳实践

保持类型定义简洁：
避免在全局命名空间中定义过于复杂的类型。考虑将复杂的类型定义放在单独的文件中并使用模块导出。

添加类型注释：
使用JSDoc注释来添加类型说明，提高代码可读性：

/**
 * 初始化应用程序
 * @param config 配置选项
 */
declare function initApp(config: { theme: string; language: string }): void;

interface Window {
  initApp: typeof initApp;
}

组织类型定义文件：
按照功能或模块组织你的类型定义文件，便于维护：

types/
├── window/
│   ├── base.d.ts
│   ├── methods.d.ts
│   └── events.d.ts
├── third-party/
│   ├── jquery.d.ts
│   └── lodash.d.ts
└── app/
    ├── store.d.ts
    └── api.d.ts

更新类型定义：
保持你的类型定义与实际代码同步。当添加新的全局属性或方法时，记得更新相应的类型声明。

通过以上方法，你可以有效地使用TypeScript的类型声明合并功能来扩展全局Window对象，从而获得更好的类型检查和代码提示，提高开发效率和代码质量。