Vue 开发规范目录及说明

• Vue 开发规范目录及说明
  • 命名规范
    • 普通变量命名规范
    • 常量
    • 组件命名规范
    • views 下的文件命名
  • 结构化规范
    • 目录文件夹及子文件规范
    • vue 文件基本结构
    • 多个特性的元素规范
    • 元素特性的顺序
    • 组件选项顺序
    • 为组件样式设置作用域
  • 注释规范
    • 务必添加注释列表
    • 单行注释
    • 多行注释
  • 模块
  • 指令规范
  • Props 规范
  • 其他
  • CSS规范
    • 通用规范
    • sass 规范
  • 本项目规范
  • epg 问题
  • 附件 统一语义理解和命名,命名规则参考
  • 参考

命名规范

普通变量命名规范

命名方法 ：驼峰命名法

1. 命名必须是跟需求的内容相关的词

   let mySchool = "我的学校"; 
   

2. 命名是复数的时候需要加s

   let names = new Array();
   

常量

命名方法 : 全部大写

1. 命名规范 : 使用大写字母和下划线来组合命名，下划线用以分割单词。

   const MAX_COUNT = 10
   
   const URL = 'https://www.baidu.com/'
   

组件命名规范

1. PascalCase (单词首字母大写命名)是最通用的声明约定

2. kebab-case (短横线分隔命名) 是最通用的使用约定

• 组件名应该始终是多个单词的，根组件 App 除外

• 有意义的名词、简短、具有可读性

• 命名遵循 PascalCase 约定

  • 公用组件以 Abcd (公司名缩写简称) 开头，如（AbcdDatePicker,AbcdTable）

  • 页面内部组件以组件模块名简写为开头，Item 为结尾，如（StaffBenchToChargeItem，StaffBenchAppNotArrItem）

• 使用遵循 kebab-case 约定

