超炫之家

前端开发手册(筑基版)

frontend

# 前言

手册的愿景是码出高效，码出质量。

现代软件架构的复杂性需要协同开发完成，如何高效地协同呢？

无规矩不成方圆，无规范难以协同，

比如，制定交通法规表面上是要限制行车权，实际上是保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行驶？

对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。

代码的字里行间流淌的是软件系统的血液，代码质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。

——引自《Java》开发手册。

# 版本

版本号 制定团队 更新日期 备注
1.0.0 超炫 2023-04-28 筑基版

# 一、编程规约

# （一）命名风格

常见的命名规范：

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

  • 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

  • 凡是涉及到文件夹（项目、模块、目录）的命名，统一采用英文小写方式，多词之间用**短横线-**相隔；

    说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义

  • 凡是涉及到文件的命名，统一使用小驼峰命名（camelCase）。

# 1 项目名

  • 【强制】项目名全部采用小写方式，多词之间用**短横线-**相隔。

    格式：公司名-产品线名-客户端

    客户端类型有PC端（pc）、APP端（app）、VUE2（vue）、VUE3（vue3）、小程序（applet）、安卓（android）、IOS（ios）等

    示例：huawei-crm-pc

# 2 模块名（业务线）

  • 【强制】业务功能模块命名，与一级菜单保持一致；全部采用小写方式，多词之间用**短横线-**相隔。

    示例：system、monotor、process

# 3 目录名（子业务线）

  • 【强制】子业务目录命名，与二级菜单保持一致；全部采用小写方式，多词之间用**短横线-**相隔。

    示例：plan-decl、plan-exam

# 4 文件名（页面）

统一使用百度翻译进行变量命名

1）列表页面

  • 【强制】多个单词，统一以下划线分隔；

  • 【强制】若为单列表页面，列表页面命名为index.vue；

  • 若有多个列表页面（申请、审核），依次命名为decl、exam等简写或英文全称。

2）子页面

注意：相同业务/功能的各项命名，要保持一致

  • 【强制】多个单词，统一以下划线分隔；
  • 添加修改页面，命名为add_update.vue；
  • 查看页面，命名为search.vue；
  • 申请页面，命名为apply.vue。

3）JS、CSS文件名

  • 全部采用小写方式， 优先选择单个单词命名，多个单词之间用**短横线-**相隔。

4） Vue组件名

  • 文件扩展名为 .vue 的单文件组件，统一以大驼峰式命名法方式。

# 5 常量

  • 【强制】常量使用全大写字母来命名；多词之间用**下划线_**相隔；并使用const关键字声明。

# 6 变量、函数、对象属性

  • 【强制】使用小驼峰命名法来命名变量、函数和对象属性；

  • 使用语义化的命名，使代码易于理解和维护。

    示例：myVariable、handleClick

# 7 规约

我们单纯的遵循每个语言的约定，在JavaScript中更自然的是小驼峰式命名法（camelCase），而在HTML中则是短横线（kebab-case）。

# （二）页面排版

# 1 缩进

  • 【强制】统一使用2个空格进行缩进，而不是制表符；

# 2 换行

  • 【强制】使用编辑器自带的格式化功能进行排版，例HBuilder的重排代码格式快捷键为Ctrl+K；
  • 【强制】if / else 不省略花括号；
  • 声明变量时,一个变量单独一行,便于注释说明与阅读；
  • 不要出现多余的空行。

# 3 空格

  • 【强制】使用运算逻辑符+, -, *, /, =时逻辑符前后需要空格；
  • 在逗号后面使用空格，逗号前面不加空格；
  • 方法形参括号后加空格。

# （三）代码注释

添加注释，要注重可读性，以及便于后续维护。

如无必要，勿增注释；如有必要，尽量详尽。

  • 【强制】重要的内容再添加注释，函数的注释要说明入参；
  • 【强制】确定不用的代码，不要注释，直接删除。（有Git版本，暂时不用的也放心大胆的删）
    • 删除未引用的页面；
    • 删除未使用的变量和函数。

# （四）控制台输出

# 1 无效LOG

【强制】页面F12-控制台（console），不要出现无意义log输出。

# 2 报错ERR

【强制】页面F12-控制台（console），出现报红出错要及时解决，未解决不要提交代码。

# （五）标点符号

# 1 分号

【推荐】JS模块中，句末结尾不添加 ;符号。

# 2 单引号

【推荐】字符串变量全部使用单引号,不使用双引号。

# 二、HTML标签

# （一）标签命名规范

  • 【强制】标签引用一律使用小写，多词之间用**短横线-**相隔。

