Vue 3源码极客之：`Vue`的`types`：`Vue`如何利用`TS`的`declare module`进行类型声明。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众，晚上好！我是今天的主讲人，咱们今晚聊聊 Vue 3 源码里那些让人又爱又恨的 TypeScript 类型声明，特别是 declare module 这玩意儿，看看 Vue 是怎么把它玩转的，让我们的代码既安全又丝滑。准备好，发车了！

第一站：declare module 是个啥？

首先，咱们得明白 declare module 这玩意儿是干嘛的。简单来说，它就是 TypeScript 里的一种“类型声明扩充”机制。你可以把它想象成一个“类型补丁”，用来告诉 TypeScript 编译器：

“嘿，我知道有这么个模块（module）存在，虽然我没找到它的定义，但它长这样！”
“嘿，这个模块已经存在了，我想给它加点新东西，比如新的属性或者方法！”

为什么要用它呢？通常是因为：

引入了没有类型定义的 JavaScript 库： 很多老牌的 JavaScript 库并没有提供 TypeScript 的类型定义文件（.d.ts），这时候我们就需要自己声明它们。
扩展现有的模块： 有时候我们需要给现有的模块添加一些自定义的属性或者方法，但又不想直接修改原始模块的代码。
全局类型声明： 在一些特殊的场景下，我们可能需要在全局范围内声明一些类型。

举个简单的例子，假设我们有一个 JavaScript 库叫 my-lib，它没有提供类型定义，里面有个函数叫 doSomething()。我们可以这样声明它：

// my-lib.d.ts (类型声明文件)
declare module 'my-lib' {
  export function doSomething(arg: string): void;
}

// 使用
import { doSomething } from 'my-lib';

doSomething('Hello, world!'); // TypeScript 知道 doSomething 接受一个字符串参数

如果没有上面的 declare module，TypeScript 就会报错，说找不到 my-lib 模块。

第二站：Vue 3 里的 declare module 之旅

Vue 3 源码里，declare module 用得那叫一个炉火纯青。它主要用在以下几个地方：

扩展 Vue 的类型： Vue 3 暴露了很多全局的类型，比如 App、Component、VNode 等等。为了方便用户进行类型扩展，Vue 使用 declare module 允许用户给这些类型添加自定义的属性。
扩展 ComponentCustomProperties： 这是 Vue 3 提供的一个专门用于扩展组件实例属性的接口。通过 declare module，我们可以给组件实例（this）添加自定义的属性。
扩展 GlobalComponents： 允许用户注册全局组件，并让 TypeScript 知道这些组件的存在。

咱们一个个来看。

2.1 扩展 Vue 的类型

Vue 允许我们扩展 Vue 的类型，添加一些自定义的配置选项。比如，我们可以添加一个 myPlugin 选项：

// 你的类型声明文件 (比如: vue.d.ts)
import { ComponentCustomProperties } from 'vue'

declare module '@vue/runtime-core' {
  export interface App<HostElement = any> {
    myPlugin?: string;
  }

  export interface ComponentCustomProperties {
    $myCustomProperty: string
  }
}

// 使用
import { createApp } from 'vue';

const app = createApp({
  setup() {
    return {
      message: 'Hello, Vue!'
    };
  }
});

app.myPlugin = 'My Plugin Value'; // TypeScript 不会报错
app.mount('#app');

在这个例子中，我们使用 declare module '@vue/runtime-core' 扩展了 @vue/runtime-core 模块中的 App 接口，添加了一个可选的 myPlugin 属性。这样，我们就可以在 createApp 创建的 app 实例上使用 myPlugin 属性，而 TypeScript 不会报错。

同时，我们也扩展了 ComponentCustomProperties 接口，添加了一个 $myCustomProperty 属性，这样我们就可以在组件实例中使用 this.$myCustomProperty，而 TypeScript 不会报错。

2.2 扩展 ComponentCustomProperties

这是最常用的场景，允许我们给组件实例添加自定义的属性。比如，我们想在每个组件里都能访问一个全局的 API 客户端：

// 你的类型声明文件 (比如: vue.d.ts)
import { ComponentCustomProperties } from 'vue'

declare module '@vue/runtime-core' {
  export interface ComponentCustomProperties {
    $api: {
      getUsers: () => Promise<any[]>;
      // 其他 API 方法
    };
  }
}

// 使用
import { defineComponent } from 'vue';

const MyComponent = defineComponent({
  mounted() {
    this.$api.getUsers().then(users => {
      console.log(users);
    });
  },
});

在这个例子中，我们扩展了 ComponentCustomProperties 接口，添加了一个 $api 属性，它是一个包含 getUsers 方法的对象。现在，我们就可以在任何组件中使用 this.$api.getUsers()，而 TypeScript 知道 $api 的类型。

2.3 扩展 GlobalComponents

如果我们要注册全局组件，并且希望 TypeScript 能够识别它们，我们可以使用 declare module 扩展 GlobalComponents 接口：

// 你的类型声明文件 (比如: vue.d.ts)
import { defineComponent } from 'vue';

