# afire

**Repository Path**: itguo89/afire

## Basic Information

- **Project Name**: afire
- **Description**: 基于uni-app封装的业务组件，实现小程序、web等多端开发工具包
- **Primary Language**: JavaScript
- **License**: BSD-4-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-04
- **Last Updated**: 2024-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Afire

### 一、框架封装
>基于uni-app封装的业务组件，实现小程序、web等多端开发工具包
##### NOTE:可能并不是所有业务场景都适合，此工具包主要目的减少类似项目中同样重复业务开发的代码，提升效率。


### 二、简介
>1.基于uni-preset-vue脚手架开发，需要提前生成uni-app开发基本脚手架
```javascript
vue create -p dcloudio/uni-preset-vue my-project
```
>2.安装afire-kit
```javascript
npm install afire-kit --save
```
>3.需要注意事项，需要单独新增vue.config.js配置文件，用来处理该处node_modules的babel转换问题
```javascript
module.exports = {
    // 选项...
    transpileDependencies: [
        "afire-kit"
    ]
}
```

### 三、API相关的说明

#### 3.1 Service使用说明
>1.ServiceConfig.class.js
##### 静态配置文件,默认的配置文件入口，如果有不同的或者新增的属性，可继承扩展此类

```javascript
class ServiceConfig {
    ///成功的业务码
    static SUCCESS_CODE = '0';

    ///错误码：-1
    static ERROR_CODE_01 = '-1';

    ///错误码：-2
    static ERROR_CODE_02 = '-2';

    ///错误码：-3
    static ERROR_CODE_03 = '-3';

    ///签名skey
    static SIGN_KEY = "_AFIRE_SIGN_KEY_";

    ///token-key-name： 提交接口的token名
    static TOKEN_KEY = "_AFIRE_TOKEN_";

    ///token-ret-name： 返回token名
    static RET_TOKEN = "token";

    ///默认的序列化参数key名
    static SERIALIZE_PARAM_KEY = "param";

    ///session key存储会话token对应key
    static LOCAL_SESSION_KEY = "_AFIRE_SESSION_KEY_";

    ///server host
    /// you need to set `Domain` props when on extends this class.
    static DOMAIN = '';
}
```
##### 自定义自己的配置文件
```javascript
class GlobalConfig extends ServiceConfig {
    /// to-do your code
}
```

>2.Service.class.js
##### 通用基础service类封装,目前封装了请求通用属性、请求前beforeReq()权限拦截、请求后afterReq()返回数据解析处理等,可做作为基础的对象继承扩展，根据实际需求而定
|  属性   | 说明  |  默认值  |  是否要传值  |
|  ----  | ---- | ----  | ---- |
| domain | api域名参数 | 默认的ServiceConfig中为空，需要自定义，在GlobalConfig中| 必须要初始化设置 |
| url    | api具体接口上下文path | 具体实例化时候需要设置 |  必传参数 |
| params | body请求放入的参数    | {} | 选传 |
| header | 头部信息携带，内部header封装权限token、签名、contentType等等通用请求字段,特殊字段可用次字段传入 | 非必传 |
| showLoading | 是否显示loading框 | false | 选传 |
| auth | 请求接口是否需要验证权限，携带token | true | 选传 |
| showToast | 失败时是否弹出toast | true | 选传 |
| successToast | 成功请求后的提示toast | false | 选传 |
| needSign | 是否需要签名字段，头部 | false | 选传 |
| serialize | 是否需要序列化参数传递给后台 | false | 

##### 具体用法如下：
```javascript
class Service {
    ///接受ServiceConfig对象或者一个子对象
    constructor(serviceConf) {
    }

    sign(){
        ///通用签名字段
    }

    beforeReq(){
        ///权限拦截、校验等判断
    }

    ///默认的处理的数据结构如下：
    ///  {
    ///     code: '',
    ///     msg: '',
    ///     data: {Object|string}
    /// }
    afterReq(res) {
        ///返回字段处理
    }

    req(){
        /// 发送请求信息...
    }
```

>3.BaseService.class.js [ 该类继承Service.class对象 ]
##### 基础通用请求service封装，基本上除了分页、上传类的请求，大部分常用的请求实例化此类就行了，以下demo业务接口请求采用混入的写法，基于Vue mixins

