写在最开始的话

文档使用markdown语法编写，建议下载 Typora （其他markdown语法编辑器也可）查看，不要使用源代码模式，影响阅读

1.本地开发

# 进入项目目录
cd gwt-framework-ui

# 安装依赖
npm install

# 建议不要直接使用 cnpm 安装依赖，会有各种诡异的 bug。可以通过如下操作解决 npm 下载速度慢的问题
npm install --registry=https://registry.npm.taobao.org

# 可能会出现依赖组件的版本过高的问题，需要添加如下参数再执行
npm install --registry=https://registry.npm.taobao.org --legacy-peer-deps

# 启动服务
npm run dev

浏览器访问 http://localhost:80

2.打包发布

# 构建测试环境
npm run build:stage

# 构建生产环境
npm run build:prod

3.主要文件目录说明

3.1 package.json

项目中需要使用的一些依赖包，每次只要 package.json 有修改，项目必须重新 npm install 一次。
一般只需要修改以下内容:
{
	"name": "xxx",
  	"version": "xxx",
  	"description": "xxx",
  	"author": "xxx",
  	"license": "xxx",
}
"scripts":{
    "dev":"xxxx"
    ...
}
scripts 负责修改命令，一般都是配 npm run xxx
npm run dev 本地运行
npm run build:pro 打包生产环境包
npm run build:stage 打包测试环境包
npm run lint 使代码格式检查并自动修复
npm run preview 预览发布环境效果

3.2 vue.config.js

主要是本地开发以及打包的一些配置

1.设置代理，适用情况为一个项目有多个接口对应不同的服务，若一个项目所有的服务都相同，可在此设置，也可在 .env.development 文件中设置
如果需要设置代理的话，一般是在 target 中改
"devServer":{
    "proxy":{
        "/auth":{
            target:"http://192.168.1.128:8088",
            logLevel:"debug",
            pathRewrite:{
                '^/auth':'/api/auth'
            },
            ...
		},
        "/system":{
            target:"http://192.168.1.128:40301",
            logLevel:"debug",
            pathRewrite:{
                '^/system':'/api/system'
            },
            ...
		}
	}
}
'/auth','/system':根据具体情况修改，指的是访问接口路径中能匹配到 "/auth" 的接口，实际访问的服务器地址则是 target 中设置的地址,也就是 "http://192.168.1.128:8088", 访问接口路径中能匹配到 "/system" 的接口，实际访问的服务器地址则是对应target设置的地址。
pathRewrite：顾名思义，就是路径重写，如上，所有接口能匹配到 "/auth" 的,"/auth"全部改成 "/api/auth"
例如：
	用户信息接口为"/system/user/info"，则实际的接口地址为 "http://192.168.1.128:40301/api/system/user/info"
logLevel:通常我们在网页开发者工具中网络请求看到的请求地址为 "http://localhost:xxx" 等，如果需要看到实际的访问地址，设置'debug'，则可以在运行的开发工具命令行看到了（vscode）

2.其他设置
devServer:{
    host:'0.0.0.0',  //本地开发时可使用ip访问的地址
    port:'8080',     //本地开发时运行使用的端口
    open:true        //npm run dev运行后是否自动打开默认浏览器
}
outputDir:'dist'     //build之后，生成文件的目录名称。默认 dist
assetsDir:'static'   //用于放置生成的静态资源        

3.3 不同环境配置文件

本系统默认了三个配置文件，如果有多个环境，可根据需要添加

3.3.1 .env.development

开发环境的配置

VUE_APP_BASE_API : 表示在开发的时候所有api前面加 "/dev-api"，但后端接口并未设置，所以需要在vue.config.js中设置代理

3.3.2 .env.production

生产环境的配置

VUE_APP_BASE_API : 表示所有api自动加 "/prod-api"
通过 npm run build:prod 生成线上文件包

3.3.3 .env.staging

测试环境的配置

VUE_APP_BASE_API : 表示所有api前面自动加 "/stage-api"
通过 npm run build:stage 生成线上文件包
目前生产环境和测试环境都是使用 "/stage-api"
如后续后端接口前缀发生变化，需修改

3.4 src文件

如需引入src文件中文件，可使用 @ 来代表 src

3.4.1 api

api文件夹是该系统用到的所有接口文件
例如里面的 "monitor" 和 "system" 则是代表系统监控以及系统管理中页面的接口

每个接口文件最开始都需要引入 request.js
import request from '@/utils/request'

3.4.2 assets

一些静态资源(图片等)的放置

在 template 引入
<img src="~@/assets/images/login-form-bg.png">

3.4.3 components

系统统一封装的一些组件，具体可看 4.公用组件说明

3.4.4 config

系统中统一的一些配置

1.cli.config.js