declare module '@vue/runtime-core' {
  export interface GlobalComponents {
    MyButton: ReturnType<typeof defineComponent>; // 或者直接写组件的类型
  }
}

// 使用
import { createApp } from 'vue';
import MyButton from './components/MyButton.vue';

const app = createApp({});
app.component('MyButton', MyButton); // 注册全局组件

// 在模板中使用
// <template>
//   <MyButton @click="handleClick">Click me</MyButton>
// </template>

在这个例子中，我们扩展了 GlobalComponents 接口，添加了一个 MyButton 属性，它的类型是 ReturnType<typeof defineComponent>，也就是 defineComponent 返回的组件类型。这样，在模板中使用 <MyButton> 组件时，TypeScript 就知道它的类型了。

第三站：Vue 源码里的真实案例

为了更深入地理解 Vue 3 如何使用 declare module，我们可以看看 Vue 源码里的一些例子。

在 packages/runtime-core/src/index.ts 文件中，我们可以看到这样的代码：

// packages/runtime-core/src/index.ts
export {
  // ...
  ComponentCustomProperties,
  // ...
}

这里导出了 ComponentCustomProperties 接口，允许用户在外部进行类型扩展。

在 packages/runtime-core/src/component.ts 文件中，我们可以看到 Vue 内部使用了 ComponentCustomProperties 接口：

// packages/runtime-core/src/component.ts
import { ComponentCustomProperties } from './index'

// ...

export interface ComponentInternalInstance {
  // ...
  ctx: Data & ComponentCustomProperties
  // ...
}

这里将 ComponentCustomProperties 接口合并到了组件实例的 ctx 属性中，使得用户可以通过 this 访问自定义的属性。

第四站：注意事项与最佳实践

在使用 declare module 进行类型声明时，有一些注意事项和最佳实践需要牢记：

类型声明文件的位置： 类型声明文件通常放在项目的根目录下，或者放在 src 目录下，并以 .d.ts 为后缀名。
模块名称： declare module 后面跟着的模块名称必须与实际的模块名称一致。如果是扩展 Vue 的类型，应该使用 '@vue/runtime-core'。
接口合并： TypeScript 允许合并同名的接口。这意味着我们可以多次使用 declare module 扩展同一个接口，而 TypeScript 会将它们合并成一个。
避免滥用： 尽量不要滥用 declare module。只有在确实需要扩展现有模块或者声明没有类型定义的模块时才使用它。如果可以找到现有的类型定义文件，尽量使用现有的。
类型安全： 确保你声明的类型是正确的。错误的类型声明可能会导致 TypeScript 无法正确地进行类型检查。

第五站：常见问题与解决方案

在使用 declare module 的过程中，可能会遇到一些问题。下面是一些常见问题和解决方案：

类型声明不生效： 可能是类型声明文件的位置不正确，或者模块名称不正确。检查类型声明文件的位置和模块名称是否正确。
类型冲突： 如果多个类型声明文件声明了同一个模块，可能会导致类型冲突。确保只有一个类型声明文件声明了同一个模块。
无法找到模块： 可能是模块没有安装，或者模块的类型定义文件没有安装。确保模块已经安装，并且已经安装了模块的类型定义文件。

第六站：案例分析：如何为 Vuex 添加类型支持

很多 Vue 项目都会用到 Vuex。如果你的 Vuex 没有类型定义，你可以使用 declare module 来添加类型支持。

// vuex.d.ts
import { Store } from 'vuex';

declare module '@vue/runtime-core' {
  // 为 `this.$store` 提供类型声明
  interface ComponentCustomProperties {
    $store: Store<any>
  }
}

declare module 'vuex' {
  // 声明你的 store 的 state 类型
  export interface State {
    count: number
  }

  // 重载 `Store` 类，让它可以接受你的 state 类型
  export class Store<S = any> {
    constructor(options: StoreOptions<S>);

    get state(): S;

    // ... 其他 Vuex API
  }

  // 重载 `StoreOptions` 接口，让它可以接受你的 state 类型
  export interface StoreOptions<S> {
    state?: S | (() => S)
    // ...
  }

  // 重载 `useStore` 函数，让它可以返回你的 state 类型
  export function useStore<S = State>(key?: string): Store<S>
}

在这个例子中，我们首先扩展了 @vue/runtime-core 模块，为组件实例添加了 $store 属性的类型声明。然后，我们扩展了 vuex 模块，声明了 State 接口，并重载了 Store 类、StoreOptions 接口和 useStore 函数，让它们可以接受我们的 State 类型。

第七站：总结

declare module 是 TypeScript 里一个非常强大的类型声明机制。通过它可以扩展现有的模块，添加自定义的属性，或者声明没有类型定义的模块。在 Vue 3 源码里，declare module 被广泛地应用，用于扩展 Vue 的类型，允许用户进行自定义的类型扩展。

希望通过今天的讲座，大家对 declare module 有了更深入的理解。记住，合理地使用 declare module 可以让我们的代码更加安全、可维护，提高开发效率。

感谢大家的收听，咱们下期再见！

发表回复 取消回复

发表回复取消回复