新茶十九
新茶十九

web前端代码指南(vue3)

一、命名规范

市面上常用的命名规范：

  • camelCase（小驼峰式命名法 —— 首字母小写）
  • PascalCase（大驼峰式命名法 —— 首字母大写）
  • kebab-case（短横线连接式）
  • Snake（下划线连接式）

1.1 项目文件命名

1.1.1 项目命名

全部采用小写方式， 以短横线分隔。

  • 正例：mall-management-system
  • 反例：mall_management-system / mallManagementSystem

1.1.2 目录名

参照项目命名规则，有复数结构时，要采用复数命名法。

  • 正例：docs、assets、images、icons、components、directives、enums、hooks、utils、views
  • 反例：script / style / demo_scripts / demoStyles

1.VUE 的项目中的组件components 中的组件使用 PascalCase 命名

  • 正例： HeadSearch / PageLoading / Authorized / NoticeIcon
  • 反例： headSearch / page-loading

2. VUE 的项目中的页面目录使用 camelCase 命名

  • 正例：pageOne / shoppingCar / userManagement
  • 反例： shopping-car / UserManagement

1.1.3 图像文件名: Snake方式

全部采用Snake命名方式， 优先选择单个单词命名，多个单词命名以下划线连接。

banner_sina.gif
menu_aboutus.gif
menutitle_news.gif
logo_police.gif
logo_national.gif
pic_people.jpg
pic_TV.jpg

1.1.4 HTML 文件名: camelCase方式

优先选择单个单词命名，多个单词命名以camelCase方式。

|- errorReport.html
|- successReport.html

1.1.5 CSS 文件名: camelCase方式

全部采用camelCase方式， 优先选择单个单词命名，多个单词命名以短横线分隔。

|- index.scss
|- userCenter.scss

1.1.6 JavaScript 文件名: camelCase方式

全部采用camelCase写方式，优先选择单个单词命名，多个单词命名以短横线分隔。

|- index.js
|- util.js
|- userCenter.js

1.1.6 TypeScript 文件名: camelCase方式

全部采用camelCase写方式，优先选择单个单词命名，多个单词命名以短横线分隔。

|- index.ts
|- util.ts
|- userCenter.ts

除特定配置文件和依赖除外

1.2 Vue组件名

1.2.1 单文件组件名

文件扩展名为 .vue 的 single-file components (单文件组件)。单文件组件名应该PascalCase方式。

components/
|- MyComponent.vue

1.2.2 紧密耦合的组件名

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。 因为编辑器通常会按字母顺序组织文件，所以这样做可以把相关联的文件排在一起。

components/
|- RoleList.vue
|- RoleListItem.vue
|- RoleListItemButton.vue

1.2.3 组件名中单词顺序

组件名应该以高级别的 (通常是一般化描述的) 单词开头，以描述性的修饰词结尾。 因为编辑器通常会按字母顺序组织文件，所以现在组件之间的重要关系一目了然。如下组件主要是用于搜索和设置功能。

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue

1.2.4 完整单词的组件名

组件名应该倾向于完整而不是缩写。 编辑器中的自动补全已经让书写长命名的代价非常之低了，而其带来的明确性却是非常宝贵的。不常用的缩写尤其应该避免。

components/
|- StudentDashboardSettings.vue
|- RoleAuthorization.vue

1.2.5 全局组件命名

**全局组件应采用文件夹加index.vue格式。文件夹名称采用PascalCase格式命名。**其内部组件和页面内部组件采取组件规范。

全局组件
components/
|- ProTable
|  |- index.vue
|  |- components/
|  |  |- ProTableHeader.vue
|  |  |- ProTableBody.vue

1.2.8 api文件

  • api 目录
    文件、变量命名要与模块保持一致，注释明确。
  • 示例：Role模块
// api目录
api/modules/role.ts:

// 添加角色  
addRole: (data) => { 
  return postAxios('/role/add', data)  
}, 

// 删除角色 
deleteRole: (roleId) => {   
  return postAxios('/role/delete/' + roleId)   
},

1.2.9 Vue3项目文件资源目录示例：

