开发指南

环境

  • node = 6+
  • npm = 3+

开发流程

创建组件

  1. $ npm install # 安装依赖
  3. $ npm run create # 新增组件， 根据提示填写组件信息

开发组件

  1. $ npm run dev # 访问 http://localhost:4000/[组件名称]
  3. $ npm run dev -- --component [COMPONENT NAME] # npm run dev -- --component button, 访问 http://localhost:4000

测试组件

  1. $ npm test # 全部测试
  3. $ npm run test [component name] # 测试单个组件

feature/bugfix

新的大版本开发会在统一的开发分支中进行，其他单个组件增加新功能或问题修复流程如下

  1. $ git checkout -b [feature_xxx/fix_xxx]
  3. # 开发
  5. $ git add --all
  6. $ git commit -am "描述" # 描述参考【Commit规范】git cz
  7. $ git pull --rebase origin master
  9. # 解决冲突
  11. $ git push origin [feature_xxx/fix_xxx]
  13. # 提交 mr, 指定相应人员 review, 根据反馈进一步修改提交
  15. $ git checkout master
  16. $ git pull

代码规范

目录规范

  1. ├── build              构建脚本
  2. ├── config             构建环境配置
  3. ├── test               测试配置
  4. ├── components         组件代码
  5.     ├── _style         通用样式，图标
  6.     ├── _util          通用工具方法
  7.     ├── button         组件目录
  8.         ├── demo       组件示例
  9.         ├── test       组件单元测试用例
  10.         ├── index.vue  组件核心代码
  11.         ├── ...        组件其他辅助代码或子组件代码
  12.         ├── README.md  组件说明文档
  13.     ├── ...
  14. ├── examples           组件库示例
  15. ├── docs               组件库文档
  16. ├── ...

组件规范

组件命名
  • 组件名(kebab-case)使用小写字母，以 - 分割, 例如 image-reader。
  • 准确表达组件UI或功能且避免过于宽泛。
组件实现
  • 依赖

新增外部依赖需要与核心开发成员讨论后决定，尽量选择较为知名开源组件，且避免体积过大。

  • 引用

组件内部使用相对路径引用，避免使用alias。如import { extand } from '../util'。

  • 通用方法

通用逻辑和样式使用_style/, _util/, 避免组件代码内部通用逻辑或样式冗余【新增需讨论】

  • 样式

使用stylus; 单位统一使用px; 所有图标使用内置svg图标, 详情见组件Icon。

注意：通用样式，工具方法的详细使用文档参考Wiki，Style，Utils，Scroll，FormatValue

组件核心代码

原则上以官方vue-sytle-guide为标准，常用部分如下：

  1. <template>
  2.   <!-- 根元素以mfe-[组件名]作为类名 -->
  3.   <!-- 多个动态属性需分为多行 -->
  4.   <!-- 统一使用指令缩写 : @ -->
  5.   <div
  6.     class="md-button"
  7.     :class="[type]"
  8.   >
  9.     <!-- 其他组件名称和prop属性使用kebab-case，且避免使用自闭合 -->
  10.     <my-component greeting-text="hi"></my-component>
  12.     <!-- 尽量将v-for/v-if提取到单独template中 -->
  13.     <!-- v-for 必须增加 key -->
  14.     <template v-if="foo">
  15.       Hello A
  16.     <template>
  17.     <template v-else>
  18.       Hello B
  19.     <template>
  20.   </div>
  21. </template>
  23. <script>
  24. import MyComponent from '../my-component'
  26. // options须严格按照如下顺序，其他可参考vue-style-guide
  27. export default {
  28.   // 必须以"md-[组件名]"作为前缀，避免与html元素冲突
  29.   name: 'md-button',
  31.   components: {
  32.     [MyComponent.name]: MyComponent
  33.   },
  35.   // props须以明细方式书写
  36.   // 统一采用事件触发，避免使用props传入回调方法
  37.   props: {
  38.     // js中prop属性需用驼峰
  39.     greetingText: {
  40.       type: String,
  41.       default: 'primary'
  42.     }
  43.   },
  45.   // data必须为函数
  46.   data () {
  47.     return {
  49.     }
  50.   },
  52.   computed: {
  54.   },
  56.   watch: {
  57.   },
  59.   // LiftCircle Hook,
  60.   /*
  61.   beforeCreate
  62.   created
  63.   beforeMount
  64.   mounted
  65.   beforeUpdate
  66.   updated
  67.   activated
  68.   deactivated
  69.   beforeDestroy
  70.   destroyed
  71.   errorCaptured
  72.    */
  74.   methods: {
  75.     // 私有方法以'$_'开头
  76.     $_privateMethod () {
  78.     },
  80.     // 监听事件方法以'$_on'开头，如 $_onButtonClick
  81.     $_onSthEvent (event) {
  82.       // 事件名称无需增加on
  83.       this.$emit('active', 'hello')
  84.     },
  86.     // 对外暴露方法
  87.     publicMethod () {
  89.     }
  90.   }
  91. }
  92. </script>
  94. <style lang="stylus" scoped>
  95.   .md-button
  96.     xxx
  97. </style>
组件单元测试代码

测试工具使用karma + avoriaz, 原则上各项指标覆盖率要大于50%

工具参考文档:

https://vuejs.org/v2/guide/unit-testing.htmlhttp://karma-runner.github.io/1.0/index.htmlhttps://eddyerburgh.gitbooks.io/avoriaz/content/

Commit规范

commit信息应符合如下规则， 建议使用工具comitzen(git cz)代替git commit

[TYPE](SCOPE):DESCRIPTION#[ISSUE]  # 如 feat(button):add type 'ghost' for form usage #1234
  • 【必填】TYPE: 类型描述。包括feat(功能)，fix(修复)，doc(文档)，build(工程化)，example(示例, 仅用于修改examples/*)
  • 【可选】SCOPE: 影响的组件，比如button。一般用于feat，fix
  • 【必填】DESCRIPTION: 内容简要描述，尽量使用英文
  • 【可选】ISSUE: 改动关联的issue号码。一般用于feat，fix