命名规范与代码风格指南

本文档定义了项目中Vue 3应用和文档的命名规范、代码风格以及最佳实践，确保团队协作的一致性和代码可维护性。

文件和目录命名

页面和视图文件

使用 kebab-case（短横线命名法），保持路径一致性，确保跨平台兼容性。

text

src/views/
  user-profile/
    index.vue
  settings-page.vue
  order-list.vue

组件文件

使用 PascalCase（大驼峰命名法），与组件名称保持一致。

text

src/components/
  UserProfile.vue
  SettingsForm.vue
  OrderTable.vue

Composables文件

使用 camelCase（小驼峰命名法），以 use 开头。

text

src/composables/  或 src/hooks/
  usePagination.js
  useUserAuth.js
  useFormData.js

工具函数文件

使用 camelCase。

text

src/utils/
  dateUtils.js
  request.js
  validation.js

目录命名

使用 kebab-case。

text

src/
  api/
  assets/
  components/
  composables/
  directives/
  router/
  store/
  utils/
  views/

组件命名

组件名称规则

单文件组件（SFC）

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

vue

<!-- UserProfile.vue -->
<script setup>
defineOptions({
  name: 'UserProfile'
})
</script>

组件注册

在模板中使用 kebab-case，在JavaScript中使用 PascalCase。

vue

<template>
  <!-- 模板中使用 kebab-case -->
  <user-profile />
  <settings-form />
</template>

<script setup>
// JavaScript 中使用 PascalCase
import UserProfile from '@/components/UserProfile.vue'
import SettingsForm from '@/components/SettingsForm.vue'
</script>

基础组件命名

对于通用基础组件，以 Base 开头，便于在IDE中快速查找和识别。

text

BaseButton.vue
BaseInput.vue
BaseModal.vue
BaseTable.vue

单例组件命名

对于全局只有一个实例的组件，以 The 开头。

text

TheHeader.vue
TheFooter.vue
TheSidebar.vue

紧密耦合组件命名

对于父子关系紧密的组件，使用父组件名作为前缀。

text

TodoList.vue
TodoListItem.vue
TodoListButton.vue

变量和常量命名

基本规则

使用 camelCase（小驼峰），命名要有语义，可读性强。

javascript

// 正确
const userName = 'John'
const isLoading = false
const totalAmount = 100

// 错误
const x = 'John'
const flag = false
const num = 100

布尔值命名

使用 is、has、can、should 等前缀，清晰表示布尔语义。

javascript

// 状态相关
const isLoading = true
const isActive = false
const isVisible = true
const isDisabled = false

// 拥有关系
const hasPermission = true
const hasError = false
const hasData = true

// 能力相关
const canEdit = true
const canDelete = false
const canSubmit = true

// 建议相关
const shouldUpdate = true
const shouldRefresh = false

常量命名

使用 UPPER_SNAKE_CASE（全大写下划线分隔）。

javascript

// API配置
const API_BASE_URL = 'https://api.example.com'
const MAX_RETRY_COUNT = 3
const DEFAULT_PAGE_SIZE = 10

// 状态码
const HTTP_STATUS_OK = 200
const HTTP_STATUS_NOT_FOUND = 404

// 时间相关
const CACHE_EXPIRE_TIME = 3600000
const REQUEST_TIMEOUT = 5000

特殊数据类型命名

对于特定数据结构，使用语义化前缀。

javascript

// 列表数据
const userList = []
const orderList = []
const fileList = []

// 对象数据
const userObject = {}
const configObject = {}

// 选择器数据
const cityPicker = []
const dateSelector = null

// 搜索相关
const searchKeyword = ''
const searchResult = []
const searchFilters = {}

Vue 3响应式数据命名

使用 ref() 和 reactive() 时，遵循Vue 3最佳实践。

javascript

// ref - 用于基本类型和需要整体替换的对象
const count = ref(0)
const user = ref(null)
const loading = ref(false)

