mand-mobile/site/docs/development.md

---
title: 开发指南
---

### 环境

* node = 8+
* npm = 3+

### 开发流程

#### 创建组件

```shell
$ npm install # 安装依赖

$ npm run create # 新增组件， 根据提示填写组件信息
```
> 需安装[vue-cli](https://cli.vuejs.org/), v3.0+还需安装[@vue/cli-init](https://www.npmjs.com/package/@vue/cli-init)

#### 开发组件
```shell
$ npm run dev # 访问 http://localhost:4000/[组件名称]

$ npm run dev -- --component [COMPONENT NAME] # npm run dev -- --component button, 访问 http://localhost:4000
```

#### 测试组件
```shell
$ npm test # 全部测试

$ npm run test [component name] # 测试单个组件
```
#### feature/bugfix

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

```shell
$ git checkout -b [feature_xxx/fix_xxx] origin/dev

# 开发

$ git add --all
$ git commit -am "描述" # 描述参考【Commit规范】git cz
$ git pull --rebase origin dev

# 解决冲突

$ git push origin [feature_xxx/fix_xxx]

# 提交 PR 至 dev 分支, 指定相应人员 review, 根据反馈进一步修改提交

$ git checkout dev
$ git pull

```
### 代码规范

#### 目录规范
```
├── build              构建脚本
├── config             构建环境配置
├── test               测试配置
├── components         组件代码
    ├── _style         通用样式，图标
    ├── _util          通用工具方法
    ├── button         组件目录
        ├── demo       组件示例
        ├── test       组件单元测试用例
        ├── index.vue  组件核心代码
        ├── ...        组件其他辅助代码或子组件代码
        ├── README.md  组件说明文档
    ├── ...
├── examples           组件库示例
├── site               组件库文档站点
├── ...
```

#### 组件规范

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

##### 组件实现
* 依赖

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

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

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

* 样式

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

注意：通用样式，工具方法的详细使用文档参考Wiki，[Style](https://github.com/didi/mand-mobile/wiki/Style)，[Utils](https://github.com/didi/mand-mobile/wiki/Utils)，[Scroll](https://github.com/didi/mand-mobile/wiki/Scroll)，[FormatValue](https://github.com/didi/mand-mobile/wiki/FormatValue)

##### 组件核心代码

原则上以官方[vue-sytle-guide](https://vuejs.org/v2/style-guide/#Component-instance-options-order-recommended)为标准，常用部分如下：

```html
<template>
  <!-- 根元素以mfe-[组件名]作为类名 -->
  <!-- 多个动态属性需分为多行 -->
  <!-- 统一使用指令缩写 : @ -->
  <div
    class="md-button"
    :class="[type]"
  >
    <!-- 其他组件名称和prop属性使用kebab-case，且避免使用自闭合 -->
    <my-component greeting-text="hi"></my-component>

    <!-- 尽量将v-for/v-if提取到单独template中 -->
    <!-- v-for 必须增加 key -->
    <template v-if="foo">
      Hello A
    <template>
    <template v-else>
      Hello B
    <template>
  </div>
</template>

<script>
import MyComponent from '../my-component'

// options须严格按照如下顺序，其他可参考vue-style-guide
export default {
  // 必须以"md-[组件名]"作为前缀，避免与html元素冲突
  name: 'md-button',

  components: {
    [MyComponent.name]: MyComponent
  },

  // props须以明细方式书写
  // 统一采用事件触发，避免使用props传入回调方法
  props: {
    // js中prop属性需用驼峰
    greetingText: {
      type: String,
      default: 'primary'
    }
  },

  // data必须为函数
  data () {
    return {

    }
  },

  computed: {

  },

  watch: {
  },

  // LiftCircle Hook,
  /*
  beforeCreate
  created
  beforeMount
  mounted
  beforeUpdate
  updated
  activated
  deactivated
  beforeDestroy
  destroyed
  errorCaptured
   */

  methods: {
    // 私有方法以'$_'开头
    $_privateMethod () {

    },

    // 监听事件方法以'$_on'开头，如 $_onButtonClick
    $_onSthEvent (event) {
      // 事件名称无需增加on
      this.$emit('active', 'hello')
    },

    // 对外暴露方法
    publicMethod () {

    }
  }
}
</script>

<style lang="stylus" scoped>
  .md-button
    xxx
</style>
```
##### 组件单元测试代码

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

工具参考文档:

<a href="https://vuejs.org/v2/guide/unit-testing.html" target="_blank">https://vuejs.org/v2/guide/unit-testing.html</a><br>
<a href="https://jestjs.io/docs/getting-started.html" target="_blank">https://jestjs.io</a><br>
<a href="https://vue-test-utils.vuejs.org" target="_blank">https://vue-test-utils.vuejs.org</a>

#### Commit规范

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

```shell
[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