react和vue开发规范文档

2018-05-18 本文已影响0人 lemonzoey

前端通用规范文档,猛戳这里

一.react一般规范

1.基本结构（使用mobx)

├── build 构建脚本目录
│ ├── css 打包生成的css目录
│ ├── js 打包生成的js目录
│ ├──assets 打包生成的静态文件目录
│ ├── index.html 运行本地构建服务器，可以访问构后的页面
├── package.json npm包配置文件，里面定义了项目的npm脚本，依赖包等信息
├── src 项目源码目录
│ ├── index.js 入口js文件
│ ├── index.html 入口html文件
│ ├── routers.js 前端路由文件
│ ├── components 展示性组件目录
│ ├── containers 容器性组件目录
│ ├── assets 资源目录，这里的资源会被wabpack构建
│ │ ├── css 公共样式文件目录
│ │ ├── js 公共js文件目录
│ │ └── img 图片存放目录
│ ├── store 应用级数据（state）
│ │ └── index.js
│ └── utils 全局配置的一些js文件
│ │ ├── request.js 比如axios,Rx等
│── webpack.config.js wabpack配置
│── .gitignore.js 提交代码时候需要配置的忽略提交的代码目录
│── README.md 展示项目基本用法功能的说明性文件

components 展示性组件
里面一般存放ui组件，负责组件的外表，也就是组件如何渲染，具有很强的内聚性。展示性组件不关心渲染时使用的组件属性（Props）是如何获取到的，它只要知道有了这些Props后，组件应该如何渲染就足够了。属性如何获取，是容器性组件负责的事情。当展示性组件状态的变化需要同步到源数据时，需要调用容器性组件中的方法，这个方法一般也是通过Props传递给展示性组件。
containers 容器性组件
负责业务流程逻辑的处理，如发送网络请求，处理请求数据，将处理过的数据传递给子组件的Props使用。同时，容器性组件提供源数据的方法，以Props方式传递给子组件，当子组件的状态变更引起源数据的变化时，子组件通过调用容器性组件提供的方法同步这些变化。

容器性组件和展示性组件可以相互嵌套，一个容器性组件可以包含多个展示性组件和其他的容器性组件；一个展示性组将也可以包含容器性组件和其他的展示性组件。这样的分工，可以使与组件渲染无直接关系的逻辑由容器性组件集中负责，展示性组件只关注组件的渲染逻辑，从而使展示性组件更容易被复用。对于非常简单的页面，一般只要一个容器性组件就足够了；但对于负责页面，则需要多个容器性组件，否则所有的业务逻辑都在一个容器性组件中处理的话，会导致这个组件非常复杂，同时这个组件获取到的源数据，可能需要经过很多层的组件Props的传递，才能到达最终使用的展示性组件。
-assets 静态文件

store 存放全局状态
utils 杂乱的部分可以放这里
index.html 入口hrml文件
index.js/index.tsx 入口js文件，最顶层的部分
routers.js/routers.tsx 路由文件，全部路由存放在这里

2.路由选择
一般情况router有2种：
1：BrowserHistory（官方推荐）
2：HashHistory（带#号）

3.基本规则

1.每个文件只包含一个 React 组件
2.使用 JSX 语法
3.使用class基础写组件，少用React.createClass

//反例
const Listing = React.createClass({
  render() {
    return <div />;
  }
});

//正例
class Listing extends React.Component {
  render() {
    return <div />;
  }
}

4.命名

扩展名: 使用 jsx 作为 React 组件的扩展名
文件名: 文件命名采用帕斯卡命名法，如：ReservationCard.jsx
引用名: 组件引用采用帕斯卡命名法，其实例采用驼峰式命名法。eslint rules: react/jsx-pascal-case

// 反例
const reservationCard = require('./ReservationCard');
// 正例
const ReservationCard = require('./ReservationCard');
// 反例
const ReservationItem = <ReservationCard />;
// 正例
const reservationItem = <ReservationCard />;

组件命名: 使用文件名作为组件名。例如：ReservationCard.jsx 组件的引用名应该是 ReservationCard。然而，对于一个目录的根组件，应该使用 index.jsx 作为文件名，使用目录名作为组件名。

// 反例
const Footer = require('./Footer/Footer.jsx')
// 反例
const Footer = require('./Footer/index.jsx')
// 正例
const Footer = require('./Footer')

5.对齐
对于 JSX 语法，遵循下面的对齐风格

