声明文件生成器
declarationGenerator 模块负责在项目中生成初始的类型声明文件，这些文件用于提供组件和 API 的类型支持，确保 TypeScript 能够正确识别自动导入的组件和 API。
API 参考
generateDeclarationFiles
1async function generateDeclarationFiles(projectPath: string): Promise<void>;
参数
projectPath: string - 项目根目录的路径
返回值
Promise<void> - 异步操作，成功时无返回值
异常
使用示例
1import { generateDeclarationFiles } from "ew-auto-import-tool";
2
3// 生成初始声明文件
4await generateDeclarationFiles("/path/to/your/project");
实现细节
generateDeclarationFiles 函数会在项目根目录下创建两个初始的声明文件：
- components.d.ts - 组件类型声明文件
- auto-imports.d.ts - API 类型声明文件
这些文件包含基本的类型声明结构，但实际内容会在项目首次启动时由 unplugin-auto-import 和 unplugin-vue-components 插件自动更新。
components.d.ts 模板
1// generated by unplugin-vue-components
2// We suggest you to commit this file into source control
3// Read more: https://github.com/vuejs/core/pull/3399
4import "@vue/runtime-core";
5
6declare module "@vue/runtime-core" {
7 export interface GlobalComponents {
8 // 此处将由插件自动填充组件类型
9 }
10}
11
12export {};
auto-imports.d.ts 模板
1// generated by unplugin-auto-import
2// We suggest you to commit this file into source control
3export {};
声明文件的作用
这些声明文件在项目中起到以下作用：
- 提供类型支持：使 TypeScript 能够识别自动导入的组件和 API，提供代码补全和类型检查
- 改善开发体验：在 IDE 中提供自动补全和类型提示，减少开发过程中的错误
- 文档参考：作为可用组件和 API 的参考文档，帮助开发者了解可用的组件和 API
工作流程
declarationGenerator 模块生成初始的声明文件模板- 当项目首次启动时，
unplugin-auto-import 和 unplugin-vue-components 插件会扫描项目和组件库
- 插件根据扫描结果更新声明文件，添加具体的组件和 API 类型声明
- TypeScript 编译器和 IDE 使用这些声明文件提供类型检查和代码补全
配置后的项目结构
配置完成后，项目根目录下会新增两个声明文件：
my-vue-app/
├── node_modules/
├── public/
├── src/
│ ├── assets/
│ ├── components/
│ ├── App.vue
│ ├── main.ts
│ └── vite-env.d.ts
├── auto-imports.d.ts # 新增：API 自动导入声明文件
├── components.d.ts # 新增：组件自动导入声明文件
├── index.html
├── package.json
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts
源码分析
declarationGenerator 模块使用 fs-extra 库来创建和写入文件：
1// 创建组件声明文件
2const componentsDeclarationContent = `// generated by unplugin-vue-components
3// We suggest you to commit this file into source control
4// Read more: https://github.com/vuejs/core/pull/3399
5import '@vue/runtime-core'
6
7declare module '@vue/runtime-core' {
8 export interface GlobalComponents {
9 // 此处将由插件自动填充组件类型
10 }
11}
12
13export {}
14`;
15
16// 创建API声明文件
17const autoImportsDeclarationContent = `// generated by unplugin-auto-import
18// We suggest you to commit this file into source control
19export {}
20`;
21
22// 写入文件
23await fs.writeFile(
24 componentsDeclarationPath,
25 componentsDeclarationContent,
26 "utf-8"
27);
28await fs.writeFile(
29 autoImportsDeclarationPath,
30 autoImportsDeclarationContent,
31 "utf-8"
32);
注意事项
- 如果声明文件已经存在，函数会跳过创建，避免覆盖已有的文件
- 声明文件的实际内容会在项目首次启动时由插件更新，初始模板只提供基本结构
- 建议将这些声明文件提交到版本控制系统，以便团队成员共享类型定义
