[Doc] update contribution guide (#1250)

This commit is contained in:
neverland
2018-06-08 14:22:34 +08:00
committed by GitHub
parent 285eb90b32
commit d9721005b2
5 changed files with 157 additions and 45 deletions

42
.github/MARKDOWN.md vendored
View File

@@ -1,42 +0,0 @@
## 组件文档如何编写
#### 文件格式
组件文档采用 markdown 格式编写
#### 文档内的标题规范
文档标题从 `h2`(即 `##` 标题 )开始,每往下一级多加一个 `#` 号;一般到 `h3` (两级标题) 或`h4` (三级标题)即可,不要出现过多的标题层级。
#### 组件描述
大标题下面是对组件的一句话简要描述。
#### 使用指南(可选)
如果组件需要使用指南,放在组件描述下方,另起一个二级标题。
#### 代码演示
另起一个二级标题,示例的结构如下:
```javascript
export default {
data() {
return {
size: 'large'
};
}
};
```
```html
<van-button :size="size">
Large
</van-button>
```
代码演示的几个书写原则:
- 从简单用法开始介绍,不要上来就同时使用一大堆 API会让人觉得难以上手
- 正交性原则一个示例只演示一个或者一类API 的使用方法,如无特殊需求不要在一个示例中同时演示多个 API 混合使用

View File

@@ -1,224 +0,0 @@
# 风格指南
在参与 Vant 开发时,请遵守约定的单文件组件风格指南,指南内容节选自 [Vue 官方风格指南](https://cn.vuejs.org/v2/style-guide)
### 组件数据
组件的 data 必须是一个函数。
```js
// bad
export default {
data: {
foo: 'bar'
}
}
// good
export default {
data () {
return {
foo: 'bar'
}
}
}
```
### 单文件组件文件名称
单文件组件的文件名应该要么始终是单词大写开头 (PascalCase),要么始终是横线连接 (kebab-case)。
```
// bad
mycomponent.vue
myComponent.vue
// good
my-component.vue
MyComponent.vue
```
### 紧密耦合的组件名
和父组件紧密耦合的子组件应该以父组件名作为前缀命名。
```
// bad
components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue
// good
components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue
```
### 自闭合组件
在单文件组件中没有内容的组件应该是自闭合的。
```html
<!-- bad -->
<my-component></my-component>
<!-- good -->
<my-component />
```
### Prop 名大小写
在声明 prop 的时候,其命名应该始终使用 camelCase而在模板中应该始终使用 kebab-case。
```js
// bad
export default {
props: {
'greeting-text': String
}
};
// good
export default {
props: {
greetingText: String
}
}
```
```html
<!-- bad -->
<welcome-message greetingText="hi" />
<!-- good -->
<welcome-message greeting-text="hi" />
```
### Props 换行
多个 Props 的元素应该分多行撰写,每个 Props 一行,闭合标签单起一行。
```html
<!-- bad -->
<my-component foo="a" bar="b" baz="c" />
<!-- good -->
<my-component
foo="a"
bar="b"
baz="c"
/>
```
### 指令缩写
指令缩写,用 `:` 表示 `v-bind:` ,用 `@` 表示 `v-on:`
```html
<!-- bad -->
<input
v-bind:value="value"
v-on:input="onInput"
>
<!-- good -->
<input
:value="value"
@input="onInput"
>
```
### Props 顺序
标签的 Props 应该有统一的顺序,依次为指令、属性和事件。
```html
<my-component
v-if="if"
v-show="show"
v-model="value"
ref="ref"
:key="key"
:text="text"
@input="onInput"
@change="onChange"
/>
```
### 组件选项的顺序
组件选项应该有统一的顺序。
```js
export default {
name: '',
mixins: [],
components: {},
props: {},
data() {},
computed: {},
watch: {},
created() {},
mounted() {},
destroyed() {},
methods: {}
};
```
### 组件选项中的空行
组件选项较多时,建议在属性之间添加空行。
```js
export default {
computed: {
formattedValue() {
// ...
},
styles() {
// ...
}
},
methods: {
onInput() {
// ...
},
onChange() {
// ...
}
}
};
```
### 单文件组件顶级标签的顺序
单文件组件应该总是让顶级标签的顺序保持一致,且标签之间留有空行。
```html
<template>
...
</template>
<script>
/* ... */
</script>
<style>
/* ... */
</style>
```