// reactive - 用于不需要整体替换的对象
const form = reactive({
  username: '',
  password: ''
})

const pagination = reactive({
  page: 1,
  pageSize: 10,
  total: 0
})

函数和方法命名

基本规则

使用 camelCase，函数名应该是动词或动词短语，清晰表达函数的作用。

事件处理函数

使用 handle 前缀，表示这是对某个事件的响应。

javascript

// 点击事件
function handleClick() {}
function handleButtonClick() {}
function handleItemClick() {}

// 表单事件
function handleSubmit() {}
function handleChange() {}
function handleInput() {}

// 生命周期
function handleMount() {}
function handleUpdate() {}

数据获取函数

使用 fetch 或 load 前缀。

javascript

// 获取数据
async function fetchUserList() {}
async function loadUserInfo() {}
async function fetchOrderDetail() {}

// 刷新数据
async function refreshData() {}
async function reloadPage() {}

状态修改函数

使用 set、update、toggle 等动词。

javascript

// 设置值
function setUserName(name) {}
function setUserAge(age) {}

// 更新状态
function updateUserList(list) {}
function updateFormData(data) {}

// 切换状态
function toggleLoading() {}
function toggleSidebar() {}
function switchTab() {}

数据操作函数

javascript

// 添加
function addUser(user) {}
function addItem(item) {}
function createOrder(order) {}

// 删除
function deleteUser(id) {}
function removeItem(index) {}
function clearList() {}

// 验证
function validateForm(data) {}
function checkPermission(user) {}
function verifyCode(code) {}

工具函数

使用描述性的名称，清晰表达输入和输出的关系。

javascript

// 格式化
function formatDate(date) {}
function formatNumber(num) {}
function formatCurrency(amount) {}

// 转换
function toString(value) {}
function toArray(value) {}
function toJson(data) {}

// 计算
function calculateTotal(items) {}
function computeDiscount(price) {}
function getCount(list) {}

事件命名

自定义事件（Emits）

使用 kebab-case，在模板中绑定事件时使用 kebab-case。

vue

<script setup>
// 定义事件（使用 camelCase）
const emit = defineEmits(['update:modelValue', 'item-click', 'data-change'])

// 触发事件
function handleClick() {
  emit('item-click', { id: 1 })
  emit('update:modelValue', newValue)
}
</script>

<template>
  <!-- 监听事件时使用 kebab-case -->
  <child-component @item-click="handleItemClick" />
</template>

事件命名建议

javascript

// 更新事件
'update:modelValue'
'update:username'
'update:status'

// 交互事件
'item-click'
'button-press'
'form-submit'

// 状态变化事件
'loading-change'
'status-update'
'data-loaded'

CSS和样式命名

使用BEM命名规范

BEM（Block Element Modifier）是一种清晰的CSS命名方法论。

css

/* Block（块）*/
.user-card { }
.button { }

/* Element（元素）*/
.user-card__header { }
.user-card__body { }
.user-card__footer { }
.button__icon { }

/* Modifier（修饰符）*/
.user-card--active { }
.user-card--disabled { }
.button--primary { }
.button--large { }

Vue Scoped样式

在Vue组件中，优先使用 scoped 样式，避免样式污染。

vue

<template>
  <div class="user-list">
    <div class="user-list__item">用户1</div>
    <div class="user-list__item user-list__item--active">用户2</div>
  </div>
</template>

<style scoped>
.user-list {
  padding: 20px;
}

.user-list__item {
  margin-bottom: 10px;
}

.user-list__item--active {
  color: #409eff;
}
</style>

动态类名绑定

使用计算属性或对象语法处理动态类名。

vue

<template>
  <div
    :class="['user-card', cardClass, { 'user-card--active': isActive }]"
  >
    内容
  </div>
</template>

<script setup>
const props = defineProps({
  type: String
})