导出vue/cli配置，只要配置修改都需要重启项目，主要是 vue.config.js 文件中的配置。在这里可以动态设置
outputDir: 生产环境构建文件的目录名
assetsDir: 放置生成的静态资源（js、css、img、fonts）的目录（相对于outputDir）
lintOnSave: 开发环境每次保存时是否输出为eslint编译警告
transpileDependencies: 进行编译的依赖
devPort: 开发环境端口号
providePlugin: 需要自动注入并加载的模块
build7z: npm run build时是否自动生成7z压缩包
buildGzip: npm run build时是否生成gzip
imageCompression: npm run build时是否开启图片压缩，由于国内网路原因image-webpack-loader必须使用cnpm安装，如无法使用cnpm，请配置false

3.4.5 router

一些静态路由，无需权限便可访问的页面，比如个人中心，登陆页面等，该系统用户登陆进来的菜单全部由后端返回，配置可在菜单管理中配置，但还有一些页面需要手动在系统中添加路由，例如登陆页面，404页面等，一般无需修改

如果页面布局是全新的页面，跟系统现有布局都不冲突，如下面404页面所示
{
	path: '/404',
    component: (resolve) => require(['@/views/error/404'], resolve),
    hidden: true
}

如无需权限访问的页面布局跟目前页面布局类似，都是常规布局顶部导航，左侧菜单（横向布局顶部导航），中间内容，则如下面个人中心页面所示
{
    path: '/user',
    component: Layout,
    hidden: true,
    redirect: 'noredirect',
    children: [
      {
        path: 'profile',
        component: (resolve) => require(['@/views/system/user/profile/index'], resolve),
        name: 'Profile',
        meta: { title: '个人中心', icon: 'user' }
      }
    ]
}
Layout 是页面公用布局组件，所有是公用布局页面内容都是在此组件下添加页面内容

3.4.6 store

项目中所有的状态管理

3.4.7 utils

项目中使用的一些公共的方法

1.file.js

主要是处理文件流的方法，使用的比较多的是，文件流转 base64 、base64 转文件流

个人中心上传头像，后端使用字符串接收头像，所以需要前端将上传后的文件流转成 base64 才能传给后端

2.request.js

向后端发送请求的一些配置

3. jsencrypt.js

处理登录加密事件

publicKey：是跟后端约定好的，后续有调整按照约定的修改
base64encrypt：base64加密，目前没用到，可视情况删除
encrypt、decrypt：分别是加密、解密方法，一般只用到加密，通过JSEncrypt库中的方法对其进行操作

4.auth.js

3.4.8 views

主要是放置各个页面

tool 文件对应系统工具各页面

system 文件对应系统管理各页面

monitor 文件对应系统监控各页面

error 文件对应401、404各页面

3.4.9 directive

自定义指令，该系统目前自定义了三种：

​ 1.弹窗拖拽 v-dialogDrag

使用方法

<el-dialog v-dialogDrag :width="dialogWidth" :title="title" :visible="visible"></el-dialog>

通过在弹窗元素上添加 v-dialogDrag 便可拖拽弹窗

​ 2.权限标识 v-hasPermi="['xxx:xxx:xxx']"

使用方法

<el-button
    v-hasPermi="['system:area:add']"
    type="primary"
    icon="el-icon-plus"
    size="mini"
    @click="handleAdd"
>新增</el-button>

如上例：

只有该用户有 system:area:add 的权限，此按钮才会显示

权限也是在菜单管理设置，可看列表权限标识字段

3.4.10 plugins

4.公用组件说明

注：公用组件若位于src/components/global 下，则已被全局注册，在使用时无需再次单独import即可生效

4.1 GwtSearchForm

列表页面顶部查询组件

1. html 引用

<GwtSearchForm
  ref="GwtSearchForm"
  :search-form-config="searchFormConfig"
  :columns="columns"
  @onSearch="onSearch"
/>
  <button>其他按钮</button>（slot）
</GwtSearchForm>

columns：所有查询条件的列表项

onSearch(val)：查询按钮事件，val为查询条件返回的值，以对象形式展示

slot（可选）：对查询栏其他按钮的扩展插槽，视具体情况添加

searchFormConfig：查询组件基础配置项

(以下为已设置的默认值，因此非必填)
size: 'small', // 表单尺寸
labelPosition: 'right', // 对齐方式
ruleForm: 'ruleForm', // 表单ref
labelWidth: '100px', // 表单名称尺寸
disabled: false, // 是否禁用表单
hasResetBtn: true, // 是否显示重置钮
formLeftSpan: 21, // 表单左col比例
formRightSpan: 3, // 表单右col比例
needExpandText: true, // 是否显示展开文字

2. script中设置

