dolphin · basics 使用文档

概述

vue-dolphin-basics 是基于 vue-cli 4.x 而搭建的一个基础脚手架

兄弟版本

• vue-dolphin-pc

• vue-dolphin-mobile

运行

git clone http://git.dev.cmrh.com/IOCP-FE-OPEN/cli/vue-dolphin-basics.git
cd vue-dolphin-basics
yarn
yarn serve

文件目录结构树

vue-dolphin-basics
├── .browserslistrc
├── .editorconfig
├── .env.development
├── .env.di
├── .env.prd
├── .eslintignore
├── .eslintrc.js
├── README.md
├── babel.config.js
├── package.json
├── public
│   ├── favicon.ico
│   └── index.html
├── src
│   ├── App.vue
│   ├── assets
│   │   ├── js
│   │   │   ├── http.js
│   │   │   ├── lib
│   │   │   ├── request
│   │   │   │   ├── index.js
│   │   │   │   ├── requestOne.js
│   │   │   │   └── requestTwo.js
│   │   │   └── utils.js
│   │   └── style
│   │       ├── color-default.scss
│   │       ├── common.scss
│   │       ├── fs-default.scss
│   │       └── reset.scss
│   ├── components
│   │   ├── PageOne
│   │   │   ├── Bar
│   │   │   │   └── Bar.vue
│   │   │   └── Foo
│   │   │       ├── Foo.vue
│   │   │       └── cake.png
│   │   ├── PageTwo
│   │   └── common
│   │       ├── business
│   │       │   └── ShowList
│   │       │       └── ShowList.vue
│   │       └── pure
│   │           └── Loading
│   │               └── Loading.vue
│   ├── main.js
│   ├── router
│   │   └── index.js
│   ├── store
│   │   ├── index.js
│   │   └── modules
│   │       ├── index.js
│   │       ├── moduleOne
│   │       │   ├── actions.js
│   │       │   ├── mutations.js
│   │       │   └── state.js
│   │       ├── moduleOne.js
│   │       ├── moduleTwo
│   │       │   ├── actions.js
│   │       │   ├── mutations.js
│   │       │   └── state.js
│   │       └── moduleTwo.js
│   └── views
│       ├── PageOne.vue
│       └── PageTwo.vue
├── vue.config.js
└── yarn.lock

规则

页面

页面组件放在 ./src/views/ 文件夹下

示例：

│   └── views
│       ├── PageOne.vue      // 页面一
│       └── PageTwo.vue      // 页面二

子组件

组件放在 ./src/components 文件夹下，该文件夹包含一个 common 文件夹，以及以页面组件命名的文件夹

示例：

│   ├── components
│   │   ├── PageOne          // 与页面一组件命名相同的文件夹，存放仅用于页面一的子组件
│   │   │   ├── Bar
│   │   │   │   └── Bar.vue
│   │   │   └── Foo
│   │   │       ├── Foo.vue
│   │   │       └── cake.png
│   │   ├── PageTwo          // 与页面二组件命名相同的文件夹，存放仅用于页面二的子组件
│   │   └── common           // 公共组件文件夹
│   │       ├── business
│   │       │   └── ShowList
│   │       │       └── ShowList.vue
│   │       └── pure
│   │           └── Loading
│   │               └── Loading.vue

common 类组件

common 类组件放在 common 文件夹下，并分两类：

• business 文件夹存放业务相关的公共组件
• pure 文件夹存放业务无关的公共组件

示例：

│   ├── components
│   │   └── common
│   │       ├── business
│   │       │   └── ShowList  // 业务相关的组件
│   │       │       └── ShowList.vue
│   │       └── pure
│   │           └── Loading   // 业务无关的组件，可直接提供给其他项目使用
│   │               └── Loading.vue

页面子组件

仅用于某个页面的子组件，放在以该页面命名的相同的文件夹下，且每个组件都是一个文件夹，里面存放组件及组件使用使用到的资源

示例：

│   ├── components
│   │   ├── PageOne           // 与页面一组件命名相同的文件夹
│   │   │   ├── Bar           // 仅用于页面一的子组件，每个组件都是一个文件夹
│   │   │   │   └── Bar.vue   // 具体的子组件
│   │   │   └── Foo           // 仅用于页面一的子组件，每个组件都是一个文件夹
│   │   │       ├── Foo.vue   // 具体的子组件
│   │   │       └── cake.png  // 组件 Foo.vue 用到的资源文件，放在同级目录下
│   │   ├── PageTwo