const isActive = computed(() => props.type === 'active')
const cardClass = computed(() => `user-card--${props.type}`)
</script>

代码注释规范

文件头注释

Vue单文件组件应该包含文件头注释。

vue

<!--
  @description 用户列表页面组件
  @author 作者名
  @date 2025-01-15
-->
<template>
  <div class="user-list">
    <!-- 页面内容 -->
  </div>
</template>

函数注释

对于复杂函数，使用JSDoc风格的注释。

javascript

/**
 * 获取用户列表数据
 * @param {Object} params - 查询参数
 * @param {number} params.page - 页码
 * @param {number} params.pageSize - 每页条数
 * @param {string} params.keyword - 搜索关键词
 * @returns {Promise<Object>} 返回用户列表数据
 * @throws {Error} 网络请求失败时抛出错误
 */
async function fetchUserList(params) {
  const { page, pageSize, keyword } = params
  // 实现代码
}

单行注释

对于简单的逻辑，使用单行注释。

javascript

// 检查用户是否登录
if (isLoggedIn) {
  // 执行登录后的操作
}

// 格式化日期显示
const formattedDate = formatDate(new Date())

逻辑块注释

对于复杂的逻辑块，使用注释分隔。

javascript

function processUserData() {
  // 第一步：获取原始数据
  const rawData = fetchRawData()

  // 第二步：过滤无效数据
  const filteredData = rawData.filter(item => item.isValid)

  // 第三步：格式化数据
  const formattedData = filteredData.map(formatItem)

  // 第四步：返回处理结果
  return formattedData
}

TODO注释

使用TODO标记待完成的功能。

javascript

// TODO: 添加分页功能
// TODO: 优化性能，考虑使用虚拟滚动
// FIXME: 修复在快速点击时的状态异常

代码风格配置

项目使用 Prettier 进行代码格式化，配置文件 .prettierrc.js。

javascript

export default {
  // 每行最大字符数
  printWidth: 150,

  // 缩进空格数
  tabWidth: 2,

  // 使用制表符缩进
  useTabs: true,

  // 语句末尾添加分号
  semi: true,

  // 使用单引号
  singleQuote: true,

  // 对象属性引号规则：仅在需要时添加
  quoteProps: 'as-needed',

  // JSX中使用单引号
  jsxSingleQuote: false,

  // 多行时添加尾随逗号（ES5标准）
  trailingComma: 'es5',

  // 对象括号间添加空格
  bracketSpacing: true,

  // JSX括号换行
  jsxBracketSameLine: false,

  // 箭头函数参数括号
  arrowParens: 'always',

  // 换行符类型
  endOfLine: 'lf'
}

VS Code配置

项目根目录的 .vscode/settings.json 配置：

json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "editor.insertSpaces": false,
  "files.eol": "\n"
}

Git提交规范

项目使用 Husky + Commitlint 强制执行提交消息规范。

提交消息格式

<type>(<scope>): <subject>

类型（type）

类型	说明	示例
feat	新增功能	feat: 新增用户管理模块
fix	修复Bug	fix: 修复登录验证逻辑错误
docs	文档或注释变更	docs: 补充API文档和注释
style	代码格式调整（不影响功能）	style: 格式化代码缩进
refactor	代码重构（不是新功能也不是修复）	refactor: 重构用户列表组件
perf	性能优化	perf: 优化表格渲染性能
test	测试相关	test: 添加用户单元测试
build	构建系统或外部依赖变更	build: 升级Vite到6.0
ci	CI配置文件和脚本变更	ci: 更新GitHub Actions配置
chore	其他不修改src或测试文件的变更	chore: 更新.gitignore
revert	回退之前的提交	revert: feat(用户管理)
update	更新模块或调整功能逻辑	update: 更新订单列表筛选逻辑

范围（scope）

范围用于指定提交影响的模块，例如：

feat(user): 新增用户登录功能
fix(order): 修复订单列表分页错误
docs(api): 更新API接口文档