my-project-name/
├─ .husky                             # husky 配置文件
├─ .vscode                            # VSCode 推荐配置
├─ build                              # Vite 配置项
├─ public                             # 静态资源文件
├─ docs                               # 项目的细化文档目录（可选）
├─ node_modules                       # 下载的依赖包
├─ src                                # 源码目录
│  ├─ api                             # http 请求目录
│  │  ├─ config                       # http 配置项
│  │  ├─ helper                       # http 封装
│  │  ├─ interface                    # http 接口类型
│  │  │  ├─ userCenter.ts             # http 用户接口
│  │  ├─ modules                      # http 接口模块
│  │  │  ├─ userCenter.ts             # http 用户api模块
│  │  └─ index.ts                     # http 请求入口
│  ├─ assets                          # 静态资源目录
│  ├─ components                      # 全局组件
│  │  ├─ ProTable                     # ProTable组件文件夹
│  │  │  ├─ index.vue                 # ProTable组件
│  │  │  ├─ interface                 # ProTable公共接口
│  │  │  │  ├─ index.ts               # ProTable公共接口文件
│  │  │  ├─ components                # ProTable内部组件
│  │  │  │  ├─ Pagination.vue         # ProTable内部分页组件
│  │  │  │  ├─ TableColumn.vue        # ProTable内部列组件
│  ├─ config                          # 全局配置项
│  ├─ constants                       # 全局常量
│  ├─ enums                           # 项目常用枚举
│  ├─ hooks                           # 常用 Hooks 封装
│  ├─ languages                       # 语言国际化 i18n
│  ├─ directives                      # 全局指令文件
│  ├─ mockApi                         # 模拟接口，临时存放
│  ├─ mockData                        # 模拟数据，临时存放
│  ├─ plugins                         # 插件
│  ├─ routers                         # 路由管理
│  ├─ stores                          # pinia store
│  ├─ styles                          # 全局样式文件
│  ├─ utils                           # 常用工具库
│  ├─ views                           # 页面存放目录
│  │  ├─ role                         # role模块名
│  │  │  ├─ userRole                  # 用户role
│  │  │  │  ├─ index.vue              # 用户role首页/列表
│  │  │  │  ├─ index.scss             # 用户role css
│  │  │  │  └─ detail.vue             # role详情页面
│  │  │  ├─ systemRole                # 系统role
│  │  │  ├─ components                # role模块通用组件文件夹
│  │  │  │  └─ RoleAuthorization.vue  # role授权组件
│  │  │  └─ interface                 # role公共接口文件夹
│  │  └─ user                         # user模块名
│  ├─ App.vue                         # 项目根组件
│  ├─ main.ts                         # 入口文件
│  └─ vite-env.d.ts                   # 指定 ts 识别 vue
├─ .editorconfig                      # 统一不同编辑器的编码风格
├─ .env                               # vite 常用配置
├─ .env.development                   # 开发环境配置
├─ .env.production                    # 生产环境配置
├─ .env.test                          # 测试环境配置
├─ .eslintignore                      # 忽略 Eslint 校验
├─ .eslintrc.cjs                      # Eslint 校验配置文件
├─ .gitignore                         # 忽略 git 提交
├─ .prettierignore                    # 忽略 Prettier 格式化
├─ .prettierrc.cjs                    # Prettier 格式化配置
├─ .stylelintignore                   # 忽略 stylelint 格式化
├─ .stylelintrc.cjs                   # stylelint 样式格式化配置
├─ CHANGELOG.md                       # 项目更新日志
├─ commitlint.config.cjs              # git 提交规范配置
├─ index.html                         # 入口 html
├─ LICENSE                            # 开源协议文件
├─ lint-staged.config.cjs             # lint-staged 配置文件
├─ package-lock.json                  # 依赖包包版本锁
├─ package.json                       # 依赖包管理
├─ postcss.config.cjs                 # postcss 配置
├─ README.md                          # README 介绍
├─ tsconfig.json                      # typescript 全局配置
└─ vite.config.ts                     # vite 全局配置文件

1.3 代码参数命名

1.3.1 name

组件名应该始终是多个单词，应该始终是 PascalCase 的。 根组件 App 以及 、 之类的 Vue 内置组件除外。

1.3.2 prop

在声明 prop 的时候，其命名应该始终使用 camelCase，而在模板和 JSX 中应该始终使用 kebab-case。我们单纯的遵循每个语言的约定，在 JavaScript 中更自然的是 camelCase。而在 HTML 中则是 kebab-case。

1.3.3 router

**Vue Router Path 命名采用 camelCase 格式。**和views页面尽量保持一致。

