m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/005-/346/240/270/345/277/203/351/200/232/347/224/250Util/000-/346/240/270/345/277/203/346/226/271/346/263/225.md

@@ -0,0 +1,398 @@
+# 核心通用Util
+
+    框架内置`Util`工具库通过框架自动全局引入，代码中可以直接使用，无需额外引入。
+
+## 使用场景
+
+框架内置核心`Util`
+
+- `Util`编写时，内部使用
+
+- `Widget`编写时，内部使用
+
+- 项目中任何需要用到核心通用函数的地方
+
+## 方法说明
+
+注：此工具集下的方法通过`Util.method()`调用，如`Util.uuid()`
+
+### os
+
+判断当前的运行环境
+
+__系统环境判断__
+
+```js
+// Android环境与iOS只会有一个为true
+Util.os.android;
+Util.os.ios;
+```
+
+__容器环境判断__
+
+```js
+// ejs，dd，h5容器只会有一个为true
+// 分别代表`EJS`容器，`钉钉`容器，`其它`(包括普通浏览器)容器
+Util.os.ejs;
+Util.os.dd;
+Util.os.h5;
+```
+__其他容器判断__
+
+```js
+// M7_v7.4.2版本支持
+// 分别代表`微信`容器，`企业微信`容器，`政务微信`容器，同时也是h5环境
+Util.os.wechat;
+Util.os.wxWork;
+Util.os.wxWorkLoacl;
+```
+__更多功能__
+
+```js
+// Android环境下
+// 获取Android的版本号以及是否是非Chrome的Android环境
+Util.os.version;
+Util.os.isBadAndroid;
+
+// iOS环境下
+// 获取iOS的版本号以及是否是苹果手机，是否是pad
+Util.os.version;
+Util.os.iphone;
+Util.os.ipad;
+```
+
+
+### uuid(options)
+
+生成一个随机uuid
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| len | Number | 长度，默认为32位，最大不能超过36，最小不能小于4 |
+| radix | Number | 随机的基数，如果小于等于10代表只用纯数字，最大为62，最小为2，默认为62 |
+| type | String | 类别，默认为`default`代表 a-c-c-d-e的连线模式，如果为` noline`代表不会有连线 |
+
+**示例**
+
+```js
+// 生成一个8-4-4-4-12格式的 32位uuid，例如 yczYoFSp-ooru-ANjl-Hrgg-XgXmMxSN
+var uuid = Util.uuid();
+
+// 生成一个只有数字的36位 uuid，例如 52616056-5161-7170-8460-802618729824
+var uuid = Util.uuid({
+    len: 36,
+    radix: 10
+});
+
+// 生成一个没有下划线的10位 uuid，例如 xOvHy03wfA
+var uuid = Util.uuid({
+    len: 10,
+    type: 'noline'
+});
+```
+
+
+### getExtraDataByKey(key)
+
+通过传入key值，得到页面key的初始化传值，实际情况是获取 `window.location.href` 中的参数的值
+
+__注意：__
+
+微信、支付宝小程序不支持获取`window.location.href`参数。
+
+在跨端框架中，页面传递参数可以统一从页面的`onLoad函数`中获取上一个页面传递的参数。
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     x      |      x       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| key | String | 对应的key值 |
+
+__返回说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| value | String | 返回href中对应的key的value |
+
+**示例**
+
+```js
+//查询参数,key对应的value
+var value = Util.getExtraDataByKey(key);
+
+// 建议在跨端框架中统一使用页面的onLoad函数获取上一个页面传递的参数
+export default {
+    data: function() {
+        return {
+            key: ''
+        }
+    }
+    onLoad: function (option) { //option为object类型，会序列化上个页面传递的参数
+        this.key = option.key;
+    }
+}
+```
+
+
+### getFullUrlByParams(url, data)
+
+将json参数拼接到url中
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| url | String | `必填`，需要拼接的url |
+| data | JSON | `必填`，对应需要拼接的JSON参数 |
+| isType | Boolean | `选填`，是否相对路径。 默认`false`，微信，支付宝小程序不支持istype=ture相对路径选项 |
+
+**示例**
+
+```js
+var url = 'http://app.epoint.com.cn/m8fedoc';
+var data = {
+    'key1': 'value1'
+};
+
+// 例如返回: http://app.epoint.com.cn/m8fedoc?key1=value1
+var finalUrl = Util.getFullUrlByParams(url, data);
+```
+
+### noop
+
+空函数
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+**示例**
+
+```js
+// 这个空函数: function() {};
+var noop = Util.noop;
+```
+
+### extend(deep, target, source1, source...)
+
+合并多个对象
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| deep | Boolean | 为true时会进行递归合并，可以省略（代表默认`false`） |
+| target | Object | `必填`，需要合并的目标对象，这个对象会随之修改，并且作为返回值 |
+| object1 | Object | `必填`，需要合并的目标对象 |
+| objectN | Object | 需要合并的目标对象 |
+
+**示例**
+
+```js
+var target = {
+  company: "epoint",
+  product: {
+    ejs: "ejs混合开发方案"
+  }
+};
+
+var obj1 = {
+  city: "suzhou",
+  product: {
+    m7: "m7移动框架"
+  }
+};
+
+// 非递归合并
+var newObj1 = Util.extend({}, target, object1);
+
+// 输出：{"company": "epoint", "product": {"m7": "m7移动框架"}, "city": "suzhou"}
+console.log(JSON.stringify(newObj1));
+
+// 递归合并
+var newObj2 = Util.extend(true, {}, target, obj1);
+
+// 输出：{"company": "epoint", "product": {"ejs": "ejs混合开发方案", "m7": "m7移动框架"}, "city": "suzhou"}
+console.log(JSON.stringify(newObj2));
+```
+
+### each(object, handler)
+
+遍历对象或数组
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| object | Object或Array | `必填`，需要遍历的对象或数组，若为对象，仅遍历对象根节点下的key |
+| handler | Function(Integer或String, Anything element) | `必填`，每个元素执行的回调函数；其中，index表示当前元素的下标或key(下标从0开始)，element表示当前匹配元素 |
+
+**示例**
+
+```js
+var array = [1,2,3];
+
+Util.each(array, function(index,item) {
+  console.log(item*item);
+});
+```
+
+### getProjectBasePath(patten)
+
+得到项目的根路径
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     x      |      x       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| patten | String | 匹配模式，如果在其它文件夹下面，需要换为对应的目录 |
+
+**示例**
+
+```js
+// 例如页面地址为http://127.0.0.1:5500/ejs.m8.mobileframe/dist/build/h5/index.html#/pages/utils/core
+
+// 结果: http://127.0.0.1:5500/ejs.m8.mobileframe/
+var basePath = Util.getProjectBasePath();
+
+// 结果: http://127.0.0.1:5500/ejs.m8.mobileframe/dist/build/
+var basePath2 = Util.getProjectBasePath('/h5/');
+```
+
+上述示例项目对应的目录结构为
+
+```
+ejs.m8.mobileframe
+    |- dist
+    |   |- build        
+    |    |    |- h5      
+    |    |    |   |- index.html      // 页面index.html路径
+```
+
+
+
+### getPathSuffix(path)
+
+得到文件的后缀
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| path | String |`必填`， 对应文件路径 |
+
+**示例**
+
+```js
+var path = 'pages/test.js';
+
+// 返回: 'js'
+var suffix = Util.getPathSuffix(path);
+```
+
+### dataProcess(response, options)
+
+处理返回数据，返回按指令处理过后的最终数据
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+__参数说明__
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| response | JSON | `必填`，需要处理的数据 |
+| options | Object | 配置信息 |
+| options.dataPath | String或Array | 需要获取的路径指令 |
+
+__返回说明__
+
+返回一个`result`，以下是`result`中的对象
+
+注意，如果`dataPath`没传，默认不会处理数据，即返回的是原始数据`response`
+
+| 参数 | 参数类型 | 说明 |
+| :------------- |:-------------:|:-------------|
+| code | Number | 处理完的结果，为`1`代表处理成功，`0`代表失败，一般失败的原因是接口返回的`status`不正确或者格式不匹配 |
+| message | String | 处理完后的提示，例如错误信息提示等 |
+| data | JSON | 处理完后的最终数据，如果没有获取到对应节点下的数据，为`null` |
+
+**示例**
+
+```js
+var response = {
+    "custom": {
+        "infolist": [{
+            "title": "测试的title",
+            "guid": "131830"
+        }]
+    },
+    "status": {
+        "code": 1,
+        "text": "成功",
+        "url": ""
+    }
+};
+
+// 直接处理数据
+var result = Util.dataProcess(response, {
+    dataPath: 'custom.infolist'
+});
+
+// result.data才是最终数据
+console.log(result.data);
+
+// 或者也可以这样处理，这样会一直处理路径数组中的每一个，直到拿到数据为止或结束
+var result = Util.dataProcess(response, {
+    dataPath: ['custom.infolist', 'custom.infoList']
+});
+```