主题（subject）

主题描述应该：

使用现在时态（"change" 而非 "changed" 或 "changes"）
首字母小写
不要以句号结尾

完整示例

bash

# 新增功能
git commit -m "feat(user): 新增用户注册功能"

# 修复Bug
git commit -m "fix: 修复列表快速切换分页时的报错"

# 更新文档
git commit -m "docs: 补充组件使用示例"

# 重构
git commit -m "refactor(auth): 重构登录验证逻辑"

# 性能优化
git commit -m "perf: 优化用户列表渲染性能"

常用术语表

页面和路由相关

单词	含义	用途
home	首页	网站主页
login	登录	用户登录页面
logout	登出	用户退出登录
register	注册	用户注册页面
profile	个人资料	用户个人信息
settings	设置	用户设置页面
dashboard	仪表盘	数据概览页面
detail	详情	详情页面
list	列表	列表页面
form	表单	表单页面
search	搜索	搜索页面
about	关于	关于页面
contact	联系我们	联系页面
error	错误页	错误页面
not-found	404页面	页面未找到

状态和属性

单词	含义	用途
is	是否	状态前缀
has	是否拥有	拥有关系
can	能否	权限检查
should	是否应该	建议性状态
enabled	启用	功能启用
disabled	禁用	功能禁用
active	激活	激活状态
inactive	未激活	非激活状态
loading	加载中	加载状态
pending	待处理	等待状态
success	成功	成功状态
failed	失败	失败状态
visible	可见	显示状态
hidden	隐藏	隐藏状态
expanded	展开	展开状态
collapsed	收起	收起状态

UI组件

单词	含义	用途
header	头部	页面头部
footer	底部	页面底部
sidebar	侧边栏	侧边导航
navbar	导航栏	导航栏
menu	菜单	菜单组件
dropdown	下拉菜单	下拉选择
button	按钮	按钮组件
input	输入框	输入组件
select	选择框	选择组件
checkbox	复选框	多选框
radio	单选框	单选框
switch	开关	开关组件
slider	滑块	滑动选择
modal	弹窗	模态框
dialog	对话框	对话框
tooltip	提示框	提示组件
table	表格	表格组件
card	卡片	卡片组件
tag	标签	标签组件
badge	徽章	徽章组件
pagination	分页	分页组件
breadcrumb	面包屑	面包屑导航
tabs	标签页	标签页组件

数据操作

单词	含义	用途
get	获取	获取数据
set	设置	设置值
fetch	拉取	API请求
load	加载	加载数据
update	更新	更新数据
delete	删除	删除数据
remove	移除	移除数据
create	创建	创建数据
add	添加	添加数据
edit	编辑	编辑操作
save	保存	保存操作
submit	提交	提交表单
validate	校验	数据验证
reset	重置	重置状态
clear	清空	清空数据
init	初始化	初始化操作
open	打开	打开操作
close	关闭	关闭操作
toggle	切换	切换状态
render	渲染	渲染数据

数据类型

单词	含义	用途
data	数据	通用数据
item	项目	单个项目
items	项目列表	项目集合
value	值	数据值
values	值集合	多个值
key	键	键名
keys	键集合	多个键
id	唯一标识	ID
ids	ID集合	多个ID
name	名称	名称
title	标题	标题
label	标签	标签文本
content	内容	内容
description	描述	描述信息
type	类型	数据类型
status	状态	状态值
state	状态	状态对象
config	配置	配置对象
options	选项	可选项
params	参数	参数对象
query	查询参数	查询字符串
result	结果	结果对象
results	结果集	多个结果
response	响应	API响应
request	请求	API请求

功能模块

