前端开发规范系列【重点学习系列(第一期)】

前端服务

前言：

前端服务一般包含：WEB 、H5、 IOS、 Android、 PC、小程序
未来保证团队里面的开发的整体代码风格一致，流程规范化，我们一定要把前端的规范好好遵守起来，在平时开发过程中就开始培养自己的开发习惯，而不是等项目上线了才开始优化风格，不然你就会相当痛苦，哪怕团队里面只有你自己一个前端。

1 - 文件命名规范

【推荐】html，css，js，lib，images文件均存放至项目的目录中。如果使用相关前端框架，根据框架的文件格式进行合理布局。

【强制】所有文件夹及文件使用英文命名（避免使用中文路径）。

【强制】html文件：入口文件使用index.html。如果有对应的设计组设计原稿，需要将对应的设计稿和html文件命名一致并合理存放。

【强制】css文件命名：后缀.css。通用initial.css，初始化base.css，首页index.css，其他页面按照对应的html命名。

【强制】Js文件命名：英文命名，后缀.js.通用common.js，初始化base.js。 其他页面按照对应的html命名。

2 - HTML规范

【推荐】文档类型声明及编码：统一为html5声明类型。书写时利用IDE实现层次分明的缩进（默认缩进4空格）。

【推荐】非特殊情况下CSS文件放在body部分标签后。非特殊情况下大部分JS文件放在标签尾部（如果需要界面未加载前执行的代码可以放在head标签后）避免行内JS和CSS代码。

【强制】所有编码需要遵循html（XML）标准，标签&属性&属性命名必须由小写字母及下划线数字组成，且所有标签必须闭合，包括br()，hr()等。属性值用双引号。

【推荐】引入JS库文件，文件名须包含库名称及版本号及是否为压缩版，比如jquery-1.4.1.min.js。引入插件，文件名格式为库名称+插件名称，比如jQuery.bootstrap.js。

【推荐】书写页面过程中，请考虑向后扩展性。class&id参见css书写规范.

【推荐】需要为html元素添加自定义属性的时候，首先要考虑下有没有默认的已有的合适标签去设置，如果没有，可以使用须以"data-"为前缀来添加自定义属性，避免使用"data："等其他命名方式。

【推荐】语义化html，如标题根据重要性用h*(同一页面只能有一个h1)，段落标记用p，列表用ul，内联元素中不可嵌套块级元素。

【推荐】尽可能减少div多层级嵌套。

【推荐】书写链接地址时，必须避免重定向，例如：href=“http：//myVue.com/”，即须在URL地址后面加上“/”；

【推荐】在页面中尽量避免使用style属性，即style=“…”。

【推荐】必须为含有描述性表单元素(input，textarea)添加label，如姓名：须写成：姓名：

【推荐】能以背景形式呈现的图片，尽量写入css样式中。

【推荐】重要图片必须加上alt属性。给重要的元素和截断的元素加上title。

【推荐】给区块代码及重要功能(比如循环)加上注释，方便后台添加功能。

【推荐】特殊符号使用：尽可能使用代码替代：比如<(<)&>(>)&空格()&»(»)等等。

3 - JS规范

【强制】文件编码统一为utf-8，书写过程过，每行代码结束必须有分号。原则上所有功能均根据XXX项目需求原生开发，以避免网上down下来的代码造成的代码污染(沉冗代码||与现有代码冲突||…)。
【推荐】库引入：原则上仅引入jQuery库，若需引入第三方库，须与团队其他人员讨论决定。
【强制】变量命名：驼峰式命名.原生JS变量要求是纯英文字母，首字母须小写，如myVue。jQuery变量要求首字符为’_'，其他与原生JS规则相同，如：_myVue。另，要求变量集中声明，避免全局变量.
【强制】类命名：首字母大写，驼峰式命名.如MyVue。
【强制】函数命名：首字母小写驼峰式命名.如myVue()。
【推荐】命名语义化，尽可能利用英文单词或其缩写。
函数常用的方法名：

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 废旧

【推荐】尽量避免使用存在兼容性及消耗资源的方法或属性，比如eval_r()&innerText。

【推荐】后期优化中，JS非注释类中文字符须转换成unicode编码使用，以避免编码错误时乱码显示。

【推荐】代码结构明了，加适量注释.提高函数重用率。

【推荐】注重与html分离，减小reflow，注重浏览器性能.

【推荐】字符串统一使用单引号(‘)，不使用双引号(“)。这在创建 HTML 字符串非常有好处

