bjquanjiang
/
DigitalScholl

# 力软框架移动端 · API 文档
以下 API 均定义在 **/common/mixins.js** 文件中，其中定义的方法、计算属性，会挂载到每一个 .vue 文件的 `this` 对象上。   
在任一 .vue 文件中，或是将通过 mixins 混入到 vue 页面的文件中，您都可以直接使用 `this.*` 的方式来调用这些 API。  
  
## 常用变量
- `this.API`： 当前后台接口地址；
- `this.PATH`： 当前页面路径，例如首页是 `/pages/home`；
- `this.DEV`： 当前是否是开发模式；
- `this.APP_VERSION`： 当前 App 端版本号，定义在 /config.js 里；
- `this.PLATFORM`： 当前平台英文简称，取值 'weixin'/'alipay'/'dingtalk'/'h5'/'app'/'unknown'；
- `this.PLATFORM_TEXT`： 当前平台中文全称，取值 '微信小程序'/'支付宝小程序'/'钉钉小程序'/'移动 Web'/'手机App'/'(未知)'。
  
## 网络请求
使用网络请求的 API 时，地址均只需要填写路径即可，无需填写完整的地址；且均集成了力软后台的身份验证，无需额外配置 token、loginMark 等字段。  
这些方法均是异步（async）方法，您可以使用 `await` 来等待其返回，或使用 `.then( result => { /* ... */} )` 的回调方式。  
    
上层封装的版本：  
（出错时均返回 null；如果配置了 errorTips 则出错时还会显示错误提示；如果用户登录状态失效，会强制跳转到登录页）  
- `this.HTTP_GET(url, data, errorTips)`： 发起一个 GET 请求，返回后台响应的数据；
- `this.HTTP_POST(url, data, errorTips)`： 发起一个 POST 请求，返回后台响应的数据；
- `this.HTTP_UPLOAD(filePath, formData)`： 上传一个文件，返回后台响应的数据，`filePath` 是文件的临时路径，`formData` 是上传时额外带的请求参数；
- `this.HTTP_DOWNLOAD(formData)`： 下载一个文件，返回下载后文件的临时路径，`formData` 是额外带的请求参数。

请求服务端数据：
- `this.FETCH_DATASOURCE(code)`： 请求指定 code 编码的数据源数据；
- `this.FETCH_ENCODE(rulecode)`： 请求指定规则编号的表单编码数据；
- `this.FETCH_FILEINFO(fileId)`： 请求指定 ID 的附件文件信息。
  
简易封装的版本：  
（以下网络请求的返回值均为一个数组，与 uni-app 原生的网络请求方法的返回值相同；返回值第一项 `error` 如果不为空表示发生了网络错误）  
- `this.GET(url, data, header)`： 发起一个 GET 请求，返回值为 `[errpr, { statusCode, header, data }]`；
- `this.POST(url, data, header)`： 发起一个 POST 请求，返回值为 `[errpr, { statusCode, header, data }]`；
- `this.UPLOAD(url, filePath, fromData)`： 上传一个文件，返回值为 `[error, { data, statusCode }]`；
- `this.DOWNLOAD(url)`： 下载一个文件，返回值为 `[error, { tempFilePath, statusCode }]`。

您也可以使用 uni-app 提供的 [网络请求 API](https://uniapp.dcloud.io/api/request/request)，其中包含了更丰富的方法。   
注意 uni-app 的 API 对钉钉小程序兼容性较差，如需使用钉钉小程序，请充分测试。  

## 全局变量
这些变量只是在本次启动 App 时可用，重新启动 App 后会被重置；如需持久化储存数据在客户端，使用 uni-app 的[数据缓存 API](https://uniapp.dcloud.io/api/storage/storage?id=setstorage)。  
注意：自行添加的全局变量，需要在 /config.js 的 `globalVariables` 字段中进行注册。  

- `this.CONFIG(path)`： 获取一个设置在 /config.js 中的配置项；传入参数是配置项的访问路径，例如配置项「全局头像是否显示为圆形」的路径为 `"pageConfig.roundAvatar"`；
- `this.SET_GLOBAL(key, value)`： 以指定键名设置一个全局变量；
- `this.GET_GLOBAL(key)`： 以指定键名获取一个全局变量；
- `this.CLEAR_GLOBAL()`： 清除所有全局变量，一般用于用户注销的场合；
- `this.SET_PARAM(obj)`： 设置一个跨页面变量，用于复杂参数的页面传参；
- `this.GET_PARAM()`： 获取之前设置的跨页面变量。

力软框架内置变量：  
- `this.DEV_ONLY_GLOBAL`： 【仅开发环境下可用】当前全局对象；仅可用于开发过程中观察数据变化；
- `this.GET_GLOBAL('loginUser')`： 当前登录用户的用户信息对象；
- `this.GET_GLOBAL('token')`： 【身份验证字段】用户令牌；
- `this.GET_GLOBAL('loginMark`： 【身份验证字段】登录设备 ID，由客户端生成，可以使用设备号或随机字符串；
- `this.GET_GLOBAL('company')`： 全局数据，所有公司列表；
- `this.GET_GLOBAL('department')`： 全局数据，所有部门列表；
- `this.GET_GLOBAL('user')`： 全局数据，所有职员列表；
- `this.GET_GLOBAL('dataDictionary')`： 全局数据，数据字典。

已登录用户，可以通过 `this.FETCH_CLIENTDATA()` （异步） API 来拉取公司、部门、用户列表以及数据字典。  

## 工具方法

- `this.MD5(str)`： 获取指定字符串的 MD5 码，用于处理密码；
- `this.GUID(joinChar)`： 用于生成 GUID；默认的分隔符是下划线 `_`，可以传入一个字符串参数来自定义分隔符；
- `this.COPY(obj)`： 创建目标对象的拷贝，使用 JSON 序列化的方式；
- `this.URL_QUERY(obj, auth=false)`： 将一个对象转换成 GET 请求参数字符串的形式（不包括问号），第二个参数表示是否加入身份验证信息（默认 false）；
- `this.CONVERT_HTML(str)`： 用于转义 HTML，例如将 `&amp;` 替换为 `<`，用于表单中的 html 区块；
- `this.TABLEITEM_DATEFORMAT(date)`： 将时间日期字符串格式化为列表项所使用的的格式；举例：是当天的时间：`['今天 8:30']`，是当年年度：`['5月22日', '8:30']`，不是当前年度：`['2019-05-22']`；返回值也可以直接当做字符串使用，会自动进行转化；
- `this.MP_SHARE_ENCODE(pageParam, query, pagePath)`： 创建小程序分享消息时使用，其他用户点开分享消息后会跳转到 pagePath 参数的页面，并且携带 pageParam 和 query 作为参数，该函数自动将这些参数格式化并编码成查询字符串；
- `this.MP_SHARE_DECODE(shareInfo)`： 解析小程序分享消息，自动获取参数并跳转页面；
- `this.FETCH_CLIENTDATA()`： 【异步】拉取客户端数据，包括：数据字典、公司/部门/人员数据。

## uni-app 的 API
以 uni.* 开头的 API 为未经力软框架封装的 API。您也可以自行进行封装。  
更多 API 请查看 uni-app 的[官方 API 文档](https://uniapp.dcloud.io/api/README)。