computed: {
   columns() {
      return [
        { 
          title: 'input', 
          dataIndex: 'packCode',
          placeholder: '请输入xxx',
          hideInSearch: true,
          needSearchRules: true, 
          required: true, 
          defaultValue: 123
        },
        { 
          title: '包件类型', 
          dataIndex: 'packName',
          valueType: 'select',
          placeholder: '请选择',
          propsValue: [this.statusOptions,'dictValue', 'dictLabel']
        },
        { 
          title: '采样单位',
          dataIndex: 'samplingCompanyId',
          valueType: 'treeSelect',
          placeholder: '请选择',
          propsValue: this.samplingCompanyList,
          normalizer: this.normalizerCompany
        },
        {
          title: '创建时间',
          dataIndex: 'createTime',
          valueType: 'datePicker',
          type: 'daterange',
          span: 16,
          formatter: (row) => this.xxx(row.createTime),
          width: 160,
          hideInForm: true
        }
      ]
   }
}

columns 部分参数的说明

​ title： 查询条件的名称

dataIndex ：需向后台传递的字段名

hideInSearch：查询项的显示与隐藏

span：该项占总row的比例宽度

formatter：格式化函数

​placeholder：为空值时表单内的默认提示语, 可不传

defaultValue：该项默认值

required：是否为必填项，设置后必填才能进行搜索

needSearchRules： 当 required为true时，需设置该变量同时为true，这么做是为了区分弹窗框中的form表单的必填项

​valueType ：表单展示形式，默认为输入框，目前只有以下几种形式，后续根据需求再添加其他

treeSelect：选择框下拉树
select：选择框
datePicker：日期
input： 文本框 

type：当 ​valueType 为 input, dataPicker 时的类型，具体可查阅element文档相关组件

propsValue

当 `valueType` 为`treeSelect` 时需要，变量为下拉树的列表
当 `valueType` 为 `select` 时为一个数组，第一项为下拉选择框的列表，第二项为 选择器选中值得字段。第三项为选择器显示值得字段

normalizer ：当 valueType 为 treeSelect 时需要，设置 node的 id,label,children

disableBranchNodes ：默认为 true , 当 valueType 为 treeSelect 时可设置，是否仅可选择叶子节点

selectMultiple ：默认 false ,当 valueType 为 select 时可设置，是否多选，值得注意的是，选择后的值为数组形式

valueformat ：日期值需要的形式，默认 yyyy-MM-dd ,当 valueType 为 datePicker 时设置

format ：日期值需要的形式，默认 yyyy-MM-dd ,当 valueType 为 date datePicker , type 为 daterange 时设置

其他属性不再此进行说明，与element文档一致

4.2 GwtDialog & GwtDialogForm

公共弹框及表单组件

直接封装的element弹框，可单独使用，亦可与GwtDialogForm组合使用，实现新增修改弹窗内的表单，示例如下：

<gwtDialog :dialog-form-config="{title: title, dialogWidth: '500px'}" :visible.sync="open" @onSubmit="submitForm">
  <!-- 弹窗内部表单组件 -->
  <GwtDialogForm
    ref="gwtDialogForm"
    :columns="columns"
    :edite-data="form"
  />
</gwtDialog>

gwtDialog 组件参数说明

visible：弹窗显示值

dialogFormConfig：

(以下为已设置的默认值，因此非必填)
hasFooter: true, // 是否有底部栏
dialogWidth: '50%', // 弹窗宽度
dialogTitle: '', // 弹窗标题
fullscreen: false, // 是否全屏

onSubmit：确定按钮事件

GwtDialogForm 组件参数说明

dialogFormConfig：弹窗表单基础配置项

(以下为已设置的默认值，因此非必填)
formLabelWidth: '100px', // 表单名称尺寸
formLabelPosition: 'right', // 对齐方式
wrapperCol: 12, // 布局列数
formSize: 'small', // 表单尺寸
refForm: 'ruleForm', // 表单ref
formDisabled: false, // 是否禁用整个表单
gutter：10 // 表单项间距

columns：表单配置，同GwtSearchForm

editeData：表单初始数据，用于编辑状态下

4.3 GwtTable

公共表格组件

<GwtTable
  :columns="columns"
  :data="tenantList"
  :options="options"
  :table-base-config="{
    hasSelection: true,
    total: total,
    loading: loading,
  }"
  @pagination="getList"
  @handleSelectionChange="handleSelectionChange"
/>

组件参数说明：

tableBaseConfig: 表格基础配置

(以下为已设置的默认值，因此非必填)
tableSize: 'mini', // 表格尺寸,目前表格统一用的mini
loading: false, // 加载状态
border: false, // 是否带有纵向边框
stripe: false, // 是否带斑马纹
rowKey: 'id', // 表格唯一标识
hasIndex: false, // 是否第一列需要序号
indexLabel: '序号',
hasSelection: false, // 是否有表格复选框
reserveSelection: false, // 是否记录分页选中
hasPage: true, // 是否需要分页组件
total: 0, // 数据总数
pageNum: 1, // 当前页
pageSize: 20, // 每页数量
offset: 360, // 表格高度调整值
expandAll: true, // 是否展开树结构表格
needScreen: false, // 是否需要筛选列
needMyColumn: false, // 是否多级表头