• 在页面中使用组件需要前后闭合，并以短线分隔，如

  <abcd-date-picker></abcd-date-picker>，<abcd-table></abcd-table>```
  

• 导入及注册组件时，遵循 PascalCase 约定

• 同时还需要注意：必须符合自定义元素规范: 切勿使用保留字。

  // 注册全局组件
  import Vue from 'vue'
  import TopWrap from '@/components/TopWap/index.vue'
  import ErrorBox from '@/components/ErrorBox/index.vue'
  Vue.component('top-wrap', TopWrap)
  Vue.component('error-box', ErrorBox)
  //页面
  <top-wrap pageTitle="dddd"></top-wrap>
  

views 下的文件命名

- 只有一个文件的情况下不会出现文件夹，而是直接放在 views 目录下面，如 index.vue

- 尽量是名词,且使用驼峰命名法

- 开头的单词就是所属模块名字（workbenchIndex、workbenchList、workbenchEdit）

- 名字至少两个单词（good: workbenchIndex）（bad:workbench）

结构化规范

目录文件夹及子文件规范

• 以下统一管理处均对应相应模块

• 以下全局文件文件均以 index.js 导出，并在 main.js 中导入

• 以下临时文件，在使用后，接口已经有了，发版后清除

     src                               源码目录
  |-- api                              接口，统一管理
  |-- assets                           静态资源，统一管理
  |-- components                       公用组件，全局文件
  |    |   |-- StaffWorkbench           组件模块名
  |    |   |-- |-- index.vue            
  |-- filters                          过滤器，全局工具
  |-- icons                            图标，全局资源
  |-- datas                            模拟数据，临时存放
  |-- lib                              外部引用的插件存放及修改文件
  |-- mock                             模拟接口，临时存放
  |-- router                           路由，统一管理
  |-- store                            vuex, 统一管理
  |-- views                         视图目录
  |   |-- staffWorkbench               视图模块名
  |   |-- |-- staffWorkbench.vue       模块入口页面
  |   |-- |-- indexComponents          模块页面级组件文件夹
  
  

vue 文件基本结构

    
    <template>
        <div>
        <!--必须在div中编写页面-->
        </div>
    </template>
<script>
 export default {
       components : {
             },
        data () {
             return {
             }
         },
        mounted() {
        }，
        methods: {
        }
     }
    </script>
    <!--声明语言，并且添加scoped-->
    <style lang="scss" scoped>
    </style>

多个特性的元素规范

• 多个特性的元素应该分多行撰写，每个特性一行。(增强更易读)

  <!-- bad -->
  <img src="https://vuejs.org/images/logo.png" alt="Vue Logo">
  <my-component foo="a" bar="b" baz="c"></my-component>
  
  <!-- good -->
  <img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo"
  >
  <my-component
  foo="a"
  bar="b"
  baz="c"
  >
  </my-component>
  
  

元素特性的顺序

原生属性放前面，指令放后面

如下所示：

  - class
  - id,ref
  - name
  - data-*
  - src, for, type, href,value,max-length,max,min,pattern
  - title, alt，placeholder
  - aria-*, role
  - required,readonly,disabled
  - is
  - v-for
  - key
  - v-if
  - v-else-if
  - v-else
  - v-show
  - v-cloak
  - v-pre
  - v-once
  - v-model
  - v-bind,:
  - v-on,@
  - v-html
  - v-text

组件选项顺序

如下所示：

  - components
  - props
  - data
  - computed
  - created
  - mounted
  - metods
  - filter
  - watch

为组件样式设置作用域

<template>
<button class="button button-close">X</button>
</template>



<style scoped>
.button {
border: none;
border-radius: 2px;
}

.button-close {
background-color: red;
}
</style>

注释规范

务必添加注释列表

• 公共组件使用说明

• 各组件中重要函数或者类说明

• 复杂的业务逻辑处理说明

• 特殊情况的代码处理说明,对于代码中特殊用途的变量、存在临界值、函数中使用的 hack、使用了某种算法或思路等需要进行注释描述

• 多重 if 判断语句

• 注释块必须以

  /**（至少两个星号）开头**/
  

• 单行注释使用//

单行注释

注释单独一行，不要在代码后的同一行内加注释。例如：

bad

var name =”abc”; // 姓名    

good

// 姓名
var name = “abc”; 

多行注释

组件使用说明，和调用说明

    /**
    * 组件名称
    * @module 组件存放位置
    * @desc 组件描述
    * @author 组件作者
    * @date 2017年12月05日17:22:43
    * @param {Object} [title]    - 参数说明
    * @param {String} [columns] - 参数说明
    * @example 调用示例
    *  <hbTable :title="title" :columns="columns" :tableData="tableData"></hbTable>
    **/

模块

如果模块只有一个输出值，就使用 export default，如果模块有多个输出值，就不使用 export default，export default 与普通的 export 不要同时使用

 // bad
  import * as myObject from './importModule'
 
  // good
  import myObject from './importModule'

如果模块默认输出一个函数，函数名的首字母应该小写。

  function makeStyleGuide() {
  }
 
  export default makeStyleGuide;

如果模块默认输出一个对象，对象名的首字母应该大写

  const StyleGuide = {
    es6: {
    }
  };
 
  export default StyleGuide;

指令规范

指令有缩写一律采用缩写形式

  // bad
  v-bind:class="{'show-left'：true}"
  v-on:click="getListData"
 
  // good
  :class="{'show-left'：true}"
  @click="getListData"

v-for 循环必须加上 key 属性，在整个 for 循环中 key 需要唯一

  <!-- good -->
  <ul>
    <li v-for="todo in todos" :key="todo.id">
      {{ todo.text }}
    </li>
  </ul>
 
  <!-- bad -->
  <ul>
    <li v-for="todo in todos">
      {{ todo.text }}
    </li>
  </ul>

避免 v-if 和 v-for 同时用在一个元素上（性能问题），以下为两种解决方案：

• 将数据替换为一个计算属性，让其返回过滤后的列表

<!-- bad -->
  <ul>
    <li v-for="user in users" v-if="user.isActive" :key="user.id">
      {{ user.name }}
    </li>
  </ul>
 
  <!-- good -->
  <ul>
    <li v-for="user in activeUsers" :key="user.id">
      {{ user.name }}
    </li>
  </ul>
 
  <script>
  computed: {
    activeUsers: function () {
      return this.users.filter(function (user) {
        return user.isActive
      })
    }
  }
  </script>

• 将 v-if 移动至容器元素上 (比如 ul, ol)

 <!-- bad -->
  <ul>
    <li v-for="user in users" v-if="shouldShowUsers" :key="user.id">
      {{ user.name }}
    </li>
  </ul>
 
  <!-- good -->
  <ul v-if="shouldShowUsers">
    <li v-for="user in users" :key="user.id">
      {{ user.name }}
    </li>
  </ul>

Props 规范

prop 的定义应该尽量详细，至少需要指定其类型

// bad 这样做只有开发原型系统时可以接受
props: ['status']
 
// good
props: {
  status: {
    type: String,
    required: true,
    validator: function (value) {
      return [
        'syncing',
        'synced',
        'version-conflict',
        'error'
      ].indexOf(value) !== -1
    }
  }
}

其他

• 避免 this.$parent

• 调试信息 console.log() debugger 使用完及时删除

• 除了三目运算，if,else 等禁止简写

 // bad
  if (true)
      alert(name);
  console.log(name);
 
  // bad
  if (true)
  alert(name);
  console.log(name)
 
  // good
  if (true) {
      alert(name);
  }
  console.log(name);

CSS规范

通用规范

统一使用"-"连字符

省略值为 0 时的单位

 // bad
  padding-bottom: 0px;
  margin: 0em;
 
 // good
  padding-bottom: 0;
  margin: 0;

如果 CSS 可以做到，就不要使用 JS

建议并适当缩写值，提高可读性，特殊情况除外

“建议并适当”是因为缩写总是会包含一系列的值，而有时候我们并不希望设置某一值，反而造成了麻烦，那么这时候你可以不缩写，而是分开写。

当然，在一切可以缩写的情况下，请务必缩写，它最大的好处就是节省了字节，便于维护，并使阅读更加一目了然。

  // bad
  .box{
    border-top-style: none;
    font-family: palatino, georgia, serif;
    font-size: 100%;
    line-height: 1.6;
    padding-bottom: 2em;
    padding-left: 1em;
    padding-right: 1em;
    padding-top: 0;
  }
 
  // good
  .box{
    border-top: 0;
    font: 100%/1.6 palatino, georgia, serif;
    padding: 0 1em 2em;
  }

声明应该按照下表的顺序 左到右，从上到下

  // bad
  .box {
    font-family: 'Arial', sans-serif;
    border: 3px solid #ddd;
    left: 30%;
    position: absolute;
    text-transform: uppercase;
    background-color: #eee;
    right: 30%;
    isplay: block;
    font-size: 1.5rem;
    overflow: hidden;
    padding: 1em;
    margin: 1em;
  }
 
  // good
  .box {
    display: block;
    position: absolute;
    left: 30%;
    right: 30%;
    overflow: hidden;
    margin: 1em;
    padding: 1em;
    background-color: #eee;
    border: 3px solid #ddd;
    font-family: 'Arial', sans-serif;
    font-size: 1.5rem;
    text-transform: uppercase;
  }

元素选择器应该避免在 scoped 中出现

官方文档说明：在 scoped 样式中，类选择器比元素选择器更好，因为大量使用元素选择器是很慢的。
对用页面级组件样式，应该是有作用域的

sass 规范

当使用 Sass 的嵌套功能的时候，重要的是有一个明确的嵌套顺序，以下内容是一个 SCSS 块应具有的顺序。

• 当前选择器的样式属性
• 父级选择器的伪类选择器 (:first-letter, :hover, :active etc)
• 伪类元素 (:before and :after)
• 父级选择器的声明样式 (.selected, .active, .enlarged etc.)
• 用 Sass 的上下文媒体查询
• 子选择器作为最后的部分

.product-teaser {
    // 1. Style attributes
    display: inline-block;
    padding: 1rem;
    background-color: whitesmoke;
    color: grey;
 
    // 2. Pseudo selectors with parent selector
    &:hover {
      color: black;
    }
 
    // 3. Pseudo elements with parent selector
    &:before {
      content: "";
      display: block;
      border-top: 1px solid grey;
    }
 
    &:after {
      content: "";
      display: block;
      border-top: 1px solid grey;
    }
 
    // 4. State classes with parent selector
    &.active {
      background-color: pink;
      color: red;
 
      // 4.2. Pseuso selector in state class selector
      &:hover {
        color: darkred;
      }
    }
 
    // 5. Contextual media queries
    @media screen and (max-width: 640px) {
      display: block;
      font-size: 2em;
    }
 
    // 6. Sub selectors
    > .content > .title {
      font-size: 1.2em;
 
      // 6.5. Contextual media queries in sub selector
      @media screen and (max-width: 640px) {
        letter-spacing: 0.2em;
        text-transform: uppercase;
      }
    }
  }

本项目规范

api

api统一放apis目录下，按模块分一个个文件,格式按以下格式，如（tv.js)

//统一用这个请求类
import request from '@/utils/request'
/**
* @author: glory.xu
* @date: 2020/3/31
* Describe: tv 操作类
*/

//注解功能
export function getItems(query) {
return request({
  url: '/tvlist/list',
  method: 'get',
  params: query
})
}

//注解功能
export function order(data) {
return request({
  url: '/tvlist/order',
  method: 'post',
  data
})
}

调用，引入需要的api

import { getItems, order} from "@/api/tv";

//使用
var pra = { userAccount: userAccount };
    var userJson = JSON.stringify(pra);
    getItems({ userJson: userJson }).then(res => {
//具体业务处理

api请求统一处理

请求处理统一在 utils/requtst.js

用户身份信息相关验证信息统一这里加

service.interceptors.request.use(
  config => {
    if (!config.headers['X-Token']) {
      config.headers['X-Token'] = `${window.localStorage.getItem('token') || ''}`;
      config.headers['X-LoginId'] = `${window.localStorage.getItem('userAccount') || ''}`;

这里在请求到结果时会拦截

service.interceptors.response.use(
  response => {
    const res = response.data
    store.commit('hideLoading');
    if (res.errno === 501) {
      Toast.fail('请登录');
      setTimeout(() => {
        window.location = '#/login/'
      }, 1500)
      return Promise.reject('error1')
    } else if (res.errno === 507) {
      Toast.fail('请绑定手机号')
      setTimeout(() => {

路由配置

都放在roter/index.js,按模块参数备注好

全局CSS

多页面使用的样式统一放 assets/styles/app.scss

本地存储

用户信息放Cookie，尽量少放

epg 问题

https://www.kancloud.cn/koala-gc/iptv-epg/977457

华为机顶盒 需要页面中含有a 元素 才能在window.document.onkeypress 监听到按键事件
不支持Flex 布局
不支持 background:url() 直接定义图片，只能使用background-image:url()
除华为机顶盒外，其他机顶盒视频小窗口均在页面底层，会被页面遮挡因此需设置背景为translate来处理。小窗口播放时需设置背景图播放区为透明框。
华为机顶盒 确定键值为 1 其他均为13
较少机顶盒支持css 动画效果，避免使用css动画
部分机顶盒不支持 iconfont 字体图标，避免使用icon字体，可直接放置png图片替代实现
华为机顶盒position absolute 不支持top 0 left0 right 0 bottom 0 方式全屏居中
路由层级控制在4层以内，否则部分机顶盒 返回路由出错 （在含有iframe 或跳转到非本框架内路由后可能出现该问题，可以使用 history.replaceState 来处理，普通模式下不存在）
大部分机顶盒不支持 audio 标签，因此音频同样使用 MediaPlayer 来实现
尽可能少的使用 cookie 记录，超过记录数量后，可能存在删除较早的cookie
不能使用localStorage
css extrat 不能设置为true

css:{extract:false}

附件 统一语义理解和命名,命名规则参考

函数方法常用的动词:

 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 聚集

分类的命名方法

• 使用单个字母加上"-"为前缀

• 布局（grid）（.g-）；

• 模块（module）（.m-）；

• 元件（unit）（.u-）；

• 功能（function）（.f-）；

• 皮肤（skin）（.s-）；

• 状态（.z-）。

布局（.g-）

模块（.m-）、元件（.u-）

功能（.f-）

皮肤（.s-）

状态（.z-）

参考

https://cn.vuejs.org/v2/style-guide