开发指南

环境

  • node = 8+
  • npm = 3+

开发流程

创建组件

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

需安装vue-cli, v3.0+还需安装@vue/cli-init

开发组件

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

测试组件

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

feature/bugfix

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

  1. $ git checkout -b [feature_xxx/fix_xxx] origin/dev
  2. # 开发
  3. $ git add --all
  4. $ git commit -am "描述" # 描述参考【Commit规范】git cz
  5. $ git pull --rebase origin dev
  6. # 解决冲突
  7. $ git push origin [feature_xxx/fix_xxx]
  8. # 提交 PR 至 dev 分支, 指定相应人员 review, 根据反馈进一步修改提交
  9. $ git checkout dev
  10. $ 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. ├── site 组件库文档站点
  16. ├── ...

组件规范

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

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

  • 引用

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

  • 通用方法

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

  • 样式

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

注意:通用样式,工具方法的详细使用文档参考Wiki,StyleUtilsScrollFormatValue

组件核心代码

原则上以官方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>
  11. <!-- 尽量将v-for/v-if提取到单独template中 -->
  12. <!-- v-for 必须增加 key -->
  13. <template v-if="foo">
  14. Hello A
  15. <template>
  16. <template v-else>
  17. Hello B
  18. <template>
  19. </div>
  20. </template>
  21. <script>
  22. import MyComponent from '../my-component'
  23. // options须严格按照如下顺序,其他可参考vue-style-guide
  24. export default {
  25. // 必须以"md-[组件名]"作为前缀,避免与html元素冲突
  26. name: 'md-button',
  27. components: {
  28. [MyComponent.name]: MyComponent
  29. },
  30. // props须以明细方式书写
  31. // 统一采用事件触发,避免使用props传入回调方法
  32. props: {
  33. // js中prop属性需用驼峰
  34. greetingText: {
  35. type: String,
  36. default: 'primary'
  37. }
  38. },
  39. // data必须为函数
  40. data () {
  41. return {
  42. }
  43. },
  44. computed: {
  45. },
  46. watch: {
  47. },
  48. // LiftCircle Hook,
  49. /*
  50. beforeCreate
  51. created
  52. beforeMount
  53. mounted
  54. beforeUpdate
  55. updated
  56. activated
  57. deactivated
  58. beforeDestroy
  59. destroyed
  60. errorCaptured
  61. */
  62. methods: {
  63. // 私有方法以'$_'开头
  64. $_privateMethod () {
  65. },
  66. // 监听事件方法以'$_on'开头,如 $_onButtonClick
  67. $_onSthEvent (event) {
  68. // 事件名称无需增加on
  69. this.$emit('active', 'hello')
  70. },
  71. // 对外暴露方法
  72. publicMethod () {
  73. }
  74. }
  75. }
  76. </script>
  77. <style lang="stylus" scoped>
  78. .md-button
  79. xxx
  80. </style>
组件单元测试代码

测试工具使用Jest + vue-test-utils, 原则上各项指标覆盖率要大于50%

工具参考文档:

https://vuejs.org/v2/guide/unit-testing.htmlhttps://jestjs.iohttps://vue-test-utils.vuejs.org

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