Vue3 + TypeScript 组件和文件命名规范及 setup 导入顺序规范

news2025/7/17 0:54:53

前言

在 Vue3 项目中，合理的文件命名规范和导入顺序不仅有助于提高代码的可读性，还能增强团队协作的效率。特别是在使用 TypeScript 和 Composition API 的项目中，清晰的组件和文件结构尤为重要。本文将详细介绍 Vue3 + TypeScript 项目中的组件、文件命名规范，以及 setup 中的导入顺序建议，帮助开发者更高效地组织代码。

文件和组件命名规范

1.1 组件文件命名

全局通用组件：使用 PascalCase 命名，例如 MyButton.vue、UserCard.vue。这些组件一般放置在 src/components 文件夹下。
业务特定组件：也采用 PascalCase 命名，例如 UserProfile.vue、OrderSummary.vue。放置在特定业务模块目录下，如 src/views/user/components。

1.2 非组件文件命名

工具函数文件：使用 kebab-case，如 date-utils.ts、array-helpers.ts。通常放在 src/utils 下。
常量和配置文件：使用 kebab-case，如 app-config.ts、theme-constants.ts。放在 src/constants 或 src/config 下。
API 文件：使用 kebab-case 命名，例如 auth.ts、user.ts。放置在 src/api 文件夹中。
枚举文件：使用 PascalCase，如 ThemeEnum.ts、UserRole.ts。放在 src/enums 文件夹中。
类型定义文件：通常在类型前缀使用 I 或直接以功能命名，文件采用 PascalCase，如 UserType.ts、AuthTypes.ts。放置在 src/types 或 src/interfaces 下。

1.3 其他文件命名

Store 文件：使用 kebab-case 命名，例如 user.ts、tags-view.ts，存放在 src/store 文件夹中。
路由文件：使用 kebab-case 命名，例如 auth-routes.ts、dashboard-routes.ts，放在 src/router 下。

导入顺序

在 Vue3 的 setup 中编写 TypeScript 代码时，保持清晰的导入顺序可以提升代码的可读性。推荐的导入顺序如下：

Vue 和 Composition API：先导入 Vue 核心库以及 Composition API 钩子，如 ref、computed、reactive、watch、useRoute 等。
第三方库：导入第三方库或插件的类型定义和函数，如 axios、element-plus 等。
项目内配置和常量：如全局配置文件和常量，放在 /src/settings 或 /src/constants 下。
枚举和类型定义：包括常用的枚举（Enum）和类型定义（types），通常存放在 /src/enums 和 /src/types 中。
Store 状态管理：引入项目的 Pinia store 模块，通常放在 src/store 中。
API 和工具函数：导入项目内的 API 接口（api）和工具函数（utils）。
业务组件：导入页面或模块专用的子组件。业务组件放在特定页面或模块下的 components 文件夹中。
局部样式：在组件中引入其特定样式。
图片和其他资源：根据需要导入。

示例代码

以下是根据上述导入顺序的示例代码：

<script lang="ts" setup>

// Vue 和 Composition API
import { ref, computed, watch } from 'vue';
import { useRoute } from 'vue-router';

// 第三方库
import type { FormInstance } from 'element-plus';

// 项目内配置和常量
import defaultSettings from '@/settings';
import { BASE_API_URL } from '@/constants/api-constants';

// 枚举和类型定义
import { ThemeEnum } from '@/enums/ThemeEnum';
import type { UserType } from '@/types/UserType';

// API 和工具函数
import AuthAPI from '@/api/dict-data';
import { formatDate } from '@/utils/date-utils';

// Store 状态管理
import { useUserStore } from '@/store/user';
import { useTagsViewStore } from '@/store/tagsView';

// 业务组件
import UserProfile from '@/views/user/components/UserProfile.vue';
import UserExport from '@/views/user/components/UserExport.vue';

import logo from "@/assets/logo.png";

</script>

组件与文件结构建议

为了方便项目的扩展和维护，以下是推荐的文件与组件组织结构：

src/
├── api/                        # API 请求文件
│   ├── auth.ts
│   └── dict-data.ts
├── components/                 # 全局通用组件
│   ├── MyButton.vue
│   └── UserCard.vue
├── constants/                  # 项目中的常量
│   └── api-constants.ts
├── enums/                      # 枚举定义
│   ├── ThemeEnum.ts
├── store/                      # Pinia store
│   ├── user.ts
│   └── tags-view.ts
├── types/                      # 类型定义文件
│   └── UserType.ts
├── utils/                      # 工具函数
│   ├── date-utils.ts
│   └── array-helpers.ts
├── views/                      # 业务页面和组件
    └── user/
        ├── index.vue           # 用户主页面
        └── components/         # 用户模块特有组件
          ├── UserProfile.vue
          └── UserExport.vue