【推荐】使用字面值创建对象
正例： let user = {};
反例： let user = new Object();

【推荐】永远不要直接使用 undefined 进行变量判断；使用 typeof 和字符串’undefined’对变量进行判断。

【推荐】this 的转换命名：对上下文 this 的引用只能使用’self’来命名

【推荐】慎用console.log，console.log 大量使用会有性能问题，所以在非webpack 项目中谨慎使用log 功能

4 - Vue 项目规范

vue 项目规范以 Vue 官方规范 （https://cn.vuejs.org/v2/style-guide/） 中的 A 规范为基础，在其上面进行项目开发，故所有代码均遵守该规范。
请仔仔细细阅读 Vue 官方规范，切记，此为第一步。

5 - 组件规范

【强制】组件名为多个单词。
组件名应该始终是多个单词组成（大于等于 2），且命名规范为KebabCase格式。
这样做可以避免跟现有的以及未来的 HTML 元素相冲突，因为所有的 HTML 元素名称都是单个单词的。

正例：
export default {
  name: 'TodoItem'
  // ...
};

反例：
export default {
  name: 'Todo',
  // ...
}
export default {
  name: 'todo-item',
  // ...
}

【强制】组件文件名为 pascal-case 格式

正例：
components/
|- my-component.vue

反例：
components/
|- myComponent.vue
|- MyComponent.vue

【推荐】和父组件紧密耦合的子组件应该以父组件名作为前缀命名

正例：
components/
|- todo-list.vue
|- todo-list-item.vue
|- todo-list-item-button.vue
|- user-profile-options.vue （完整单词）

反例：
components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue
|- UProfOpts.vue （使用了缩写）

【推荐】在 Template 模版中使用组件，应使用 PascalCase 模式，并且使用自闭合组件。

正例：
<!-- 在单文件组件、字符串模板和 JSX 中 -->
<MyComponent />
<Row><table :column="data"/></Row>

反例：
<my-component /> <row><table :column="data"/></row>

【强制】组件的 data 必须是一个函数
当在组件中使用 data 属性的时候 (除了 new Vue 外的任何地方)，它的值必须是返回一个对象的函数。 因为如果直接是一个对象的话，子组件之间的属性值会互相影响。

正例：
export default {
  data () {
    return {
      name: 'jack'
    }
  }
}

反例：
export default {
  data: {
    name: 'jack'
  }
}

【推荐】Props 定义应该尽量详细
必须使用 camelCase 驼峰命名
必须指定类型
必须加上注释，表明其含义
必须加上 required 或者 default，两者二选其一
如果有业务需要，必须加上 validator 验证

正例：

props: {
  // 组件状态，用于控制组件的颜色
   status: {
     type: String,
     required: true,
     validator: function (value) {
       return [
         'succ',
         'info',
         'error'
       ].indexOf(value) !== -1
     }
   },
    // 用户级别，用于显示皇冠个数
   userLevel：{
      type: String,
      required: true
   }
}

【推荐】为组件样式设置作用域

正例：
<template>
  <button class="btn btn-close">X</button>
</template>
 
<!-- 使用 `scoped` 特性 -->
<style scoped>
  .btn-close {
    background-color: red;
  }
</style>

反例：
<template>
  <button class="btn btn-close">X</button>
</template>
<!-- 没有使用 `scoped` 特性 -->
<style>
  .btn-close {
    background-color: red;
  }
</style>

【推荐】如果特性元素较多，应该主动换行。

正例：
<MyComponent foo="a" bar="b" baz="c"
    foo="a" bar="b" baz="c"
    foo="a" bar="b" baz="c"
 />
反例：
<MyComponent foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c"/>

【推荐】模板中使用简单的表达式
组件模板应该只包含简单的表达式，复杂的表达式则应该重构为计算属性或方法。复杂表达式会让你的模板变得不那么声明式。我们应该尽量描述应该出现的是什么，而非如何计算那个值。而且计算属性和方法使得代码可以重用。

正例：
<template>
  <p>{{ normalizedFullName }}</p>
</template>
 
// 复杂表达式已经移入一个计算属性
computed: {
  normalizedFullName: function () {
    return this.fullName.split(' ').map(function (word) {
      return word[0].toUpperCase() + word.slice(1)
    }).join(' ')
  }
}

反例：
<template>
  <p>
       {{
          fullName.split(' ').map(function (word) {
             return word[0].toUpperCase() + word.slice(1)
           }).join(' ')
        }}
  </p>