单词	含义	用途
auth	授权	认证授权
token	令牌	访问令牌
session	会话	用户会话
cache	缓存	缓存数据
storage	存储	本地存储
redirect	跳转	页面跳转
router	路由	路由配置
route	路由	单个路由
store	仓库	状态存储
state	状态	应用状态
getter	获取器	状态获取
action	动作	状态操作
mutation	变更	状态变更
module	模块	功能模块
feature	功能	特性功能
plugin	插件	插件系统
service	服务	服务层
api	接口	API接口
mock	模拟数据	Mock数据
test	测试	测试代码
spec	规范	测试规范
build	构建	构建工具
deploy	部署	部署流程
env	环境	环境变量

辅助工具

单词	含义	用途
utils	工具	工具函数
helper	帮助类	辅助类
common	通用	通用模块
constants	常量	常量定义
config	配置	配置文件
settings	设置	设置文件
theme	主题	主题配置
style	样式	样式文件
styles	样式集合	多个样式
assets	资源	资源文件
images	图片	图片资源
icons	图标	图标资源
fonts	字体	字体文件
vendor	第三方库	第三方库
core	核心	核心模块
base	基础	基础模块
shared	共享	共享模块

用户和角色

单词	含义	用途
user	用户	用户对象
users	用户列表	多个用户
admin	管理员	管理员
guest	访客	访客用户
member	成员	成员用户
role	角色	用户角色
roles	角色列表	多个角色
permission	权限	权限设置
permissions	权限列表	多个权限

错误和日志

单词	含义	用途
error	错误	错误信息
errors	错误集合	多个错误
warning	警告	警告信息
message	消息	提示消息
messages	消息集合	多个消息
notification	通知	通知消息
log	日志	日志记录
logger	日志器	日志工具

Vue 3特殊规范

Composition API命名

Composables命名

使用 use 前缀，返回对象中包含响应式状态和方法。

javascript

// usePagination.js
import { ref, computed } from 'vue'

export function usePagination(apiFunc) {
  const loading = ref(false)
  const dataList = ref([])
  const pagination = reactive({
    page: 1,
    pageSize: 10,
    total: 0
  })

  async function loadData() {
    loading.value = true
    try {
      const res = await apiFunc({
        page: pagination.page,
        pageSize: pagination.pageSize
      })
      dataList.value = res.list
      pagination.total = res.total
    } finally {
      loading.value = false
    }
  }

  return {
    loading,
    dataList,
    pagination,
    loadData
  }
}

生命周期函数命名

使用 on 前缀，清晰表达生命周期钩子。

javascript

import { onMounted, onUnmounted } from 'vue'

onMounted(() => {
  // 组件挂载后的操作
})

onUnmounted(() => {
  // 组件卸载前的清理操作
})

Props和Emits命名

Props定义

使用 TypeScript 类型定义，属性名使用 camelCase。

vue

<script setup>
interface Props {
  userName: string
  isActive?: boolean
  userId: number
}

// 使用 withDefaults 设置默认值
const props = withDefaults(defineProps<Props>(), {
  isActive: false
})
</script>

Emits定义

事件名使用 kebab-case，但 defineEmits 中使用 camelCase。

vue

<script setup>
interface Emits {
  'update:modelValue': [value: string]
  'item-click': [item: Item]
  'data-change': [data: Data, options?: Options]
}

const emit = defineEmits<Emits>()

// 触发事件
function handleClick(item) {
  emit('item-click', item)
}
</script>

Ref和Reactive命名

javascript

// ref - 用于基本类型和需要整体替换的对象
const count = ref(0)
const user = ref<User | null>(null)
const error = ref<string>('')

// reactive - 用于深层对象
const form = reactive<FormData>({
  username: '',
  password: ''
})

// computed - 计算属性，使用动词过去式
const filteredList = computed(() =>
  list.value.filter(item => item.active)
)

const isValid = computed(() =>
  form.username && form.password
)

Watch和WatchEffect命名

javascript

// watch - 监听特定源
watch(
  () => props.userId,
  (newId, oldId) => {
    console.log(`用户ID从${oldId}变为${newId}`)
  }
)

