Guide

Introduction

项目介绍

旨在搭建一套简单易用的前端框架, 便于各项目使用, 方便统一; 以解决网络上各种框架不同的设计思路及使用方式的不一致性而造成项目混乱, 且可以随时根据项目需求调整不同的UI组件.

目前一期项目为innis使用, 使用vuejs进行开发; 后期支持微前端框架时, 再调整为与具体架构无关.

项目暂时命名为 bpui

1
2
3
例如: 
element-ui 中许多组件不传递 v-model值将报错; 
vuetify 会将传入的属性转化为另外的属性而很难深度定制等问题.

框架的设计思路及优先级

  1. 移动优先, 移动端及pc端的使用方式一致.
  2. 框架完整性: 支持大多数常用组件
  3. 易用性: 尽量做到少阅读使用文档时就能够使用. 使用方式向原生组件靠拢.
  4. 兼容性，可扩展性。样式图标独立.
  5. 性能
  6. 支持微信小程序
  7. 微前端

IDE

目前主流的IDE为 vscode

开始工作前按以下进行一些准备工作.

常用插件

建议搜索并安装如下的扩展插件.

可以使用 prettier 进行代码格式化. (ctrl+shift+F 格式化文档, 或 ctrl+K,ctrl+F 格式化选择的代码片段)

code snippet

需要在vscode中设置 javascript, typecript, vue 等文件的 code snippet配置, 以便添加文件版本等内容.

点击 设置->用户代码片段, 分别输入 vue.json, javascript.json, typescript.json 设置如下内容.

  1. 设置自文件头版权信息.

bpheader 是快捷键, 键入后会自动输出body字段中的信息.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"bpheader": {
  "prefix": "bpheader",
  "body": [
    "'use strict';",
    "",
    "/**",
    "* Copyright (c) ${CURRENT_YEAR} Copyright bp All Rights Reserved.",
    "* Author: yourname",
    "* Date: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}",
    "* Desc: $2",
    "*/"
  ],
  "description": "File header"
}

注: vue.json 文件头版权信息注释应该从 /* */ 改为 <!-- -->

可以使用 vue code snippet 这个完整的snippet.

编码规范

需要按照如下的编码规范进行编码:

  1. 优先使用 typescript
  2. 以下按照 .vue 文件按顺序进行代码规范说明
  3. 为保持模块独立性, 尽量不使用 vuex.

文件头版权说明.

1
2
3
4
5
6
7
8
<!--
/**
* Copyright (c) 2019 Copyright bp All Rights Reserved.
* Author: lipengxiang
* Date: 2019-11-01 22:29
* Desc: 
*/
 -->

vue文件使用 <!-- --> 注释, ts/js文件使用 /* */

模板

1
2
3
<template>
  ...
</template>

脚本

优先选择typescript.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<script lang="ts">
  import { Component, Vue, Ref, Watch, Provide, Prop, Emit } from "vue-property-decorator";
  import { State, Mutation } from 'vuex-class';

// 使用 @Component注解使用组件.
@Component({
  components: {
  }
})
export default class extends Vue {

  // 
  // private data.
  privateData: string = '';

  //
  // event 事件.
  @Emit()
  demoEvent(param: string) {}

  //
  // Ref.
  @Ref() demoRef1 : HTMLElement;

  //
  // state 状态.
  @State(state=>state.demo) demo:DEMO_TYPE;
  
  //
  // Prop 属性.
  @Prop({ type: number }) demoProp: number;
  
  //
  // data 数据.
  @Provide() demoData:number = 1;
  
  //
  // computed.
  get demoComputed() { return xxxx; }
  
  //
  // watch.
  @Watch('child')
  onDemoChanged(val: string, oldVal: string) { }
  
  //
  // lifecycle hook.
  constructor() {
    super();
  }
  
  mounted() {
  }

  //
  // methods.

  /**
   * @desc: 方法描述.
   */
  foo1() {
  }
}
</script>

代码归类

相同类型的代码应该放在一起, 例如, @Prop 属性应该都放置在一起, @Emit 事件触发等放置在一起; 自定义方法放置在一起.

不要出现代码随意放置的问题.

使用驼峰命名法.

例如 getName

原则上应该以 动词 在前, 名称 在后; 便于理解.

名称归类.

当类中的方法较多时, 例如超过10个时, 处理同一个子模块的方法应该前缀统一, 并且放置在一起, 方便后续维护.

例如: 同一个页面中处理树形结构逻辑代码统一命名,

tree_onClick,tree_addChildNode, tree_removeNode 等;

同样, 私有变量以及data同样应该使用这个规则;

事件触发类的方法应该以 on 开头

例如, 按钮click事件触发的方法命名为: onClickLogin, onClickOk 等

使用on开头表明是由其他触发引起的.

方法注释.

大多数方法都应该以以下方式进行注释

1
2
3
4
5
6
7
/**
 * @desc: 方法描述.
 * @param p1: 参数1说明.
 * @return 返回值说明.
 */
foo1(p1:string): string {
}

异步方法使用如下方式:

1
2
3
4
5
6
7
/**
 * @desc: 方法描述.
 * @param p1: 参数1说明.
 * @return 返回值说明.
 */
async foo1(p1:string): Promise<string> {
}

样式

使用 scss

1
2
3
<style lang='scss' scoped>
...
</style>

Git使用规范

开发中git的使用必须按照如下规则:

下一步