##### API的用法完全继承Service的写法

##### Api说明
```javascript
    req(); //请求接口
```

##### 具体用法如下：
```javascript
import BaseService from 'afire-kit/service/BaseService.class';

///引入上面自定义的GlobalConfig.class.js类文件
import GlobalConfig from '/your/local/path/GlobalConfig.class';

export default {
    data(){
        service: null
    },

    methods: {
        async getData(...opt) {
            ///防止重复实例化
            if(!this.service) {
                ///默认的处理的数据结构如下：
                ///  {
                ///     code: '',
                ///     msg: '',
                ///     data: {Object|string}
                /// }
                this.service = new BaseService(GlobalConfig);

                ///配置接口的url参数，除了域名之后的部分即可
                ///域名部分在GlobalConfig中DOMAIN字段配置过了，框架自动接入
                ///当然你也可以单独配置某个service实例的domain属性，防止不同接口请求域名不一样
                ///this.service.domain = '';
                this.service.url = '/api/url/path';

                /// ====== 以下有默认值， 可不定义 ===== 
                ///是否需要校验权限，默认的需要校验请求权限，
                ///如登录请求接口、获取短信验证码接口等非校验权限的，可设置false
                ///则头部token等相关的字段不再传入，且框架也不再拦截权限
                ///默认的为true，可不定义
                this.service.auth = true;

                ///默认的为true，可不定义
                ///是否显示loading框
                this.service.showLoading = true;

                ///默认的为true，可不定义
                ///失败时是否弹出toast
                this.service.showToast = true;

                ///默认的请求成功不显示toast
                this.service.successToast = false;

                ///是否需要加签名 + 头部信息里面存放
                ///默认不需要签名加密
                ///note:如果为true，需要对应GlobalConfig里面配置SIGN_KEY字段
                this.service.needSign = false;

                ///body是否需要序列化
                ///如参数body传递的格式: {'param': {Object}}
                ///对应的如果为true的话，需要配置GlobalConfig的SERIALIZE_PARAM_KEY字段，默认值为param
                this.service.serialize = false;
            }

            /// ===== 以下是易变参数，最好放到外面便于同步 =====
            ///body参数
            this.service.params = {...};

            ///头部需要传的参数，目前头部签名、token等权限的字段已经内置了，只需要配置即可
            this.service.header = {...};

            ///发送请求
            let res = await this.service.req();
            
            ///to-do your code 获取处理的数据结果
        }
    }
}
```

>4.分页请求PageService.class.js
##### 封装了常见的分页请求，目前是通过下标索引来控制分页数的累加,start表示当前索引值,limit表示页面尺寸数，类似pageSize

|  属性   | 说明  |  默认值  |  是否要传值  |
|  ----  | ---- | ----  | ---- |
| domain | api域名参数 | 默认的ServiceConfig中为空，需要自定义，在GlobalConfig中| 必须要初始化设置 |
| url    | api具体接口上下文path | 具体实例化时候需要设置 |  必传参数 |
| params | body请求放入的参数    | {} | 选传 |
| showLoading | 是否显示loading框 | false | 选传 |
| auth | 请求接口是否需要验证权限，携带token | true | 选传 |
| showToast | 失败时是否弹出toast | true | 选传 |
| successToast | 成功请求后的提示toast | false | 选传 |
| needSign | 是否需要签名字段，头部 | false | 选传 |
| start | 分页下标索引值, 默认的内部已经内置了 | 0 | 选传 |
| limit | 当前页分页数据条数，即pageSize, 因为采用了滚动触发页面 | 8 | 选传 |

##### Api说明
```javascript
    req(); //请求接口

    onRefresh(): //下拉刷新接口

    onBottom(): //分页请求接口

    //opt 参数参考上面的属性
    //主要是start && limit, 如 opt = {start: 0, limit: 10}
    resetPageQuery(opt = {}): //重置分页对象
```