data: 表格数据

columns: 表格列配置，同GwtSearchForm

options: 操作按钮组

label: 文本
type :类型（primary /success / warning / danger / info /text)

handleSelectionChange：多选后的数据函数

pagination：翻页所要触发的函数

columns 部分参数的说明

​ title： 列名

dataIndex ：对应字段名

hideInTable：列显示与隐藏

fixed：固定列

width：列宽

​align：对齐方式

tooltip：是否溢出文案显示

sortable：是否支持排序

formatter： 格式化函数

​render ：扩展函数

columnType

treeSelect：选择框下拉树
select：选择框
datePicker：日期
input： 文本框
switch：开关

其他属性不再此进行说明，与element文档一致

以上四个独立组件完整案例请前往 src\views\system\tenant\index.vue 系统管理 -> 租户管理 中查看

4.4 GwtProTable

即以上四个独立式组件的混合模式，可用于常规页面的超级组件，配置相关参数，引入 <gwtProTable /> 标签即可生效，说明如下：

<GwtProTable
  ref="gwtProTable"
  :columns="columns"
  :options="options"
  :pro-table-config="{ hasSelection: true }"
  :request="listUser"
  :submit="submit"
  :button-group="buttonGroup"
  @handleSelectionChange="handleSelectionChange"
/>

组件参数说明：

proTableConfig: 超级表格组件基础参数配置,为 searchFormConfig, dialogConfig, dialogFormConfig, tableBaseConfig 四者并集,因此亦为非必填

options: 最右列操作按钮组

label: 文本
type :类型（primary /success / warning / danger / info /text)

columns: 表格列配置

request: 请求数据方法api

manualRequest: 是否手动触发首次请求

buttonGroup: 表格上方按钮组

submit: 新增编辑保存方法

2. 在script中的设置

buttonGroup

    buttonGroup() {
      return [
        {
          title: '新增',
          permission: 'system:user:add',
          icon: 'el-icon-plus',
          method: () => {
            this.handleAdd()
          }
        },
        {
          title: '导入',
          permission: 'system:user:import',
          icon: 'el-icon-upload2',
          method: () => {
            this.handleImport()
          }
        },
        {
          title: '导出',
          permission: 'system:user:export',
          icon: 'el-icon-download',
          method: () => {
            this.handleExport()
          }
        },
        {
          title: '修改',
          permission: 'system:user:edit',
          icon: 'el-icon-edit',
          disabled: this.single,
          method: () => {
            this.handleUpdate({})
          }
        },
        {
          title: '删除',
          permission: 'system:user:remove',
          icon: 'el-icon-delete',
          type: 'danger',
          disabled: this.multiple,
          method: () => {
            this.handleDelete({})
          }
        }
      ]
    }

options

    options() {
      return {
        width: '180px',
        list: [
          {
            id: 1,
            title: '修改',
            icon: 'el-icon-edit',
            permission: 'system:user:edit',
            method: (key, row, rowIndex) => this.handleUpdate(row)
          },
          {
            id: 2,
            title: '删除',
            icon: 'el-icon-delete',
            permission: 'system:user:remove',
            method: async(key, row, rowIndex) => this.handleDelete(row)
          },
          {
            id: 3,
            title: '重置',
            icon: 'el-icon-key',
            permission: 'system:user:resetPwd',
            method: async(key, row, rowIndex) => this.handleResetPwd(row)
          }
        ]
      }
    }

以上混合式组件完整案例请前往 src\views\system\user\index.vue 系统管理 -> 用户管理 中查看

未完待续...

5.登录

出于安全性考虑，登录用到了密码加密

login.vue

1.首先获取 uuid

通过获取验证码接口得到后端返回的 uuid,请求登录接口的时候需要带过去
见 getCode()

2.加密用户名和密码

通过utils中的公共方法，对用户名和密码进行加密
const loginQueryForm = {
    password: encrypt(this.loginForm.password),
    username: encrypt(this.loginForm.username),
    code: this.loginForm.code,
    uuid: this.loginForm.uuid
}

3.调用 store 的 user 模块中的 Login

this.$store.dispatch('Login', loginQueryForm).then(()=>{
	...
})

4.在登录请求成功之后将返回的 access_token 和 expires_in 设置到cookie上去，之后的请求接口都需要在请求头携带 token

通过 utils/auth 中设置cookie的方法
 	setToken(data.access_token)
	setExpiresIn(data.expires_in)