m8-framework-mcp 1.0.0

package/docs/ejs-doc/m7_mini_h5/m7_mini_h5.md

@@ -0,0 +1,410 @@
+# 新点小程序开发指南
+
+## 文件修订记录
+|版本号|发布时间|作者|备注|
+|:----:|:------:|:------:|
+| V1.0.0 | 2019/11/21 |吴松泽| 初稿|
+| V1.0.1 | 2020/03/15 |吴松泽| 完善对接开放平台部分|
+
+## 适用范围
+
+`跨平台开发人员`
+
+## 概述
+
+为了提升H5页面在原生容器中的展示效果，以及达到原生页面性能。我们基于M7框架开发出新点小程序框架，使用webpack4对M7框架代码重新构建。可以将M7项目代码快速改造，得到符合原生容器**本地加载**方式的小程序代码压缩包。
+
+## 版本要求
+
+`新点开放平台` > `1.0.0`
+
+`Android`&&`iOS` > `7.4.2`（工作平台）
+
+`EJS` > `3.4.2`
+
+## 环境搭建
+### 安装Node环境
+
+1、下载并安装Node.js：[下载](https://nodejs.org/en/download/ "下载")
+
+因提供的项目模板均依赖于npm（全称 Node Package Manager，即“node包管理器”），所以需要用到Node。
+请下载Node最新的LTS版本，低版本Node会导致调试时报错。
+
+2、（可选）安装完成后，将npm源地址设置为本地能够连接成功的源地址。例如：
+```
+ npm config set registry http://registry.npm.taobao.org/
+```
+
+### 安裝开发工具
+
+下载并安装开发工具VSCode（全称 Visual Studio Code）：[下载](https://code.visualstudio.com/download "下载")
+
+> 需以管理员权限安装VSCode，否则在项目初始化时会提示 `EPOINT TOOLS` 无权限配置开发环境。
+
+### 安装开发插件
+
+1、下载开发插件 `EPOINT_TOOLS`： [下载EPOINT_M7_TOOLS](http://218.4.136.126:1443/epointoa9/H5/xcx/vscode_tool/epoint-m7-tool.zip "下载")
+
+> - `EPOINT_TOOLS` 是我们为开发者提供的新点小程序开发插件，便于开发者能在熟悉的开发环境（VSCode）下开发新点小程序。
+- 插件提供了完善的项目自动化开发功能，如：安装依赖、本地调试、手机调试、上传小程序、本地配置项功能。
+
+**注意：**
+
+安装好插件后需要用VSCode打开模板项目根目录，才可以正常显示插件按钮。插件识别新点小程序项目模板后，点击初始化安装项目依赖，请耐心等待。
+
+2、解压下载到的 epoint-m7-tool.zip 文件，得到一个.vsix格式的文件。
+
+3、按下图步骤完成 `EPOINT_TOOLS` 的安装。
+
+![](https://fdoc.epoint.com.cn/onlinedoc/rest/frame/base/attach/attachAction/getContent?isCommondto=true&attachGuid=337a8d35-01fb-41e1-8117-f23de821fe22)
+
+4、安装成功后，打开新点小程序项目即可看到 EPOINT_TOOLS 目录。
+
+![](images/install.png)
+
+### 安装Chrome浏览器
+因本地调试需依赖 Google Chrome 浏览器，因此也需要下载安装。
+
+## 新点小程序框架
+我们基于M7框架开发出新点小程序框架，使用webpack4对M7框架代码重新构建。保留符合M7模式的开发方式，保留M7的Util插件、widgets组件。可以将M7项目代码快速改造，得到符合小程序容器本地加载方式的代码压缩包。
+
+## 框架获取
+[下载小程序框架](http://218.4.136.126:1443/epointoa9/H5/xcx/vscode_tool/webpack.m7.mobileframe.zip "下载小程序框架")
+### 框架整体目录
+```
+webpack.m7.mobileframe:
+├─build                             // webpack 构建配置
+├─dist                              // 代码构建后文件
+└─src
+    ├─js                            // M7框架代码
+	├─pages                         // 业务代码
+    │  └─[module_name]              // 业务模块名称
+    └─public                        // 公共资源
+```
+### pages目录
+```
+webpack.m7.mobileframe:
+└─src
+	├─pages                         // 业务代码
+    │  ├──[module_name]              // 业务模块名称
+	│  │	├──css
+	│  │		├──xxx.css
+	│  │	├──js
+	│  │		├──xxx.js
+	│  │	└──img
+	│  │──────xxx.html
+```
+
+与M7框架业务代码结构一样，唯一区别是**js对应的html文件名必须一致**。
+
+### plugin.json
+```
+[{
+    "moduleName": "module", // 模块名称
+    "pages": [
+        "./src/pages/module/js/module_page1.js", // 模块页面1
+        "./src/pages/module/js/module_page2.js"  // 模块页面2
+    	],
+    "appId": "xxx", // 开放平台新建应用模块获取
+    "indexURL": "module/module_page1.html", // 模块入口页面
+    "version": "1.0.0"
+	},{
+	...
+}]
+```
+根目录的`plugin.json`文件中需要配置项目模块名称、项目模块地址、模块的appId、小程序入口路径（点击小程序自动打开入口页面），模块的版本号
+
+## 快速上手
+### 前置条件
+已经根据上述文档搭建好开发环境
+### 起步
+#### > 第一步：导入项目
+
+获取小程序框架。
+
+打开开发模板：打开VSCode，选择“文件 > 打开文件夹”，选择刚刚解压后文件所在的文件夹打开。
+
+![](https://fdoc.epoint.com.cn/onlinedoc/rest/frame/base/attach/attachAction/getContent?isCommondto=true&attachGuid=1478d4c0-8f5d-4143-a183-3f760ab1485d)
+
+#### > 第二步：设置开放平台信息
+在 EPOINT TOOLS 中点击“设置”以设置开放平台、账号密码相关信息。
+
+![](images/setting.png)
+
+#### > 第二步：初始化
+
+因开发包在本地运行需要依赖一些文件，需要先下载这些文件并安装。
+
+**方法1**：在 EPOINT TOOLS 中点击“初始化”以安装项目依赖。
+
+![](images/001.png)
+
+
+**方法2**：通过在项目根目录执行如下命令安装依赖包。
+
+```
+ npm install
+```
+
+#### > 第三步：启动项目
+
+##### 本地调试：
+
+本地调试，指的是通过PC端浏览器的模拟手机功能调试小程序应用。
+
+**方法1**：通过 `EPOINT TOOLS` 启动项目。安装项目依赖成功之后，点击“本地调试”，**输入启动的模块名称后**，默认浏览器会自动打开并访问`plugin.json`中该模块配置的项目首页 。
+
+![](images/dev.png)
+
+**方法2**： 通过在项目根目录下执行如下命令启动项目。
+
+```
+npm run dev -- --env.modeName=模块名称
+```
+
+##### 手机调试：
+
+手机调试，指的是临时生成应用调试二维码，通过客户端扫码调试应用。
+
+通过 `EPOINT TOOLS` 启动项目。安装项目依赖成功之后，点击“手机调试”，**输入启动的模块名称后**，插件根据设置的开放平台地址和账号密码，上传调试包临时生成二维码。
+
+![](images/mobile_dev.png)
+
+### 上传小程序
+
+代码构建，将小程序代码根据模块分类，通过webpack构建成独立可运行的代码包至`dist`文件夹内，并且自动根据模块名称打包成小程序压缩文件，上传至设定的开放平台内。
+
+通过 `EPOINT TOOLS` 代码构建。安装项目依赖成功之后，点击“上传小程序”，**输入上传的模块名称**，**小程序的版本号**后，插件会将小程序包构建，上传至开放平台。
+
+![](images/update.png)
+
+
+
+## 页面编写
+### 基础页面
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0, viewport-fit=cover" name="viewport" />
+    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+    <meta name="format-detection" content="telephone=no" />
+    <title>module1</title>
+  </head>
+
+  <body>
+      <div class="mui-content">
+      </div>
+  </body>
+</html>
+```
+其中按照代码规范：
+
+- 页面头部必须要有 头部申明
+
+- 采用html5标准文档头`<!DOCTYPE html >`
+
+- 相应的meta标签必须要有
+
+- 页面必须要设置标题title
+
+### 资源引入
+新点小程序使用webpack构建，资源引入统一在**js页面**使用import引入
+```
+import '../css/module_page2.css';
+import '../../../js/m7_core/utils/util.charset.js';
+```
+默认已经加载框架的核心基础js资源，包括：
+
+MUI基础库的核心js
+
+Mustache模板引擎
+
+Zepto，一个为移动端打造的Dom操作库，类似PC端的jQuery。
+
+EJS，用于调用原生能力的API集合
+
+框架通用基础工具类，包括Ajax，Promise以及一些常用的API集合
+
+**多模块通用资源样式，统一放到`src/public`中**
+
+## 完整示例
+下拉刷新列表
+
+html代码：
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0, viewport-fit=cover"
+        name="viewport" />
+    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+    <meta name="format-detection" content="telephone=no" />
+    <title>minirefresh</title>
+</head>
+
+<body>
+    <div class="mui-content ">
+        <!-- minirefresh开头的class请勿修改 -->
+        <div id="minirefresh" class="minirefresh-wrap">
+            <div class="minirefresh-scroll" >
+                <ul id="listdata"></ul>
+            </div>
+        </div>
+    </div>
+    <script type="text/x-tpl" id="item-template">
+        <li class="list-item" id="{{guid}}">
+            <h3 class="msg-title">
+                {{title}}
+            </h3>
+            <span class="msg-fs14 msg-date">
+                {{date}}
+            </span>
+        </li>
+    </script>
+</body>
+
+</html>
+```
+html代码内不需要引用资源文件，统一在与html文件名相同的js文件中引入。webpack会自动根据`plugin.json`中的`pages`里的js名称寻找构建html页面。
+
+js代码
+```javascript
+import '../../../js/m7_core/widgets/minirefresh/minirefresh.css';
+import '../../../js/m7_core/widgets/minirefresh/minirefresh.js';
+import '../../../js/m7_core/widgets/minirefresh/minirefresh.bizlogic.js';
+import '../css/minirefresh.css';
+
+(function () {
+    'use strict';
+    // 统一顶部使用import引入
+    Util.loadJs(function () {
+        initPage();
+    });
+
+    // 支持es5/es6
+    const initPage = () => {
+        new MiniRefreshBiz({
+            container:'#minirefresh',
+            url: '/request.php?action=testV7List',
+            listContainer: '#listdata',
+            dataRequest: function (currPage) {
+                return JSON.stringify({
+                    token: 'RXBvaW50X1dlYlNlcml2Y2VfKiojIzA2MDE=',
+                    params: {
+                        pageIndex: currPage,
+                        pageSize: 10,
+                        keyword: 'type1'
+                    }
+                });
+            },
+            dataChange: function (response) {
+                if (response.status.code == '200') {
+                    var outData = response.custom.infolist || [];
+                }
+                return outData;
+            },
+            itemClick: function (e) {
+                console.log("点击item");
+            }
+        });
+    }
+}());
+```
+
+css代码
+
+```
+
+/*
+ * 需要定制位置
+ */
+
+.minirefresh-wrap {
+    top: 0px !important;
+}
+
+.minirefresh-scroll {
+    background: #FFFFFF;
+}
+
+.data-list {
+    position: relative;
+    margin-top: 0;
+    margin-bottom: 0;
+    padding-left: 0;
+    list-style: none;
+    background-color: #fff;
+}
+
+.list-item {
+    position: relative;
+    overflow: hidden;
+    padding: 11px 15px;
+    -webkit-touch-callout: none;
+}
+
+.list-item:after {
+    position: absolute;
+    right: 0;
+    bottom: 0;
+    left: 15px;
+    height: 1px;
+    content: '';
+    -webkit-transform: scaleY(.5);
+    transform: scaleY(.5);
+    background-color: #c8c7cc;
+}
+
+.list-item:active {
+    background: #F5F5F5;
+}
+
+.msg-title {
+    display: block;
+    font-size: 15px;
+    margin: 5px;
+}
+
+.msg-fs14 {
+    font-size: 14px;
+    color: #999;
+}
+
+.msg-date {
+    float: right;
+    margin: 5px;
+}
+
+.list-item a,
+.navbar-header a {
+    text-decoration: none;
+    color: #18B4FE;
+}
+```
+## 解决调试跨域问题
+使用webpack可以依赖[devserver-proxy](https://www.webpackjs.com/configuration/dev-server/#devserver-proxy "devserver-proxy")插件解决**本地开发过程**中的跨域问题。小程序框架已经集成。
+
+在`build/webpack.dev.conf.js`中修改：
+```
+proxy: [{
+		context: ['/', '/pre/api'],  // 请求的接口名称
+		target: 'http://115.29.151.25:8012', // 需要跨域的接口地址
+		secure: false,
+		changeOrigin: true,
+		}]
+```
+
+在js页面中只需要请求接口名称，例如：
+```
+new MiniRefreshBiz({
+	...
+	url: '/pre/api',
+	...
+```
+
+重新启动`EPOINT TOOLS`中的`本地调试`即可。

package/docs/ejs-doc/promisesupport/promisesupport.md

@@ -0,0 +1,84 @@
+# Promise支持
+
+`EJS`中，大部分API都支持`Promise`
+
+注，有少部分API不支持`Promise`
+
+## 不支持`Promise`的API
+
+有少部分API因为涉及到多次回调（比如右上角按钮），所以不建议使用`Promise`
+
+如果强行要使用，这些API调用完毕后马上就会进入`then`
+
+以下是不支持`Promise`的长期回调`API`
+
+| JSAPI | 说明 |
+| :------------- |:-------------|
+| event.registerEvent | 注册事件监听 |
+| navigator.showSearchBar | 显示搜索栏，并监听搜索事件 |
+| navigator.hookSysBack | 拦截系统返回按钮 |
+| navigator.hookBackBtn | 拦截左侧导航栏返回按钮 |
+| navigator.setRightBtn | 设置并监听右侧按钮 |
+| navigator.setLeftBtn | 设置并监听左侧按钮 |
+| navigator.setRightMenu | 设置并监听右侧下拉菜单 |
+
+另外，一些全局调用，由于性质不一样，也不支持`Promise`，如
+
+- `ejs.config`，`ejs.ready`，`ejs.error`，`ejs.app`
+
+## 支持`Promise`的API调用示例
+
+注，除了不支持列表中的API，其它都支持`Promise`用法
+
+### 基本用法
+
+```js
+ejs.ui.alert({
+    title: '提示',
+    message: 'sd#ddd测试',
+    success: function(result) {
+        litemplate.showTips(JSON.stringify(result));
+    },
+    error: function(error) {
+        litemplate.showTips('失败:' + JSON.stringify(error));
+    }
+});
+```
+
+### Promise用法
+
+```js
+ejs.ui.alert({
+    message: "hello",
+}).then(function(result) {
+    console.log('点击alert成功，进入then');
+}).catch(function(error) {
+    console.error('失败:' + JSON.stringify(error));
+});
+```
+
+## 自定义API调用也支持`Promise`
+
+除了标准`API`外，调用自定义API`ejs.callApi`也支持`Promise`
+
+### 使用示例
+
+```js
+// 实际中请不要这样调用标准API，这里仅作为示例
+// 因为标准API除了调用外还有可能有其它的兼容处理，直接callApi无法达到那个目的
+ejs.callApi({
+    name: "pickDate",
+    mudule: 'ui',
+    data: {
+        datetime: '2017-07-25'
+    }
+}).then(function(result) {
+    console.log('成功选择时间：' + JSON.stringify(result) + ',进入then');
+}).catch(function(error) {
+    console.error('失败:' + JSON.stringify(error));
+});
+```
+
+- `callApi`也一样支持基本用法
+
+- 另外，当参数`isLongCb = 1`时，和最前面的长期回调一样，这时候`callApi`也同样不支持`Promise`

package/docs/ejs-doc/structure/structure.md

@@ -0,0 +1,26 @@
+# 架构
+
+## 多平台支撑架构图
+
+![](images/structure.jpg)
+
+
+## EJS容器架构图
+
+![](images/structure2.jpg)
+
+## 多平台支撑说明
+
+`EJS 4.x`支持多平台的调用，过程简述如下
+
+- 页面中运行代码`ejs.ui.alert('hello world!')`
+
+- 在用浏览器(或微信小程序)打开时，会判断当前环境为`H5`(或`miniprogram`)，于是进行API转换，转换成了`H5`(或`miniprogram`)下的`API命令`，浏览器执行`alert`在`H5`(或`miniprogram`)中的实现代码
+
+- 在用`EJS容器`打开时(比如扫一扫)，会判断当前环境为`EJS`，于是进行API转换，转换成了`EJS`环境下的`API命令`，命令发送到了`EJS`容器，容器执行`alert`的实现代码
+
+- 在用`DD容器`打开时(比如扫一扫)，会判断当前环境为`DD`，于是进行API转换，转换成了`DD`环境下的`API命令`，命令发送到了`DD`容器，容器执行`alert`的实现代码
+
+依靠上述的机制，实现了不同平台下的代码统一，如果进行不同平台下的移植转换时，相关代码无需改动
+
+注，如果没有引入相应平台下的API支持库，则无法正常调用

package/docs/ejs-doc/version/version.md

@@ -0,0 +1,62 @@
+# EJS API 版本控制管理
+
+部分`EJS`原生`API`调用时需要版本校验控制。移动前端页面调用`EJSAPI`时，会对`API`最低版本与`EJS`版本、APP版本不符合的`API`进行提示升级。
+
+## 场景说明
+
+### 场景一：普通API
+
+- 例如`ejs.miniH5.applyUpdate`，最低支持版本`ejs >= 4.0.2`。在容器EJS组件版本低于`4.0.2`，调用`ejs.miniH5.applyUpdate`时，页面会进行提示：
+
+`applyUpdate要求的容器EJS版本至少为:4.0.2，当前容器EJS版本：3.4.2.a21-SNAPSHOT，请升级`
+
+### 场景二：组件API
+
+- `ejs.util.invokePluginApi`，组件API。调用个性化API时，需要手动传入需要调用的API最低支持的APP版本`appVersion`，对APP版本进行校验。当APP版本低于传入的API最低版本时，错误回调返回错误信息。
+
+```js
+ejs.util.invokePluginApi({
+    path: 'contact.provider.localOperation',
+    dataMap: {
+        method: 'getOUAndUserList',
+        ouguid: ouguid
+    },
+  	appVersion: '4.0.0',
+    success: function(result) {
+        // result 返回数据
+    },
+    error: function(err) {
+        // err 错误信息
+    }
+});
+```
+在低于`4.0.0`版本的app中调用该组件，页面会进行提示：
+
+`getOUAndUserList要求的容器版本至少为:4.0.0，当前容器版本：3.5.0，请升级`
+
+### 场景三：自定义API
+
+- 在调用自定义API时，需要手动传入需要调用的API最低支持的APP版本`appVersion`，对APP版本进行校验。当APP版本低于传入的API最低版本时，错误回调返回错误信息。
+
+```js
+ejs.callApi({
+    name: 'alert', // 例如 alert（仅举例）
+    mudule: 'ui', // 例如 ui（仅举例）
+    isLongCb: 0, // 是否是长期回调
+    data: {}, // 需要传递给原生的数据
+  	appVersion: '4.0.0',
+    success: function(result) {
+        /**
+         * 长期回调的情况下，每次符合条件都会触发
+         * 短期回调的情况下，只会触发一次
+         * 回调的参数由具体的自定义API决定
+         */
+    },
+    error: function(error) {}
+});
+```
+
+在低于`4.0.0`版本的app中调用该API，页面会进行提示：
+
+`alert要求的容器版本至少为:4.0.0，当前容器版本：3.5.0，请升级`
+