</template>

【强制】指令都使用缩写形式
指令推荐都使用缩写形式，(用 : 表示 v-bind: 、用 @ 表示 v-on: 和用 # 表示 v-slot:)

正例：
<input
  @input="onInput"
  @focus="onFocus"
>
  
反例：
<input
  v-on:input="onInput"
  @focus="onFocus"
>

【推荐】标签顺序保持一致
单文件组件应该总是让标签顺序保持为 `

【强制】必须为 v-for 设置键值 key

【推荐】v-show 与 v-if 选择
如果运行时，需要非常频繁地切换，使用 v-show ；如果在运行时，条件很少改变，使用 v-if。

【推荐】script 标签内部结构顺序
components > props > data > computed > watch > filter > 钩子函数（钩子函数按其执行顺序） > methods

6 - Vue Router 规范

【推荐】页面跳转数据传递使用路由参数
页面跳转，例如 A 页面跳转到 B 页面，需要将 A 页面的数据传递到 B 页面，推荐使用 路由参数进行传参，而不是将需要传递的数据保存 vuex，然后在 B 页面取出 vuex 的数据，因为如果在 B 页面刷新会导致 vuex 数据丢失，导致 B 页面无法正常显示数据。

正例：
let id = ' 123';
this.$router.push({ name: 'userCenter', query: { id: id } });

【推荐】使用路由懒加载（延迟加载）机制

{
  path: '/uploadAttachment',
  name: 'uploadAttachment',
  meta: {
    title: '上传附件'
  },
  component: () => import('@/view/components/uploadAttachment/index.vue')
}

【推荐】path、childrenPoints 命名规范采用kebab-case命名规范（尽量vue文件的目录结构保持一致，因为目录、文件名都是kebab-case，这样很方便找到对应的文件）
【推荐】name 命名规范采用KebabCase命名规范且和component组件名保持一致！（因为要保持keep-alive特性，keep-alive按照component的name进行缓存，所以两者必须高度保持一致）

// 动态加载
export const reload = [
  {
    path: '/reload',
    name: 'reload',
    component: Main,
    meta: {
      title: '动态加载',
      icon: 'icon iconfont'
    },
 
    children: [
      {
        path: '/reload/smart-reload-list',
        name: 'SmartReloadList',
        meta: {
          title: 'SmartReload',
          childrenPoints: [
            {
              title: '查询',
              name: 'smart-reload-search'
            },
            {
              title: '执行reload',
              name: 'smart-reload-update'
            },
            {
              title: '查看执行结果',
              name: 'smart-reload-result'
            }
          ]
        },
        component: () =>
          import('@/views/reload/smart-reload/smart-reload-list.vue')
      }
    ]
  }
];

【推荐】path除了采用kebab-case命名规范以外，必须以 / 开头，即使是children里的path也要以 / 开头。如下示例

7 - Vue 项目目录规范

【推荐】vue 项目中的所有命名一定要与后端命名统一。
比如权限：后端 privilege, 前端无论 router , store, api 等都必须使用 privielege 单词！

【推荐】使用 vue-cli3 来初始化项目，项目名按照上面的命名规范。
目录名按照上面的命名规范，其中 components 组件用大写驼峰，其余除 components 组件目录外的所有目录均使用 kebab-case 命名。

src                               源码目录
|-- api                              所有api接口
|-- assets                           静态资源，images, icons, styles等
|-- components                       公用组件
|-- config                           配置信息
|-- constants                        常量信息，项目所有Enum, 全局常量等
|-- directives                       自定义指令
|-- filters                          过滤器，全局工具
|-- datas                            模拟数据，临时存放
|-- lib                              外部引用的插件存放及修改文件
|-- mock                             模拟接口，临时存放
|-- plugins                          插件，全局使用
|-- router                           路由，统一管理
|-- store                            vuex, 统一管理
|-- themes                           自定义样式主题
|-- views                            视图目录
|   |-- role                             role模块名
|   |-- |-- role-list.vue                    role列表页面
|   |-- |-- role-add.vue                     role新建页面
|   |-- |-- role-update.vue                  role更新页面
|   |-- |-- index.less                      role模块样式
|   |-- |-- components                      role模块通用组件文件夹
|   |-- employee                         employee模块

最后

If builders built buildings the way programmers write programs, then
the first woodpecker that came along would destroy civilization.
（如果建筑师盖房子就像程序员写程序一样，那么，第一只到来的啄木鸟就能毁掉我们的文明）