// 反例
  <Foo superLongParam="bar"
       anotherSuperLongParam="baz" />
 // 正例
  <Foo
    superLongParam="bar"
    anotherSuperLongParam="baz"
  />
  // if props fit in one line then keep it on the same line
  <Foo bar="bar" />
  // children get indented normally
  <Foo
    superLongParam="bar"
    anotherSuperLongParam="baz"
  >
    <Spazz />
  </Foo>

6.引号

对于 JSX 使用双引号，对其它所有 JS 属性使用单引号

为什么？因为 JSX 属性不能包含被转移的引号，并且双引号使得如 "don't" 一样的连接词很容易被输入。常规的 HTML 属性也应该使用双引号而不是单引号，JSX 属性反映了这个约定。

 // 反例
  <Foo bar='bar' />
 // 正例
  <Foo bar="bar" />
 // 反例
  <Foo style={{ left: "20px" }} />
 // 正例
  <Foo style={{ left: '20px' }} />

空格

在自闭和标签之前留一个空格

// 反例
<Foo/>
// 反例
<Foo                 />
// 反例
<Foo
 />
// 正例
<Foo />

属性

属性名采用驼峰式命名法

// 反例
<Foo
  UserName="hello"
  phone_number={12345678}
/>

// 正例
<Foo
  userName="hello"
  phoneNumber={12345678}
/>

括号

当组件跨行时，要用括号包裹 JSX 标签。eslint rules: react/wrap-multilines

 // 反例
  render() {
    return <MyComponent className="long body" foo="bar">
             <MyChild />
           </MyComponent>;
  }

 // 正例
  render() {
    return (
      <MyComponent className="long body" foo="bar">
        <MyChild />
      </MyComponent>
    );
  }

  // 正例, when single line
  render() {
    const body = <div>hello</div>;
    return <MyComponent>{body}</MyComponent>;
  }

10.标签

没有子组件的父组件使用自闭和标签。eslint rules: react/self-closing-comp

  // 反例
  <Foo className="stuff"></Foo>

  // 正例
  <Foo className="stuff" />

如果组件有多行属性，闭合标签应写在新的一行上。eslint rules: react/jsx-closing-bracket-location

  // 反例
  <Foo
    bar="bar"
    baz="baz" />

  // 正例
  <Foo
    bar="bar"
    baz="baz"
  />

11.方法

不要对 React 组件的内置方法使用 underscore 前缀

// 反例
React.createClass({
  _onClickSubmit() {
    // do stuff
  }

  // other stuff
});

// 正例
class extends React.Component {
  onClickSubmit() {
    // do stuff
  }

  // other stuff
});

12.顺序

继承 React.Component 的类的方法遵循下面的顺序
1. constructor
2. optional static methods
3. getChildContext
4. componentWillMount
5. componentDidMount
6. componentWillReceiveProps
7. shouldComponentUpdate
8. componentWillUpdate
9. componentDidUpdate
10. componentWillUnmount
11. clickHandlers or eventHandlers like onClickSubmit() or onChangeDescription()
12. getter methods for render like getSelectReason() or getFooterContent()
13. Optional render methods like renderNavigation() or renderProfilePicture()
14. render
如何定义 propTypes，defaultProps，contextTypes等属性，如下所示

import React, { PropTypes } from 'react';

const propTypes = {
  id: PropTypes.number.isRequired,
  url: PropTypes.string.isRequired,
  text: PropTypes.string,
};

const defaultProps = {
  text: 'Hello World',
};

class Link extends React.Component {
  static methodsAreOk() {
    return true;
  }

  render() {
    return <a href={this.props.url} data-id={this.props.id}>{this.props.text}</a>
  }
}

Link.propTypes = propTypes;
Link.defaultProps = defaultProps;

export default Link;

二.vue开发规范

1.结构化规范