js 相关文件

js 相关的文件放在 assets/js/ 文件夹下，包括：

• lib 文件夹，用于存放第三方的 js 文件或库
• request 文件夹，用于存放业务相关的 http 请求的封装代码
• http.js 使用了 axios 做了请求封装
• utils.js 工具库

目录结构：

│   ├── assets
│   │   ├── js
│   │   │   ├── http.js
│   │   │   ├── lib
│   │   │   ├── request
│   │   │   │   ├── index.js
│   │   │   │   ├── requestOne.js
│   │   │   │   └── requestTwo.js
│   │   │   └── utils.js

这里着重说明下 request 的分模块

request

文件夹目录结构示例：

│   │   │   ├── request
│   │   │   │   ├── index.js
│   │   │   │   ├── requestOne.js // 请求封装分文件一
│   │   │   │   └── requestTwo.js // 请求封装分文件二

模块划分依据：根据具体业务场景和不同的微服务做的模块划分

style 相关文件

style 相关的文件放在 assets/style/ 文件夹下，这些文件为全局的 scss 样式，包括 scss 变量、类、方法等，具体文件为：

• color-default.scss 全局的颜色变量
• fs-default.scss 全局的字体大小变量
• common.scss 全局的公共类
• reset.scss 全局的重置样式

目录结构：

│   │   └── style
│   │       ├── color-default.scss
│   │       ├── common.scss
│   │       ├── fs-default.scss
│   │       └── reset.scss

全局共享，需做以下配置：

// vue.config.js
...
  css: {
    loaderOptions: {
      scss: {
        prependData: `
          @import '~@/assets/style/color-default.scss';
          @import '~@/assets/style/fs-default.scss';
          @import '~@/assets/style/reset.scss';
          @import '~@/assets/style/common.scss';
        `
      }
    }
  }

示例

以 color-default.scss 为例，说明一下具体用法

// color-default.scss

$color-1: #CCCCFF;
$color-2: #FFCCCC;
$color-3: #FFFF99;

在子组件 Bar.vue 中使用变量：

// Bar.vue

<style lang="scss" scoped>
.bar {
	...
  background-color: $color-2;
}
</style>

更多示例请查看脚手架的示例代码

vuex

store 的目录文件也是分模块分文件的，示例如下：

│   ├── store
│   │   ├── index.js
│   │   └── modules
│   │       ├── index.js
│   │       ├── moduleOne
│   │       │   ├── actions.js
│   │       │   ├── mutations.js
│   │       │   └── state.js
│   │       ├── moduleOne.js
│   │       ├── moduleTwo
│   │       │   ├── actions.js
│   │       │   ├── mutations.js
│   │       │   └── state.js
│   │       └── moduleTwo.js

store 下的 modules 文件夹，存放不同的 vuex 模块，比如 moduleOne 模块，对应必须有：

• moduleOne.js 文件
• moduleOne 文件夹
  • action.js
  • mutations.js
  • state.js

如何使用

具体的使用，请参考脚手架的示例代码 PageOne.vue，该示例代码演示了最常用的功能，可运行起来查看效果

环境变量

环境一般有三种：本地开发环境、DI 环境、PRD 环境

对应的文件：

├── .env.development
├── .env.di
├── .env.prd

在打不同的环境包时，可在 package.json 中设置，使用 --mode 做区分

  "scripts": {
		...
    "build:di": "vue-cli-service build --mode di",
    "build:prd": "vue-cli-service build --mode prd",
  },

打包

使用命令

// 打测试包
yarn build:di

生成 dist-DI 文件，其中的 DI 是在环境变量文件 .env.di 中的 VUE_APP_ENV 中配置

// 打生产包
yarn build:prd

生产 dist-PRD 文件

规范

命名规范

组件的命名使用大驼峰命名法

示例：

ShowList.vue
Foo.vue

注释规范

方法注释

/**
 * 判断是否为 JSON 字符串
 *
 * @param {string} data 目标字符串
 * @return {boolean}
 */
const isJSONString = data => {
  try {
    JSON.parse(data)
    return true
  } catch (e) {
    return false
  }
}

变量注释

  data () {
    return {
      // 产品名称
      productName: '蛋糕'
    }
  }

组件编写

注意及时拆分组件，一个组件在一般情况下不得超过 600 行

有问题欢迎提 issues，感谢！