# 三、JS规范

# （一）import引入归类

代码中的变量、函数、组件引入等，要按照一定的顺序进行排序，增加代码的可读性；

  • 【强制】import引入需进行归类区分：

    1. API接口
    2. 组件
    3. 工具类(.js)
    4. 其他

示例：

<script>
  /* 1、API接口 */  
  import { getDictData } from '@/api/common'

  /* 2、组件 */
  import addUpdate from './components/addUpdate.vue'
  import detail from './components/detail.vue'

  /* 3、工具 */
  import * as common from '@/utils/base/common'
    
  ...
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13

# （二）逻辑判断

  • 【强制】优先使用严格相等运算符（===）代替相等运算符（==）。

# （三）错误处理

  • 在可能出现错误的地方使用异常处理机制（try...catch）进行错误处理。

# （四）对象和数组

使用字面量语法创建对象和数组，并使用换行和缩进对其格式化。

对象定义的规则包括将左花括号与类名放在同一行，冒号与属性值间有个空格，字符串使用双引号，数字不需要，最后一个属性-值对后面不要添加逗号，将右花括号独立放在一行，并以分号作为结束符号。

let arr = [1, 2, 4]; //字面量语法
let obj = {
    a: 1,
    b: "zifu",
    c: []
};
1
2
3
4
5
6

# 四、CSS规范

# （一）CSS命名规范

  • 【强制】使用小写字母和短横线-连接单词，尽量不缩写，除非一看就明白的单词；

  • 使用有意义的类名和ID；

    示例：

    .my-table-class {}

#my-btn-id {}
    1
    2
    3

  • 以下是一些常用的CSS命名规则：

    • 头：header
    • 内容：content/container
    • 尾：footer
    • 导航：nav
    • 侧栏：sidebar
    • 栏目：column
    • 左右中：left right center
    • 登录：login
    • 标志：logo
    • 广告：banner
    • 页面主体：main
    • 热点：hot
    • 新闻：news
    • 下载：download
    • 子导航：subnav
    • 菜单：menu
    • 子菜单：submenu
    • 搜索：search
    • 友情链接：friendlink
    • 版权：copyright
    • 内容：content
    • 标签：tags
    • 文章列表：list
    • 提示信息：msg
    • 小技巧：tips
    • 栏目标题：title
    • 加入：joinus
    • 指南：guild
    • 服务：service
    • 注册：regsiter
    • 状态：status
    • 投票：vote
    • 合作伙伴：partner

# （二）书写顺序

按照一定的顺序来书写CSS可以提高代码的可读性。一般的顺序如下：

  • 位置属性（position, top, right, z-index, display, float）等；
  • 【强制】大小（width, height, padding, margin）等；
  • 文字系列（font, line-height, letter-spacing, color- text-align）等；
  • 背景（background, border）等；
  • 其他（animation, transition）等。

# （三）使用简写属性

使用CSS的简写属性可以减少代码量并提高可读性。

  • 使用 margin替代 margin-top、 margin-right等。

    示例：

    .my-class {
    margin: 10px 20px 30px 20px;
}
    1
    2
    3

# （四）鼠标事件

# 1 鼠标聚焦

  • 【强制】按钮、卡片等可点击操作功能，鼠标聚焦显示小手样式；

    cursor: pointer;
    1

# （五）使用CSS预处理器

使用Sass、Less等CSS预处理器来简化CSS的编写和维护。

# 五、页面编码规范

# （一）全局

# 1 名词解释

名词 描述
登录页 系统登录页面
导航页 系统登录之后，跳转的第一个页面，用户导航便捷操作。（非必需）
首页 系统登录之后，跳转的第一个页面。
头部栏 在系统的最顶部区域，一般左侧包含系统图标、名词，右侧有一些操作按钮及下拉菜单等。
菜单栏 一般在左侧侧边栏为菜单。
列表页面 包含搜索栏、表格数据以及分页栏。
树形列表页面 表格数据为树形结构的列表页面。
搜索栏 一般在列表页面的头部区域，包含搜索项以及一些操作按钮。
弹出框页面 在列表页面，已弹出框形式展示的页面。

# 2 弹出框页面布局

弹出框页面全局统一为：上中下三栏。

  • 标题栏
  • 内容区
  • 底部按钮栏

# 3 排序规约

  • XX编码（编号）在前，XX名称在后；
  • 部门、人、日期；

# （二）列表页面