├── index.html 入口页面
├── build 构建脚本目录
│ ├── build-server.js 运行本地构建服务器，可以访问构后的页面
│ ├── build.js 生产环境构建脚本
│ ├── dev-client.js 开发服务器热重载脚本，主要用来实现开发阶段的页面自动
│ ├── dev-server.js 运行本地开发服务器
│ ├── utils.js 构建相关工具方法
│ ├── webpack.base.conf.js wabpack基础配置
│ ├── webpack.dev.conf.js wabpack开发环境配置
│ └── webpack.prod.conf.js wabpack生产环境配置
├── config 项目配置
│ ├── dev.env.js 开发环境变量
│ ├── index.js 项目配置文件
│ ├── prod.env.js 生产环境变量
│ └── test.env.js 测试环境变量
├── mock mock数据目录
│ └── hello.js
├── package.json npm包配置文件，里面定义了项目的npm脚本，依赖包等信息
├── src 项目源码目录
│ ├── main.js 入口js文件
│ ├── App.vue 根组件
│ ├── components 公共组件目录
│ │ └── title.vue
│ ├── assets 资源目录，这里的资源会被wabpack构建
│ │ ├── css 公共样式文件目录
│ │ ├── js 公共js文件目录
│ │ └── img 图片存放目录
│ ├── routes 前端路由
│ │ └── index.js
│ ├── store 应用级数据（state）
│ │ └── index.js
│ └── views 页面目录
│ ├── hello.vue
│ └── notfound.vue
├── static 纯静态资源，不会被wabpack构建。
│── .gitignore.js 提交代码时候需要配置的忽略提交的代码目录
│── README.md 展示项目基本用法功能的说明性文件

2.vue文件方法声明顺序

    - components   
    - props    
    - data     
    - created
    - mounted
    - activited
    - update
    - beforeRouteUpdate
    - metods   
    - filter
    - computed
    - watch

3、强制要求

1. 组件名为多个单词

组件名应该始终是多个单词的，根组件 App 除外。

// 反例：
export default {
 name: 'Todo',
 // ...
}
// 正例
export default {
 name: 'TodoItem',
 // ...
}

2. 组件数据

组件的 data 必须是一个函数。

当在组件中使用 data 属性的时候 (除了 new Vue 外的任何地方)，它的值必须是返回一个对象的函数。

// 正例
// In a .vue file
export default {
 data () {
 return {
 foo: 'bar'
 }
 }
}
// 在一个 Vue 的根实例上直接使用对象是可以的，
// 因为只存在一个这样的实例。
new Vue({
 data: {
 foo: 'bar'
 }
})

// 反例
export default {
 data: {
 foo: 'bar'
 }
}

3. Prop定义

Prop 定义应该尽量详细。

在你提交的代码中，prop 的定义应该尽量详细，至少需要指定其类型。

// 正例
props: {
 status: String
}
// 更好的做法！
props: {
 status: {
 type: String,
 required: true,
 validator: function (value) {
 return [
 'syncing',
 'synced',
 'version-conflict',
 'error'
 ].indexOf(value) !== -1
 }
 }
}

// 反例
// 这样做只有开发原型系统时可以接受
props: ['status']

4. 为v-for设置键值

总是用 key 配合 v-for。

在组件上总是必须用 key 配合 v-for，以便维护内部组件及其子树的状态。甚至在元素上维护可预测的行为，比如动画中的对象固化 (object constancy)，也是一种好的做法。

// 正例
<ul>
 <li
 v-for="todo in todos"
 :key="todo.id"
 >
 {{ todo.text }}
 </li>
</ul>

// 反例
<ul>
 <li v-for="todo in todos">
 {{ todo.text }}
 </li>
</ul>

5.避免 v-if 和 v-for 用在一起

永远不要把 v-if 和 v-for 同时用在同一个元素上。

一般我们在两种常见的情况下会倾向于这样做：

为了过滤一个列表中的项目 (比如 v-for="user in users" v-if="user.isActive")。在这种情形下，请将 users 替换为一个计算属性 (比如 activeUsers)，让其返回过滤后的列表。

为了避免渲染本应该被隐藏的列表 (比如v-for="user in users" v-if="shouldShowUsers")。这种情形下，请将 v-if 移动至容器元素上 (比如 ul, ol)。

// 正例
<ul v-if="shouldShowUsers">
 <li
 v-for="user in users"
 :key="user.id"
 >
 {{ user.name }}
 </li>
</ul>

// 反例
<ul>
 <li
 v-for="user in users"
 v-if="shouldShowUsers"
 :key="user.id"
 >
 {{ user.name }}
 </li>
</ul>

4、强烈推荐（增强可读性）

1. 组件文件

只要有能够拼接文件的构建系统，就把每个组件单独分成文件。
当你需要编辑一个组件或查阅一个组件的用法时，可以更快速的找到它。

// 正例
components/
|- TodoList.vue
|- TodoItem.vue

// 反例
Vue.component('TodoList', {
 // ...
})
Vue.component('TodoItem', {
 // ...
})

2. 单文件组件文件的大小写

单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)

