# 前端开发规范
规范是为了更好的协作与提升用户体验，当然不仅仅枯燥的下文，还有所谓的常识～
更新：xydideo ｜ 2026-03-31
# [置顶]表单规范 - 适配于部门框架
# 🎯 el-form
查询功能区的表单时：正常默认进来要自动搜索(非必填项)，重置之后清空表单同时触发查询。
# el-form 组件要求
- 属性 label-width="140px"；
- 属性 :inline="true"；
- 属性 size="small"
# el-form-item 组件要求
- placeholder 输入框是：请输入，选择器是：请选择；日期选择器是：请选择日期；
- 属性需要有 clearable；
- 必填项需要有 required、 rules；
- 祥哥npm包-字典推荐：vue2-element-dict (opens new window)
单选框、多选框：可以单击它或关联标签来激活/禁用它
<input type="checkbox" id="option1" /> <label for="option1">Option 1</label>
查询表单 注意class的search-form是部门框架全局样式
<el-form
ref="searchFormRef"
:model="searchForm"
:inline="true"
label-width="140px"
size="small"
class="search-form">
<el-form-item label="项目编号" prop="code">
<el-input v-model="searchForm.code" placeholder="请输入" clearable />
</el-form-item>
<el-form-item class="search-button-box">
<el-button type="primary" @click="handleSearch">查询</el-button>
<el-button @click="handleReset">重置</el-button>
</el-form-item>
</el-form>
# 表单校验 !!!（注意：做不到位会被投诉哦～～）
输入类的限制可以使用部门 npm包：fed-directive (opens new window)
- 必填项校验：el-form-item 组件的 required 属性及 rules规则处理；
- 输入类型校验：遇到金额、长度、面积、等只能输入数字的常识输入框，需要输入类型校验数，只能输入数字。
- 时间逻辑关系的约束和校验：开始时间不能晚于结束时间，事件发生的时间不能晚于当前时间等
- 常识类校验...
# 弹窗
- 如果弹窗表单里面有必填项，那要监听弹窗关闭时将弹窗里面的 form 表单进行resetFields，以免校验不通过的信息留存。示例：
// 弹窗关闭，校验清空数据
auditDialogVisible: {
handler(newVal) {
if (!newVal) {
this.$refs.auditFormRef.resetFields()
}
}
}
- 二次确认提示（如：删除...等危险操作）
this.$confirm("此操作将永久删除该角色, 是否继续?", "警告", {
confirmButtonText: "确定",
cancelButtonText: "取消",
type: "error"
}).then(() => {
//具体代码
}).catch(() => {
this.$message({
type: "info",
message: "已取消"
})
})
# [置顶] 表格规范
# 🎯 el-table
# el-table 组件要求
- 表格内容按均分配，重要内容、内容多的表格列宽要宽一些。
- 操作列的默认用el-link
- 表格请求时候需要有v-loading
# 按钮样式同一个项目需统一（在无 ui 规范文件的情况下参考下面）
- primary：搜索、查看、上传、导入、导出、下载、提交
- success：新增
- warning：修改
- danger：删除
<!-- 表格：注意操作用 `el-link` -->
<el-table v-loading="isLoading" :data="tableData">
...
<el-table-column label="操作" align="center" fixed="right" width="180">
<template slot-scope="scope">
<el-link type="danger" @click="handleDelete(scope.row)">删除</el-link>
</template>
</el-table-column>
</el-table>
# 命名规范
# 🔆 前端命名规范
1、项目名称
全部采用小写方式，以横线分隔或以下划线分隔
例：my-project-name
2、目录名称:有复数结构时，要采用复数命名法
例：scripts, styles, images, datas
4、文件名称:js文件名和css文件名:采用中间连字符(*+"-"+*)
例：account-model.js、account-model.scss
5、vue文件名：中间连字符
例如：account-model/index.vue,account-model/components/page.vue
6、vue页面中的 name 属性：中间连字符 （name必填且唯一）
例如：y-title
7、文件夹名称：中间连字符
例如：my-document
8、data变量：小驼峰。例如：dataName:'',根据不同类型添加初始数据声明：
1)对于初始值是字符串类型的字段：userName:''
2)对于初始值是 数组类型 的字段：userList:[]
3)对于初始值是 对象类型 的字段：userInfo:{} 或时间对象：nowTime:new Date()
4)对于初始值是 布尔类型 的字段：isUserEdit:false 或 isUserEdit:true
5)对于初始值是 数字类型 的字段：userNum:0 或没有初始值的时候 userNum:NaN
9、方法命名：小驼峰
例如：myMethod()
10、组件引入：大驼峰
例如：import GCardHeader from '@/components/g-card-header/index.vue'
components: {
GCardHeader,
}
11、样式选择器命名：class和id
1)、类名命名=>单词+’-’+单词，如fine-home。连字符 '-'
2)、Id命名=>单词+’_’+单词，如fine_home。下划线连接
12、图片命名规范
1)、不要用拼音，尽量使用英文
2)、统一使用下划线 nav_right_back.png
3)、如【移动端】需区分倍图 2x 和 3x 的后缀，例如banner_2x.png（不需要@2x, 避免zfb小程序兼容）
4)、图片的名称分为头尾两部分，用下划线隔开，
a、头部表示此图片的大类性质，例如广告，标志，菜单，按钮等
banner：放置在页面顶部的广告，装饰图案等长方形的图片
logo：标志性的图片
button：在页面上位置不固定，并且带有链接的小图片
menu：在页面中某一位置连续出现，性质相同的链接栏目的图片
pic：装饰用的图片
title：不带链接表示标题的图片
b、尾部结合应用具体命名，比如：
banner_sohu.jpg, banner_sina.jpg, title_news.jpg
# 1.组件命名规范
- 名称不能重复 (强制)
- 名称要有意义,做到见名知意 (强制)
- 不能使用拼音命名 (强制)
# 2.data 变量命名规范
data 属性名应该尽量能够做到见名知意，一般来说需要突出两到三个重点：
- 这个变量是关于什么业务行为的？
- 这个变量是关于什么组件的？
- 这个变量是关于组件什么特性的？
- 加上变量注释
# 3.方法命名规范
事件方法命名格式 handleXxxxx, 其他方法命名格式 fnXxx，或方法功能含义命名
# 4.路由规范
1、路由命名由两部分组成：模块名+具体功能名。命名：连字符'-'链接，例如：
{
path: "/login-module/login", //登录页，命名：连字符'-'链接
name: "login",
meta: {
needLogin: false,
title: "登录页"
},
component: () => import(/* webpackChunkName: "loginModule" */"@/views/login-module/login/index.vue")
},
//路由嵌套
{
path: "/role-management",
name: "role-management",
component: () => import(/* webpackChunkName: "settingModule" */ "@/views/setting-module/role-manage.vue"),
redirect: "/role-management/set-auth",//该文件夹下默认打开的路由
meta: {
title: "角色管理"
},
children: [{
path: "/role-management/set-auth",
name: "set-auth",
component: () => import(/* webpackChunkName: "settingModule" */ "@/views/setting-module/role-manage/components/set-auth.vue"),
meta: {
title: "角色权限设置"
}
}]
},
2、路由目录
├─src # 源代码
│ ├─router # 存放路由文件
│ │ ├─common
│ │ │ └─index.js # 公共模块路由
│ │ ├─login
│ │ │ └─index.js # 登录模块路由
│ │ └─after-each.js # 路由拦截器：afterEach
│ │ └─before-each.js # 路由拦截器：beforeEach
│ │ └─index.js # 自动注册路由
# 🔆 图片使用规范
- 能用 svg 的尽量 svg 格式，例如 icon
- pc 端基本上使用 1x 图就行
- 移动端以 750px 宽的设计图标准下下载图片，特殊情况再下载 3 倍图
- jpg 与 png 选则 jpg，超过 300k 的图片需要高质量压缩
# SVG 图片展示-使用方法
常用方式：
<img :src="require('@/assets/test.svg')" />
svg-icon 使用 svg-sprite-loader：
<svg-icon icon-class="test" />
# 🔆 接口使用规范
1、调用页面 test.vue，如下：
// 1、引入数据接口
import { commonApi } from "@/api";
export default {
name: "test",
methods:{
getTableData() {
this.loading = true;
//2、Api方法，传入接口参数
commonApi.getListReset(this.pageData.listQuery).then(response => {
this.tableDatas = response.data.items;
this.pageData.total = response.data.total;
// Just to simulate the time of the request
setTimeout(() => {
this.loading = false;
}, 1500);
});
}
}
}
2、接口 Api 方法定义
//定义接口文件 api/modules/common-api.js
import request from "@/utils/request";
const basePath = "/table";
// 获取列表
export function getListReset(params) {
return request({
url: `${basePath}/list2`,
method: "get",
params,
});
}
// 获取二维码
export const getQRCode = function(data) {
return request({
url: `${basePath}/getQRCode`,
method: "post",
data, // 主要这里是 data
});
};
3、汇总在 index.js 中，提供按模块输出接口函数,模块命名：“+Api”，对应 modules 下的模块名称，如下所示：
//接口暴露文件index.js
import * as loginApi from "./modules/login-api";
import * as commonApi from "./modules/common-api";
export { loginApi, commonApi };
4、目录结构
├─src # 源代码
│ ├─api # 存放api接口文件
│ │ ├─modules # 根据业务需求划分模块放置接口文件
│ │ │ └─common-api.js # 公共接口
│ │ │ └─login-api.js # 登录模块接口，’-api‘结尾，对应views下的页面模块命名
│ │ ├─axios.js # axios请求文件，配置统一请求设置和返回拦截
│ │ └─index.js # 向外暴露接口模块
# 🔆 assets资源文件
1、存放图片资源文件，imgs 文件夹下
2、存放数据字典，data 文件夹下
3、根据 views 下的模块划分 imgs 文件夹内部的二级文件夹名称，与页面一一对应。
4、文件目录结构
├─src # 源代码
│ ├─assets # 存放页面静态资源文件
│ │ ├─imgs # 存放图片文件夹
│ │ │ ├─common # 公共图片文件夹
│ │ │ │ └─loading.gif # 加载gif
│ │ │ ├─login # 登录模块图片文件夹，根据大模块划分，存储模块下所有图片
│ │ │ └─logo.png # logo图片
│ │ ├─data # 数据文件
│ │ │ └─common-dict.js # 公用数据字典文件
# 书写规范
# 🔆 样式书写规范
推荐部门 npm包：fed-static (opens new window)
less版本
import "fed-static/styles/fed-style/index.less"
scss版本
import "fed-static/styles/fed-style/index.scss"
uniapp版本; app.vue 中引入样式文件
@import "fed-static/styles/fed-style/uni.scss"
1、组件样式请记住加上 scoped 或者命名空间，避免造成全局的样式污染
2、样式选择器应避免使用元素选择器, 推荐类选择器。划分为：header-*，container-*，footer-*
<style scoped lang="scss" type="text/scss">
.header-box { padding: 20px }
</style>
3、尽量给每个页面，添加一个父类。以“page-”开头，如下所示：
<template>
<div class="page-login"></div>
</template>
其他样式在此父类下编写
.page-login {
padding: 20px
.other-class{
....
}
}
4、少量样式可以写在组件，大量样式需要引入样式文件。
5、全局的样式变量文件和样式文件，存储在styles文件夹中
6、样式文件夹目录
├─src # 源代码
│ ├─styles # 存放页面公用样式文件
│ │ ├─iconfonts # 存放图标
│ │ ├─theme # 页面主题设置，一般用于重置vant-ui或者element-ui组件样式
│ │ │ └─resetui.less # 重置样式文件
│ │ └─animate.scss # 动画
│ │ ├─common.scss # 公用样式
│ │ ├─normalize.scss # 浏览器重置样式文件
│ │ └─common-params.scss # 全局样式变量
# 🔆 业务组件编写规范
根据业务编写的可复用组件，请务必对每个属性、方法添加注释。并且将组件的使用说明编写对应的 readme 文档。
# 🔆 组件文件目录规范
├─src # 源代码
│ ├─components # 存放业务组件
│ │ ├─global # 存放全局注册组件
│ │ │ ├─y-title # 全局注册组件’y-title‘
│ │ │ │ └─index.vue # 组件对应文件
│ │ │ │ └─README.md # 组件使用说明readme
│ │ │ └─y-banner # 全局注册组件’y-banner‘
│ │ ├─y-title # 组件’y-title‘
│ │ │ └─index.vue # 组件对应文件
│ │ │ └─README.md # 组件使用说明readme
│ │ └─index.js # 注册全局组件
- 1、组件文件夹命名 以“y-“开头。例如 y-title
- 2、全局注册放在 global 文件夹下，实现自动注册
# 组件 README 文档编写格式参考
# 动画加载
# 如何使用
this.$Loading.show()
this.$Loading.hide()
# API
| name | 描述 | 参数 |
|---|---|---|
| show | 展示 | duration |
| hide | 关闭 | 无 |
# Options
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| duration | 延迟多少秒自动关闭 当duration为0时不自动关闭 | number | 0 |
### 🔆 `views`页面文件规范
在`views`下添加业务页面，页面 template 中的标签控制长度，当某个模块例如弹窗模块标签行数很长，导致页面可读性低，应控制页面标签长度，独立此模块放在该文件夹下的 components 中。目录如下
```sh
├─src # 源代码
│ ├─views # 存放业务页面文件
│ │ ├─login-module # 根据业务划分页面存放模块
│ │ │ ├─login # 登录页面文件夹
│ │ │ │ └─components # 登录页面可分模块放置的文件
│ │ │ │ │ └─dialog-module.vue # 分割出来的弹窗模块组件
│ │ │ │ └─index.vue # 登录页面文件
│ │ │ └─reset-pwd # 重置密码,文件夹命名：用中间连字符“-”
│ │ │ └─index.vue
│ │ ├─other-module # 其他模块
│ │ │ ├─other # 其他模块页面
│ │ │ │ └─components # 其他模块页面业务模块文件
│ │ │ │ └─index.vue # 其他模块页面
│ │ │ └─reset-page # 其他模块
│ │ │ └─index.vue # 其他模块页面
│ │ │ └─style.scss # 样式文件很长的时候，另存在样式文件中
- 1、文件夹命名:用中间连字符“-”,以’-module‘结尾，划分模块。
- 2、页面划分过长的业务模块存放于 components 文件夹中
- 3、文件内容统一引入存放在 index.vue 中
- 4、样式文件很长的时候，另存在样式文件中
# 🔆 代码注释
- 页面基本信息注释
<!--
* @Description: 首页
* @Version: 0.1
* @Author: chenyt
-->
- 页面方法注释
/**
* @description:初始化
* @param {type}
* @return:
* @author: chenyt
*/
# 提交规范
# 🔆 代码提交规范
# 1、代码提交必须包含提交类别
用于说明 commit 的类别，只允许使用下面 9 个标识：
- feat：新功能
- fix：修复 bug
- docs：撰写文档
- style：代码格式（不影响代码运行的变动）
- refactor：重构（既不是新增功能，也不是修改 bug 的代码变动）
- test：增加测试
- build：工程化
- chore：代码优化或辅助工具的变动
例如：fix：修改登录自动退出的 bug。
# 2、执行 npm run lint
规范 eslint 规则
# 3、提交合并
保证功能完整性，提交到个人开发分支远程后，合并到 develop 分支
# 🔆 代码分支管理统一
1、分支通常可以对应研发流程中不同的部署环境：
- master -> 线上正式分支
- develop -> 测试环境（test）
- feature -> 开发环境，例如：feature/xiaoye
多模块开发不同期上线的开发策略：
2、使用过无用的分支定期清理掉
# 用户体验
若需求方无特殊要求，则按照以下规则。
# 🔆 前端表格规范 - 严格要求
# 颜色值
- UI 没有给出明确色值时，表头背景颜色值: #F0F2F5; 选中或鼠标悬停在某一行时，此行背景颜色值应为: #DEE9F5;
# 表格中数据展示应符合下述要求
- 表头数据 居中 展示
- 同一列文本数据长短不一致的应 居左 展示，例如单位名称、地址;
- 统一列数据长短基本一致的应 居中 展示，例如姓名、性别、日期、审核状态
- 金额、数字内容应 居右 展示，对应表头标题应使用 半角括号 注明单位，例如“金额(元)”
- 金额应保留两位小数点
# 表格交互应符合下述要求
- 表格数据较多时可显示拖动滑块; 宜根据操作需求，提供编辑功能;
- 表格列宽结合实际内容不能全部统一宽度；
- 主动询问了解表格数据量，询问是否需要做分页及其分页策略
# 表格展示
用于查询后的数据展示时，表格的第一列应为序号; 表格中使用多选框和单选框时，设置在序号左侧;
# 表格滚动条
滑动横向滚动条时保留重要字段;如操作区域、表头区域。
# 🔆 前端数据校验规范
# 身份证
采用部门框架 utils 库
- 号码长度验证：身份证长度仅存在 15 位或 18 位两种长度；
- 号码正确性验证：如身份证号为 18 位，可根据本体码与校验码得关系验证身份证号码输入有误；
- 根据 18 位与 15 位身份证号码编码规则及校验码算法，将 15 位身份证号码转换为 18 位身份证号码；
- 校验码为 X：因校验码为 X，实际上有大小写输入不同，请注意兼容或统一。
- 号码真实性：真实姓名和身份证号在公安系统进行匹配真实性。
# 手机号
- 第一位必须为数字 1；
- 第二位不能为 0/1/2；
- 数字长度必须为 11 位，多了少了都不行；
- 必须输入阿拉伯数字，其他数字、字母、汉字和符号均不可输入。
# 登录密码
如没特殊要求，为了方便老年人的同时，尽可能保证账户的安全性，密码长度为 6 到 8 位数字或字母或数字和字母组合，字母不区分大小写。不能输入汉字和各种符号。
# 电子邮箱
- 电子邮件的邮箱地址格式:用户标识符+@+域名；
- @之前必须有内容且只能是字母（大小写）、数字、下划线()、减号（-）、点（.）；
- @和最后一个点（.）之间必须有内容且只能是字母（大小写）、数字、点（.）、减号（-），且两个点不能挨着；
- 最后一个点（.）之后必须有内容且内容只能是字母（大小写）、数字且长度为大于等于 2 个字节，小于等于 6 个字节。
# 金额
- 不能输入中文、特殊符号
- 只能输入一个点（.）
# 🔆 前端表单优化
# 标签
- 密码输入框 增加显示密码功能-右侧小眼睛图标，便于用户看到输入的错误。
# 触发校验
在完成一个字段后进行内联验证，比如当姓名输入框失去焦点后，再进行验证。 不要在输入过程中进行验证，否则用户还未输入完成会一直出现错误。
# 操作按钮
操作按钮通常分为主次按钮，如：提交和取消，保存和取消等。
- 按钮默认位置：左侧为次要线框按钮，右侧为主要色块按钮。
- 表单有清空/重置按钮等回退按钮。
- 查询表单建议重置按钮，清空表单同时触发查询。
# 键盘
请使用与预期输入相匹配的键盘，如手机号使用数字键盘
# 🔆 敏感信息数据脱敏
无特殊要求情况下，按以下标准执行！
# 姓名
姓名三个字的中间隐藏，两个字的名字隐藏。例如：张三 -> 张*
// 姓名脱敏
desensitization(form.name, 'name')
# 手机号脱敏
手机号前三位和后四位不变，中间四位脱敏。例如：17356781234 => 173****1234
// 手机号脱敏
desensitization(form.mobile, 'phone')
# 身份证号\银行卡号\社保卡号
身份证号码只显示前三位和后四位，中间脱敏。
例如：320123199001011234 => 320***********1234
// 手机号脱敏
desensitization(form.card, 'idCard')
# 其他敏感数据脱敏
其他敏感数据脱敏规则请根据业务需求制定。
# 🔆 其他用户体验
# 全局
- 主题配色
- 字体大小有规范
- 模块间距有层次感、模块对齐统一
- 按钮有手势
- 卡片有微交互
- 可点区域不能过小(h5:48px)
- 图片宽高比不变形
- 弹窗和页面不晃动
- 弹窗常见宽度(640、720、800、960px)
- 弹窗高度不要超过
90vh, 可以设置.el-dialog__body的最大高度, 最小高度也不小于260px；
.el-dialog__body {
padding: 16px 24px;
max-height: 64vh; // 最大高度设置
min-height: 260px; // 最小高设置
overflow: auto;
}
dialog_body_height
# 常识类
- 警告(错误) 时有提示
- 提示色有规范，危险用红色，警告用橙色，成功用绿色
- 空数据有缺省图标
- 请求时候有loading，避免用户重复提交
- 开始结束时间有关联性校验
- 危险动作有二次确认
- 使用全局请求方法，避免接口重复请求，推荐祥哥npm包-https://www.npmjs.com/package/vue-axios-optimize
# 中高水平
- 响应式布局
- 微交互动画