##### 具体用法如下：
```javascript
import PageService from "afire-kit/service/PageService.class";
import GlobalConfig from "/your/local/path/GlobalConfig.class";

export default {
    data(){
        page_service: null
    },

    methods: {
        async getData(...opt){
            if(!this.page_service) {
                ///默认的解析数据结构如下
                /// {
                ///     code: ''//状态码
                ///     msg: '' //提示信息
                ///     data: {
                ///       //数据结构对应的key    
                ///       list: []
                ///     }
                /// }
                this.page_service = new PageService(GlobalConfig, "list");

                ///配置接口的url参数，除了域名之后的部分即可
                ///域名部分在GlobalConfig中DOMAIN字段配置过了，框架自动接入
                ///当然你也可以单独配置某个service实例的domain属性，防止不同接口请求域名不一样
                ///this.service.domain = '';
                this.page_service.url = '/api/url/path';

                /// ====== 以下有默认值， 可不定义 ===== 
                ///是否需要校验权限，默认的需要校验请求权限，
                ///如登录请求接口、获取短信验证码接口等非校验权限的，可设置false
                ///则头部token等相关的字段不再传入，且框架也不再拦截权限
                ///默认的为true，可不定义
                this.page_service.auth = true;

                ///默认的为false，可不定义
                ///是否显示loading框
                this.page_service.showLoading = false;

                ///默认的为true，可不定义
                ///失败时是否弹出toast
                this.page_service.showToast = true;

                ///默认的请求成功不显示toast
                this.page_service.successToast = false;

                ///是否需要加签名 + 头部信息里面存放
                ///默认不需要签名加密
                ///note:如果为true，需要对应GlobalConfig里面配置SIGN_KEY字段
                this.page_service.needSign = false;

                ///body是否需要序列化
                ///如参数body传递的格式: {'param': {Object}}
                ///对应的如果为true的话，需要配置GlobalConfig的SERIALIZE_PARAM_KEY字段，默认值为param
                this.page_service.serialize = false;

                ///分页的参数，limit等价于pageSize
                ///start是分页的下标索引数，就当前分页的条数
                ///后面会支持按照页码数递增分页模式，当前不支持
                this.page_service.limit = 8; //默认为8条记录
                this.page_service.start = 0; //默认的从0开始
            }

            /// ===== 以下是易变参数，最好放到外面便于同步 =====
            ///body参数
            this.service.params = {...};

            ///头部需要传的参数，目前头部签名、token等权限的字段已经内置了，只需要配置即可
            this.service.header = {...};

            ///发送请求
            let res = await this.service.req();
            
            ///to-do your code 获取处理的数据结果
        }
    }
}
```

#### 3.2 PageEvent事件点阅 && 发布，用来触发事件通知，类似EventBus
>使用注意事项：pageEvent为页面级别的事件触发机制，每个页面仅触发一次，不会多次触发；不支持页面B触发页面A中的组件C机制，只支持页面B触发页面A事件通知,如果需要通知到组件，请采用页面和组件之间通知比如组件watch某个属性，或者直接通过props来实现

##### 之所以使用自定义的组件通知，不采用uni-app自带的，主要是自带的会触发多次，而且不是在想要的地方、时机触发

##### Api说明
```javascript
    ///注册监听事件
    /// 事件名 && 处理事件通知函数
    addListener(eventName, callback);

    ///触发事件 && 传递数据
    emitEvent(eventName, data);

    ///注销某个page上的所有事件
    ///route如/pages/path/a
    ///默认的情况，不用主动销毁事件，框架会在页面onUnload时候会卸载事件
    destroyEvent([route]);
```

##### 具体用法如下：
```javascript
//main.js中引入pageEvent组件
import pageEvent from "afire-kit/pageEvent";

//扩展Vue实例属性
Vue.prototype.$pageEvent = pageEvent;


///Page-A.vue

onLoad(){
    ///注册&&监听事件refreshPage
    this.$pageEvent.addListener('refreshPage', function () {
        ///to-do your code
    });
}

///Page-C.vue

onLoad(){
    ///注册&&监听事件onArrayListDelete
    this.$pageEvent.addListener('onArrayListDelete', function (ret) {
        ///to-do your code
        console.log(ret);
    });
}

///Page-B.vue
methodB(){
    ///触发事件refreshPage
    this.$pageEvent.emitEvent('refreshPage');

    ///触发事件onArrayListDelete
    this.$pageEvent.emitEvent('onArrayListDelete', {index: 0});
}

```


#### 四、组件相关的说明
##### 待续～～～～

### Customize configuration
See [Configuration Reference](https://cli.vuejs.org/config/).