229 lines
6.4 KiB
Markdown
229 lines
6.4 KiB
Markdown
---
|
||
title: Development Guide
|
||
---
|
||
|
||
### Environment
|
||
|
||
* node = 8+
|
||
* npm = 3+
|
||
|
||
### Development Process
|
||
|
||
#### Create Component
|
||
|
||
```shell
|
||
$ npm install # Install dependencies
|
||
|
||
$ npm run create # Create a new component, fill in information according to the prompts
|
||
```
|
||
|
||
> [vue-cli](https://cli.vuejs.org/) needs to be installed. v3.0 also requires [@vue/cli-init](https://www.npmjs.com/package/@vue/cli -init)
|
||
|
||
#### Develop Component
|
||
```shell
|
||
$ npm run dev # Visit http://localhost:4000/[COMPONENT NAME]
|
||
|
||
$ npm run dev -- --component [COMPONENT NAME] # npm run dev -- --component button, visit http://localhost:4000
|
||
```
|
||
|
||
#### Test Component
|
||
```shell
|
||
$ npm test # All tests
|
||
|
||
$ npm run test [component name] # Test a single component
|
||
```
|
||
#### feature/bugfix
|
||
New major version development will be carried out in the unified development branch. Other individual components will follow the following process to add new functionalities or repair problems.
|
||
|
||
```shell
|
||
$ git checkout -b [feature_xxx/fix_xxx] origin/dev
|
||
|
||
# Development
|
||
|
||
$ git add --all
|
||
$ git commit -am "describe" # refer to [Commit Specification] git cz
|
||
$ git pull --rebase origin dev
|
||
|
||
# Conflicts resolution
|
||
|
||
$ git push origin [feature_xxx/fix_xxx]
|
||
|
||
# Submit pull request to dev, specify the corresponding person review, and submit further modifications based on feedback
|
||
|
||
$ git checkout dev
|
||
$ git pull
|
||
|
||
```
|
||
### Code Specification
|
||
|
||
#### Directory Specification
|
||
```
|
||
├── build Build scripts
|
||
├── config Build environment configuration
|
||
├── test Test configuration
|
||
├── components Components code
|
||
├── _style Utility style, icons
|
||
├── _util Utility methods
|
||
├── button Component directory
|
||
├── demo Component demo
|
||
├── test Component unit test cases
|
||
├── index.vue Components core code
|
||
├── ... Component other auxiliary code or sub-component code
|
||
├── README.md Component documentation
|
||
├── ...
|
||
├── examples Mand Mobile Examples
|
||
├── site Mand Mobile Doc Site
|
||
```
|
||
|
||
#### Component Specification
|
||
|
||
##### Component Naming
|
||
* Lower-case letters for component name(kebab-case), which is splited with `-`, such as `image-reader`.
|
||
* Accurately express the component functionality and avoid over-simplification.
|
||
|
||
##### Component Implementation
|
||
* Dependencies
|
||
|
||
New external dependencies need to be decided after discussions with the core developers. Try to choose relatively well-known open-source components, and avoid excessively large size.
|
||
|
||
* Imports
|
||
|
||
Use a relative path inside the component, avoid using `alias`, such as `import { extand } from '../util'`.
|
||
|
||
* Utilities
|
||
|
||
Common logic and styles use `_style/*`, `_util/*`, to avoid common logic or style redundancy inside the component code [Need a discussion when adding new members]
|
||
|
||
* Styles
|
||
|
||
Use `stylus`; choose `px` as unit; and all icons use built-in svg icons, see component `Icon` for details.
|
||
|
||
Note: Detailed usage of utility styles and methods please refer to 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)
|
||
|
||
##### Component Core Code
|
||
|
||
In principle, the official standard is [vue-sytle-guide](https://vuejs.org/v2/style-guide/#Component-instance-options-order-recommended), and the common parts are as follows:
|
||
|
||
```html
|
||
<template>
|
||
<!-- Root element with mfe-[COMPONENT NAME] as the class name -->
|
||
<!-- Multiple dynamic attributes need to be divided into multiple lines -->
|
||
<!-- Use abbreviated directives: @ -->
|
||
<div
|
||
class="md-button"
|
||
:class="[type]"
|
||
>
|
||
<!-- Use kebab-case for other component names and prop attributes, and avoid using self-closing -->
|
||
<my-component greeting-text="hi"></my-component>
|
||
|
||
<!-- Try to extract v-for/v-if into a separate template -->
|
||
<!-- add v-for with a key -->
|
||
<template v-if="foo">
|
||
Hello A
|
||
<template>
|
||
<template v-else>
|
||
Hello B
|
||
<template>
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
import MyComponent from '../my-component'
|
||
|
||
// Options must be strictly in the following order, others may refer to vue-style-guide
|
||
export default {
|
||
// Must be prefixed with "md-[component name]" to avoid conflicts with html elements
|
||
name: 'md-button',
|
||
|
||
components: {
|
||
[MyComponent.name]: MyComponent
|
||
},
|
||
|
||
// Prop must be written in detail
|
||
// Use event triggers to avoid using props incoming callback methods
|
||
props: {
|
||
// Prop names should always use camelCase in Javascript
|
||
greetingText: {
|
||
type: String,
|
||
default: 'primary'
|
||
}
|
||
},
|
||
|
||
// Data must be a function
|
||
data () {
|
||
return {
|
||
|
||
}
|
||
},
|
||
|
||
computed: {
|
||
|
||
},
|
||
|
||
watch: {
|
||
},
|
||
|
||
// LiftCircle Hook,
|
||
/*
|
||
beforeCreate
|
||
created
|
||
beforeMount
|
||
mounted
|
||
beforeUpdate
|
||
updated
|
||
activated
|
||
deactivated
|
||
beforeDestroy
|
||
destroyed
|
||
errorCaptured
|
||
*/
|
||
|
||
methods: {
|
||
// Private method name starts with '$_'
|
||
$_privateMethod () {
|
||
|
||
},
|
||
|
||
// Listener name starts with '$_on'，such as $_onButtonClick
|
||
$_onSthEvent (event) {
|
||
// Event name without 'on'
|
||
this.$emit('active', 'hello')
|
||
},
|
||
|
||
// Public method
|
||
publicMethod () {
|
||
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
|
||
<style lang="stylus" scoped>
|
||
.md-button
|
||
xxx
|
||
</style>
|
||
```
|
||
##### Component Unit Test Code
|
||
|
||
Use `Jest` + `vue-test-utils`, and the coverage of each indicator should be greater than `50%`.
|
||
|
||
Reference Documents:
|
||
|
||
<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 Specification
|
||
|
||
Commit should conform to the following rules. It is recommended to use the tool `comitzen`(`git cz`) instead of `git commit`:
|
||
|
||
```shell
|
||
[TYPE](SCOPE):DESCRIPTION#[ISSUE] # such as feat(button):add type 'ghost' for form usage #1234
|
||
```
|
||
|
||
* [Required] TYPE: Type description, includes `feat`，`fix`，`doc`，`build`，`example`
|
||
* [Optional] SCOPE: Affected components, such as `button`, generally used for 'feat,fix'
|
||
* [Required] DESCRIPTION: A brief description of the content, try to use English
|
||
* [Optional] ISSUE: Associated Issue ID, generally used for 'feat,fix'
|
||
|