当前位置：首页 > article >正文

Vue 项目命名规范指南

article 2025/9/17 11:22:26

📚 Vue 项目命名规范指南（适用于 Vue 3 + Pinia + Vue Router）

目的：统一命名风格，提升可读性、可维护性和团队协作效率。

一、通用原则

类型	命名风格	示例
变量	`camelCase`	`userName`, `isLoading`
常量	`UPPER_SNAKE_CASE`	`MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT`
函数/方法	`camelCase`	`fetchData`, `validateForm`
类 / 组件 / 枚举 / 路由 name	`PascalCase`	`UserProfile`, `ErrorBoundary`
自定义指令（Vue）	`kebab-case`	`v-focus`, `v-tooltip`
URL 路径	`kebab-case`	`/user-profile`, `/settings/account`

二、组件相关命名规范

1. 组件文件名

使用 PascalCase 或 KebabCase。
推荐使用 PascalCase，便于在 JS 中直接引用。

components/UserProfile.vue        ✅ 推荐userProfile.vue        ❌ 不推荐（容易与变量混淆）user-profile.vue       ✅ 在模板中使用时推荐

2. 组件注册与使用

注册时使用 PascalCase：

import UserProfile from './components/UserProfile.vue'

模板中使用 kebab-case：

<template><user-profile :user="user" />
</template>

3. Props 命名（组件间传参）

使用 camelCase（JS 中），模板中用 kebab-case。
避免缩写（除非是通用缩写如 id, url）。

props: {userName: String,isActive: Boolean,userId: Number
}

<template><UserCard :user-name="name" :is-active="true" />
</template>

三、Vue Router 相关命名规范

1. 路由路径（URL）

使用 kebab-case，清晰表达资源结构。

{path: '/user-profile',name: 'UserProfile',component: () => import('../views/UserProfile.vue')
}

2. 路由名称（name）

使用 PascalCase，与组件名保持一致。

name: 'UserProfile'

3. 动态参数命名

参数名使用 kebab-case（URL），JS 中访问使用 camelCase。

path: '/user/:user_id' // URL 中使用
$route.params.userId    // JS 中自动转为 camelCase

四、Pinia 状态管理命名规范

1. Store 文件名

使用小驼峰命名，以 .store.js 或 .store.ts 结尾。

stores/userStore.jscartStore.js

2. State 属性命名

使用 camelCase，语义明确。

state: () => ({user: null,isLoading: false,activeTab: 'dashboard'
})

3. Actions 命名

动词开头 + 名词，表示动作。

actions: {async fetchUser(userId) {},updateUser(userData) {}
}

4. Getters 命名

名词或形容词为主，表示派生状态。

getters: {isLoggedIn: (state) => !!state.user,fullName: (state) => `${state.firstName} ${state.lastName}`
}

五、变量与函数命名规范

1. 变量命名

使用 camelCase。
避免模糊命名（如 data, info），应具体说明用途。

let currentUser = null;
let loadingCount = 0;

2. 函数命名

动词开头，描述行为。

function validateForm() {}
function submitData(data) {}

3. 布尔类型变量命名

以 is, has, should 开头。

let isActive = false;
let hasPermission = true;

六、常量命名规范

使用全大写 + 下划线分隔。
通常用于配置项、枚举、固定值等。

const MAX_RETRY_COUNT = 3;
const USER_ROLES = ['admin', 'editor', 'viewer'];

七、事件命名规范（Vue 组件通信）

使用 kebab-case，在子组件中 $emit 时使用：

this.$emit('update:loading', false);

在父组件中监听：

<template><ChildComponent @update:loading="handleLoadingChange" />
</template>

八、自定义指令命名规范

使用 kebab-case，符合 HTML 规范。

app.directive('focus', {mounted(el) {el.focus();}
});

使用方式：

<input v-focus />

九、样式类命名建议（可选）

推荐使用 BEM 风格或 CSS-in-JS 工具。
如果使用 SCSS/CSS，建议命名清晰：

.user-card {}
.user-card__header {}
.user-card--active {}

十、模块化命名建议

如果你的项目采用模块化结构（如多个 store、路由模块、功能模块），建议在命名中加入上下文前缀。

示例：

类型	示例
Store	`userStore.js`, `productStore.js`
路由模块	`userRoutes.js`, `orderRoutes.js`
组件	`UserList.vue`, `UserDetail.vue`

十一、附录：命名风格总结表

类型	命名风格	示例
组件名	PascalCase	`UserProfile.vue`
模板标签	kebab-case	`<user-profile />`
Props	camelCase（JS） / kebab-case（模板）	`userName`, `user-name`
路由 name	PascalCase	`'UserProfile'`
路由路径	kebab-case	`/user-profile`
动态路由参数	kebab-case（URL） / camelCase（JS）	`:user_id` → `params.userId`
变量	camelCase	`userName`, `isLoading`
常量	UPPER_SNAKE_CASE	`MAX_RETRY_COUNT`
函数	camelCase	`fetchData`, `submitForm`
布尔变量	is/has/should + 描述	`isActive`, `hasPermission`
Pinia state	camelCase	`user`, `cartItems`
Pinia actions	动词 + 名词	`fetchUser`, `addToCart`
Pinia getters	名词/形容词	`isLoggedIn`, `totalPrice`
自定义指令	kebab-case	`v-focus`