// watchEffect - 自动追踪依赖
watchEffect(() => {
  console.log(`当前用户：${user.value?.name}`)
})

最佳实践总结

通用原则

语义化优先：名称应该清晰表达其用途，避免缩写（除非是广泛认知的缩写）
一致性：整个项目中保持命名风格一致
可读性：名称应该易于阅读和理解
避免过载：不要使用语言保留字和内置函数名
简洁明确：在保证清晰的前提下，尽量简短

Vue 3特定建议

组件命名：使用 PascalCase，与文件名保持一致
事件命名：使用 kebab-case，遵循 Vue 3 约定
Composables命名：使用 use 前缀
响应式数据：根据场景选择 ref 或 reactive
类型安全：使用 TypeScript 定义 Props、Emits 和数据类型

命名规范与代码风格指南 ​

文件和目录命名 ​

页面和视图文件 ​

组件文件 ​

Composables文件 ​

工具函数文件 ​

目录命名 ​

组件命名 ​

组件名称规则 ​

单文件组件（SFC） ​

组件注册 ​

基础组件命名 ​

单例组件命名 ​

紧密耦合组件命名 ​

变量和常量命名 ​

基本规则 ​

布尔值命名 ​

常量命名 ​

特殊数据类型命名 ​

Vue 3响应式数据命名 ​

函数和方法命名 ​

基本规则 ​

事件处理函数 ​

数据获取函数 ​

状态修改函数 ​

数据操作函数 ​

工具函数 ​

事件命名 ​

自定义事件（Emits） ​

事件命名建议 ​

CSS和样式命名 ​

使用BEM命名规范 ​

Vue Scoped样式 ​

动态类名绑定 ​

代码注释规范 ​

文件头注释 ​

函数注释 ​

单行注释 ​

逻辑块注释 ​

TODO注释 ​

代码风格配置 ​

VS Code配置 ​

Git提交规范 ​

提交消息格式 ​

类型（type） ​

范围（scope） ​

主题（subject） ​

完整示例 ​

常用术语表 ​

页面和路由相关 ​

状态和属性 ​

UI组件 ​

数据操作 ​

数据类型 ​

功能模块 ​

辅助工具 ​

用户和角色 ​

错误和日志 ​

Vue 3特殊规范 ​

Composition API命名 ​

Composables命名 ​

生命周期函数命名 ​

Props和Emits命名 ​

Props定义 ​

Emits定义 ​

Ref和Reactive命名 ​

Watch和WatchEffect命名 ​

最佳实践总结 ​

通用原则 ​

Vue 3特定建议 ​

命名规范与代码风格指南

文件和目录命名

页面和视图文件

组件文件

Composables文件

工具函数文件

目录命名

组件命名

组件名称规则

单文件组件（SFC）

组件注册

基础组件命名

单例组件命名

紧密耦合组件命名

变量和常量命名

基本规则

布尔值命名

常量命名

特殊数据类型命名

Vue 3响应式数据命名

函数和方法命名

基本规则

事件处理函数

数据获取函数

状态修改函数

数据操作函数

工具函数

事件命名

自定义事件（Emits）

事件命名建议

CSS和样式命名

使用BEM命名规范

Vue Scoped样式

动态类名绑定

代码注释规范

文件头注释

函数注释

单行注释

逻辑块注释

TODO注释

代码风格配置

VS Code配置

Git提交规范

提交消息格式

类型（type）

范围（scope）

主题（subject）

完整示例

常用术语表

页面和路由相关

状态和属性

UI组件

数据操作

数据类型

功能模块

辅助工具

用户和角色

错误和日志

Vue 3特殊规范

Composition API命名

Composables命名

生命周期函数命名

Props和Emits命名

Props定义

Emits定义

Ref和Reactive命名

Watch和WatchEffect命名

最佳实践总结

通用原则

Vue 3特定建议