// good
{
  "path": "/proTable",
  "name": "proTable",
  "redirect": "/proTable/useProTable",
  "meta": {
    "icon": "MessageBox",
  },
  "children": [
    {
      "path": "/proTable/useProTable",
      "name": "useProTable",
      "component": "/proTable/useProTable/index",
      "meta": {
        "icon": "Menu",
      }
  ]
},
// bad
{
  path: '/user_info', // user_info 当成一个单词
  name: 'UserInfo',
  meta: {
    title: ' - 用户',
    desc: ''
  },
  component: () => import('@/views/file/user-Info.vue')
},

path除了采用camelCase命名规范以外，必须以 / 开头，即使是children里的path也要以 / 开头

目的：
经常有这样的场景：某个页面有问题，要立刻找到这个vue文件，如果不用以/开头，path为parent和children组成的，可能经常需要在router文件里搜索多次才能找到，而如果以/开头，则能立刻搜索到对应的组件

1.3.4 模板中组件

对于绝大多数项目来说，在 单文件组件 和 字符串模板 中 组件名 应该总是 PascalCase 的 ，
但是在 DOM 模板中总是 kebab-case 的。



1.3.5 变量
     
   
  • 命名方法：camelCase
    •  
   
  • 命名规范：类型 + 对象描述或属性的方式
    •  
  
// good
let tableTitle = "LoginTable"
let mySchool = "我的学校"

// bad
var getTitle = "LoginTable"

1.3.6 常量
     
   
  • 命名方法：全部大写下划线分割
    •  
   
  • 命名规范：使用大写字母和下划线来组合命名，下划线用以分割单词
    •  
  
const MAX_COUNT = 10
const URL = 'http://test.host.com'

1.3.7 方法
     
   
  • 命名方法：camelCase
    •  
   
  • 命名规范：统一使用动词或者动词 + 名词形式
    •  
  
// 1、普通情况下，使用动词 + 名词形式
// good
jumpPage、openCarInfoDialog

// bad
go、nextPage、show、open、login

// 2、请求数据方法，以 data 结尾
// good
getListData、postFormData

// bad
takeData、confirmData、getList、postForm

// 3、单个动词的情况
init、refresh




 

 
   
   
   
   
   
   
   
   
   
  
 
    
    
 
     动词 
     含义 
     返回值 
    
 
    
    
    
 
     can 
     判断是否可执行某个动作 (权 ) 
     函数返回一个布尔值。true：可执行；false：不可执行； 
    
 
    
 
     has 
     判断是否含有某个值 
     函数返回一个布尔值。true：含有此值；false：不含有此值； 
    
 
    
 
     is 
     判断是否为某个值 
     函数返回一个布尔值。true：为某个值；false：不为某个值； 
    
 
    
 
     get 
     获取某个值 
     函数返回一个非布尔值 
    
 
    
 
     set 
     设置某个值 
     无返回值、返回是否设置成功或者返回链式对象 
    
 
    
  
 
  
附： 函数方法常用的动词:
 
  
get 获取/set 设置,
add 增加/remove 删除
create 创建/destory 移除
start 启动/stop 停止
open 打开/close 关闭,
read 读取/write 
load 写入/save 保存,
create 创建/destroy 销毁
begin 开始/end 结束,
backup 备份/restore 恢复，
import 导入/export 导出,
split 分割/merge 合并，
inject 注入/extract 提取,
attach 附着/detach 脱离，
bind 绑定/separate 分离,
view 查看/browse 浏览，
edit 编辑/modify 修改,
select 选取/mark 标记，
copy 复制/paste 粘贴,
undo 撤销/redo 重做，
insert 插入/delete 移除,
add 加入/append 添加，
clean 清理/clear 清除,
index 索引/sort 排序，
find 查找/search 搜索,
increase 增加/decrease 减少,
play 播放/pause 暂停,
launch 启动/run 运行，
compile 编译/execute 执行,
debug 调试/trace 跟踪，
observe 观察/listen 监听,
build 构建/publish 发布，
input 输入/output 输出,
encode 编码/decode 解码，
encrypt 加密/decrypt 解密,
compress 压缩/decompress 解压缩，
pack 打包/unpack 解包,
parse 解析/emit 生成，
connect 连接/disconnect 断开,
send 发送/receive 接收，
download 下载/upload 上传,
refresh 刷新/synchronize 同步，
update 更新/revert 复原,
lock 锁定/unlock 解锁，
check out 签出/check in 签入,
submit 提交/commit 交付，
push 推/pull 拉,
expand 展开/collapse 折叠，
begin 起始/end 结束,
start 开始/finish 完成，
enter 进入/exit 退出,
abort 放弃/quit 离开，
obsolete 废弃/depreciate 废旧,
collect 收集/aggregate 聚集

 
  
1.3.8 自定义事件
 
  
自定义事件应始终使用 kebab-case 的事件名。
 
  
不同于组件和 prop，事件名不存在任何自动化的大小写转换。而是触发的事件名需要完全匹配监听这个事件所用的名称。
 
  
// 父组件中调用




 
  
1.3.10 事件方法
 
  
     
   
  • 命名方法：camelCase
    •  
   
  • 命名规范：handle + 名称（可选）+ 动词
    •  
  
 
  




 
  
1.3.11 api命名
 
  
变量命名要与尽可能与模块保持一致，写好注释。
 
  
// 添加角色  
addRole: (data) => { 
  return postAxios('/role/add', data)  
}, 

// 删除角色 
deleteRole: (roleId) => {   
  return postAxios('/role/delete/' + roleId)   
},

 
  
1.3.12 TS接口命名
 
  
     
   
  • 类型使用 PascalCase 命名。不要使用I做为接口名前缀。接口成员使用 camelCase 方式命名
    •  
  
 
  
// Good
interface Foo {
  bar: number;
  baz(): number;
}

// Bad
interface IFoo {
  Bar: number;
  Baz(): number;
}

 
  
     
   
  • 枚举值使用 PascalCase 命名。
    •  
  
 
  
// 推荐
enum StatusEnum {
	SUCCESS = 'success'
}

// Good
enum StatusEnum {
	Success = 'success'
}

// Bad
enum Status {
	success = 'success'
}

 
  
二、代码规范
 
  
2.1 Vue
 
  
2.1.1 代码结构
 
  
     
   
  1. script标签内部加上name属性, 用于定义组件名称
    2.  
   
  2. script 标签内部结构顺序： 
    
       
     
    1. import引入顺序 
      
         
       
      1. 官方/生态 方法、类型
        2.  
       
      2. 全局方法、类型、组件
        3.  
       
      3. 依赖方法、类型、组件
        4.  
       
      4. 局部方法、类型、组件
        5.  
      
       
      2.  
     
    2. 接收参数 
      
         
       
      1. 定义类型接口
        2.  
       
      2. 设置props
        3.  
      
       
      3.  
     
    3. 功能代码（推荐将统一功能的代码写在聚集在一起） 
      
         
       
      1. 功能一 
        
           
         
        1. 定义接口类型
          2.  
         
        2. 定义数据
          3.  
         
        3. 定义计算属性
          4.  
         
        4. 定义方法
          5.  
         
        5. 定义数据监视
          6.  
        
         
        2.  
       
      2. 功能二
         …
        3.  
      
       
      4.  
     
    4. 生命周期
      5.  
     
    5. 其他方法
      6.  
     
    6. 导出内容
      7.  
    
     
    3.  
  
 
  
示例：
 
  


 
  
2.1.2 data
 
  
     
   
  1. 若需要一个基本类型的响应式数据，必须使用ref
    2.  
   
  2. 若需要一个响应式对象，层级不深，ref、reactive都可以
    3.  
   
  3. 若需要一个响应式对象，且层级较深，推荐使用reactive，（form表单数据推荐使用reactive）
    4.  
  
 
  


 
  
2.1.3 computed
 
  
应该把复杂计算属性分割为尽可能多的更简单的属性。 小的、专注的计算属性减少了信息使用时的假设性限制，所以需求变更时也用不着那么多重构了。
 
  


 
  
2.1.4 为 v-for 设置键值
 
  
在组件上必须用 key 搭配 v-for，以便维护内部组件及其子树的状态。
 
  
    
  
  • 
      {{ todo.text }}
  
    • 



 
  
2.1.5 禁止v-if 和 v-for 放在同一个元素上
 
  
永远不要把 v-if 和 v-for 同时用在同一个元素上。因为这可能导致渲染逻辑变得复杂且难以预测。
 Vue3中: 当它们同时存在于一个节点上时，v-if 比 v-for 的优先级更高。这意味着 v-if 的条件将无法访问到 v-for 作用域内定义的变量别名：
 
  


  • 
  {{ todo.name }}

    • 

     
  
    在外先包装一层