前端开发规范

一、基本原则

1. 语义化

   1. HTML/CSS 使用语义化标签和类名（如 <header> 而非 <div class="top">）

2. 模块化

   1. 组件按功能拆分，遵循单一职责原则

3. 性能优先

   1. 减少重绘、压缩资源、按需加载

二、目录结构与文件规范

项目目录

src/  
├── assets/          # 静态资源  
├── components/      # 通用组件 (Button, Input)  
├── views/           # 页面级组件  
├── styles/          # 全局样式与变量  
├── utils/           # 工具函数  
├── api/             # 接口封装  
├── router/          # 路由配置  
└── store/           # 状态管理

文件命名

• HTML/CSS：小写短横线（login-page.css）。
• JS类/Vue/React组件：大驼峰（PrimaryButton.vue）。
• 图片：描述性命名（banner-home.png）。

三、HTML 规范

1. 语法

   1. 属性双引号：<div class="container">。
   2. 自闭合标签加斜线：<img src="..." />。

2. 属性顺序

class > id > data-* > src/type/href > alt/title

ref > props > event

<CustomComponent ref="test" prop1="1" @click="test" />

3. 语义化示例

 <!-- Bad -->
<div onclick="submit()">Submit</div>

<!-- Good -->
<button type="submit" class="btn-primary">Submit</button>

四、CSS/SCSS 规范

1. 命名

   1. 外套 wrap ------------------用于最外层

   2. 头部 header ----------------用于头部

   3. 主要内容 main ------------用于主体内容（中部）

   4. 左侧 main-left -------------左侧布局

   5. 右侧 main-right -----------右侧布局

   6. 导航条 nav -----------------网页菜单导航条

   7. 内容 content ---------------用于网页中部主体

   8. 底部 footer -----------------用于底部

   9. 文件中CSS命名规范

      • 1.所有命名以中划线'-'连接
      • 2.文件最外层类名

   10. 项目名-文件夹名-文件名-wrap，例如：labour-roster-wrap{}

2. 属性顺序

.selector {
  /* 布局 */
  display: flex;
  position: absolute;

  /* 盒模型 */
  width: 100%;
  padding: 10px;

  /* 视觉 */
  background: #fff;
  color: #333;

  /* 文本 */
  font-size: 16px;
  line-height: 1.5;

  /* 其他 */
  z-index: 10;
}

3. 嵌套层级

属性层级尽量不要超过三级

.card {
  .header {
    .title { ... }
  }
}

五、JavaScript规范

1. 语法

   1. 代码行尾加分号；
   2. 相等判断尽量使用 ===
   3. 变量声明优先级 const > let > var

2. 命名

   1. 变量/函数：小驼峰（getUserInfo）。
   2. 类/组件：大驼峰（UserModel）。
   3. 常量：全大写（API_TIMEOUT = 5000）。

3. 模块化

 // utils/auth.js
export const login = (username, password) => { ... };

// 使用
import { login } from '@/utils/auth';

六、组件设计规范

1. props设计

必填项提供默认值

props: {
    size: { type: String, default: 'medium' }
}

2. API命名

• 事件：onClick、onChange。

3. 避免props臃肿

复杂场景用插槽（Slot）替代嵌套Props

<Modal>
  <template #header> Custom Header </template>
</Modal>

七、工作流与提交规范

1. Git 分支策略

main：生产分支

test：测试分支

dev：开发分支（暂无开发环境可无此分支）

feat-*：功能分支

hotfix-*: 线上问题临时分支

功能分支和hotfixf分支在测试通过上线后随即删除，保持git仓库分支清晰简洁

2. Commit Message

commit message 写清楚此次提交的内容

八、注释

注释统一

1. 文件注释

   <!--
    * @Description:
    * @Author: suer
    * @Date: 2021-12-13 17:45:53
    * @LastEditTime: 2021-12-14 13:45:53
    * @LastEditors: user
    * @Usage:  组件使用说明
   -->

2. 函数注释

   /**
     * @description: 方法描述
     * @param {参数类型} 参数名称
     * @param {参数类型} 参数名称
     * @return 没有返回信息写 void / 有返回信息 {返回类型} 描述信息
     */

3. 变量注释

   const userName = '' // 用户姓名
   
   form: {
       contractNum: "", //合同编号
       contractDate: "", //签约日期
       contractTime: "", //合同期限
       contractPath: "", //合同附件
       contractStauts: "", //合同状态
   }

九、工具链推荐

用途	工具
代码格式化	ESLint + Prettier
CSS 预处理	Sass（SCSS语法）
状态管理	Vuex/Pinia（Vue） / Redux（React）
UI 库	elementui/elementplus/antdesign