// 正例
components/
|- MyComponent.vue
// 反例
components/
|- myComponent.vue
|- mycomponent.vue

3. 基础组件名

应用特定样式和约定的基础组件 (也就是展示类的、无逻辑的或无状态的组件) 应该全部以一个特定的前缀开头，比如 Base、App 或 V。

// 正例
components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue
// 反例
components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue

4. 紧密耦合的组件名

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。

如果一个组件只在某个父组件的场景下有意义，这层关系应该体现在其名字上。因为编辑器通常会按字母顺序组织文件，所以这样做可以把相关联的文件排在一起。

// 正例
components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue
components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue

// 反例
components/
|- SearchSidebar.vue
|- NavigationForSearchSidebar.vue

5. 模板中的组件名大小写
总是 PascalCase 的

// 正例
<!-- 在单文件组件和字符串模板中 -->
<MyComponent/>
// 反例
<!-- 在单文件组件和字符串模板中 -->
<mycomponent/>
<!-- 在单文件组件和字符串模板中 -->
<myComponent/>

6. 完整单词的组件名
组件名应该倾向于完整单词而不是缩写。

// 正例
components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue
// 反例
components/
|- SdSettings.vue
|- UProfOpts.vue

7. 多个特性的元素

多个特性的元素应该分多行撰写，每个特性一行。

// 正例
<img
  src="[https://vuejs.org/images/logo.png](https://vuejs.org/images/logo.png)"
  alt="Vue Logo"
>
<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>

// 反例
<img src="[https://vuejs.org/images/logo.png](https://vuejs.org/images/logo.png)" alt="Vue Logo">
<MyComponent foo="a"  bar="b" baz="c"/>

8. 带引号的特性值
非空 HTML 特性值应该始终带引号 (单引号或双引号，选你 JS 里不用的那个)。
在 HTML 中不带空格的特性值是可以没有引号的，但这样做常常导致带空格的特征值被回避，导致其可读性变差。

// 正例
<AppSidebar :style="{ width: sidebarWidth + 'px' }">

// 反例
<AppSidebar :style={width:sidebarWidth+'px'}>

指令缩写

都用指令缩写 (用 : 表示 v-bind: 和用 @ 表示 v-on:)

// 正例
<input
 @input="onInput"
 @focus="onFocus"
>

// 反例
<input
 v-bind:value="newTodoText"
 :placeholder="newTodoInstructions"
>

5、推荐单文件组件元素的顺序

1. 单文件组件的顶级元素的顺序

单文件组件应该总是让<template> 、<script> 和 <style> 标签的顺序保持一致。且 <style> 要放在最后，因为另外两个标签至少要有一个。

// 正例
<!-- ComponentA.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

6、谨慎使用 (有潜在危险的模式)

1. 没有在 v-if/v-if-else/v-else 中使用 key

如果一组 v-if + v-else 的元素类型相同，最好使用 key (比如两个 <div> 元素)。

// 正例
<div
 v-if="error"
 key="search-status"
>
  错误：{{ error }}
</div>
<div
 v-else
 key="search-results"
>
 {{ results }}
</div>

// 反例
<div v-if="error">
 错误：{{ error }}
</div>
<div v-else>
 {{ results }}
</div>

2. scoped 中的元素选择器
元素选择器应该避免在 scoped 中出现。
在 scoped 样式中，类选择器比元素选择器更好，因为大量使用元素选择器是很慢的。

// 正例
<template>
 <button class="btn btn-close">X</button>
</template>
 
<style scoped>
.btn-close {
 background-color: red;
}
</style>

// 反例
<template>
 <button>X</button>
</template>
 
<style scoped>
button {
 background-color: red;
}
</style>

3. 隐性的父子组件通信

应该优先通过 prop 和事件进行父子组件之间的通信，而不是 this.$parent 或改变 prop。

// 正例
Vue.component('TodoItem', {
 props: {
 todo: {
 type: Object,
 required: true
 }
 },
 template: `
 <input
 :value="todo.text"
 @input="$emit('input', $event.target.value)"
 >
 `
})

// 反例
Vue.component('TodoItem', {
 props: {
 todo: {
 type: Object,
 required: true
 }
 },
 methods: {
 removeTodo () {
 var vm = this
 vm.$parent.todos = vm.$parent.todos.filter(function (todo) {
 return todo.id !== vm.todo.id
 })
 }
 },
 template: `
 <span>
 {{ todo.text }}
 <button @click="removeTodo">
 X
 </button>
 </span>
 `
})