# 1 表格列宽度

  • 【强制】列表页面展示栏，能确定数据长度不变的项，宽度不要让出现换行或展示不全。

  • 【推荐】常用列推荐宽度。

    表格列类型 推荐宽度（px）
    复选框 55
    序号 55
    登录账户 100
    姓名 80
    部门 110
    IP地址 120
    手机号码 100
    日期 100
    日期+时间 180
    状态 90

    以上为推荐宽度，根据实际业务再进行微调。

# 2 搜索栏按钮设置

搜索栏的按钮全部带框，带icon，颜色为蓝色。

  1. “查询”按钮样式如图；

  2. “重置”按钮样式如图，无颜色；

  3. “新增”按钮样式如图；

  4. “导出”按钮样式如图；

【特殊】

  1. 非流程业务列表页面，需要添加数据， 按钮改为“新增”；

  2. 流程业务列表页面，需要添加数据，按钮改为“申请”；

# 3 列表按钮设置

列表中的无框无背景无icon，用|分割开；颜色：除了删除/报废等删除性质的操作为红色，其他均为蓝色。

  1. “ 修改”按钮样式如图，蓝色，无框无背景无icon；

  2. “删除”按钮样式如图，红色，无框无背景无icon；

【特殊】

  1. 表格按钮若超过三个，可选择文字按钮“更多”进行隐藏；

# 4 列表数据加载

调用后端接口获取列表数据时，在列表中需设定（v-loading）样式，明确告知用户此列表数据正在加载中。

# （三）添加/修改页面

# 1 弹出框按钮设置

新增/修改页面的按钮文字为保存、关闭；

  1. “保存”按钮样式如图，无icon，蓝色；

  2. “关闭”按钮样式如图，无ion，无颜色；

【特殊】

  1. 非流程系统弹窗， 按钮改为 -- 保存，关闭 ；

  2. 流程系统弹窗：

    a、若列表页面有“申报”按钮，则弹出框里面的按钮改为保存、关闭 ；

    b、若列表页面没有“申报”按钮，弹出框保存之后就直接让下一个操作人审核了，则弹出框里面的按钮改为提交、关闭 ；

# 2 表单验证

  • form表单中所列内容，按照API中备注信息，添加校验规则；
  1. 非空校验；
  2. 字符长度校验；
  3. 数值范围校验；
  4. 手机号、身份证号、邮箱等特殊校验；
  5. 唯一性校验（需后端提供接口）；

# 3 提交数据加载动效

  • 调用后端接口进行保存/提交数据时，要使得整体页面设定（loading）加载指定，明确告知用户此数据正在提交中，同时也防止用户重复提交，或进行其他操作。

# （四）查看页面

# 六、VUE2规范

# （一）命名规范

# 1 name

  • 页面名应该始终是多个单词，统一以大驼峰式命名法方式命名。

    示例：

    export default {
  name: 'ToDoList',
 // ...
}
    1
    2
    3
    4

# 2 prop

  • 在声明prop时，应该以小驼峰式命名法方式命名。

    示例：

    export default {
  props: ['sonList', 'pageType'],
 // ...
}
    1
    2
    3
    4

# 3 router

  • Vue Router Path命名采用**短横线-**格式。

    示例：

    {
  path: '/user-info', // 能解析成 user info
  name: 'UserInfo',
  component: UserInfo,
  // ...
}
    1
    2
    3
    4
    5
    6

# 4 method

  • 使用驼峰命名法来命名方法名；

  • 统一使用动词或者动词+名词形式。

    动词 含义 返回值
    can 判断是否可执行某个动作 (权 ) 函数返回一个布尔值。true：可执行；false：不可执行；
    has 判断是否含有某个值 函数返回一个布尔值。true：含有此值；false：不含有此值；
    is 判断是否为某个值 函数返回一个布尔值。true：为某个值；false：不为某个值；
    get 获取某个值 函数返回一个非布尔值
    set 设置某个值 无返回值、返回是否设置成功或者返回链式对象

# （二）代码规范

# 1 v-for

  • 在组件上必须用key搭配v-for，以便维护内部组件及其子树的状态；

  • v-if和v-for互斥，永远不要把v-if和v-for同时用在同一个元素上。

# 2 指令简写

  • 用 : 表示v-bind；
  • 用 @ 表示v-on；
  • 用 # 表示v-slot。

# （三）组件

所有子页面，全部要拆离为子组件

  • 【强制】若只在当前目录使用，子组件放置在当前目录下的components子目录（./components/）；
  • 【强制】若为局部通用组件，放置在模块下的common目录下（@/views/模块名/common/）；
  • 【强制】若为全局组件，提取封装放置在components组件目录下（@/components/）。

VUE