m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/010-/346/226/260/347/202/271/345/260/217/347/250/213/345/272/217/001-/345/260/217/347/250/213/345/272/217/345/256/277/344/270/273/347/216/257/345/242/203.md

@@ -0,0 +1,196 @@
+# 小程序基本介绍
+
+
+## 小程序框架结构
+
+![](assets/010/image_env.png)
+
+## 小程序更新加载机制
+
+小程序容器允许访问一段特殊的协议，以此来加载小程序，协议内容如下：
+
+```
+h5://appId
+```
+**协议参数说明**
+
+| 参数名称 | 说明 |
+| :------------- |:-------------:|
+| appId | 小程序的唯一标识 |
+
+小程序容器可以通过扫一扫、或者直接加载该地址可以打开小程序。
+
+
+## 组件
+组件是小程序提供给开发者来方便创建常用的页面`UI`的。开发者可以以灵活的方式自由组合各种组件，去构建属于自己的页面`UI`。
+
+就像`HTML`的标签一样，在小程序里，开发者在`HTML`里写上对应组件的标签，就能显示出来。例如：
+
+```
+<van-button type="primary">主要按钮</van-button>
+```
+
+更多组件内容可以参考[UI组件](?file=009-UI组件/005-button按钮 "UI组件")。
+
+## API
+为了让开发者很方便的使用新点小程序提供的能力，例如获取用户授权码，获取设备信息，播放视频等等。小程序基于ejs框架提供了很多API供开发者使用，所有API均为异步调用，通过回调返回结果。
+
+例如获取用户授权码：
+```
+ejs.auth.getAuthCode({
+    success: function(result) {
+        /**
+         * {
+            authCode: '用户授权码'
+           }
+         */
+    },
+    error: function(error) {}
+});
+```
+
+更多API相关的内容可以参考 [EJS相关](?file=004-EJS相关/001-EJS3.X "EJS相关")。
+
+## 小程序运行机制
+
+### 小程序内存保活
+&nbsp;&nbsp;&nbsp;&nbsp;小程序拥有独立的内存保活列表，用户通过应用中心、应用搜索、扫一扫等原生界面的交互来打开小程序，这时候小程序栈会被标记为进入内存保活列表，在用户点击胶囊按钮关闭操作的时候，小程序不会在关闭动画结束后进行销毁，而是进入内存保活列表，直到用户再次访问该小程序，内存保活中的小程序才会被唤醒。
+
+
+### 小程序生命周期
+
+![](img/image_system.png)
+
+小程序的生命周期包含以下事件：onLaunch，onShow，onHide，onClose，可以通过如下前端代码进行注册：
+```
+ejs.app({
+  onLaunch: function(){
+    // todo ...
+  },
+  onShow: function(){
+    // todo ...
+  },
+  onHide: function(){
+    // todo ...
+  },
+  onClose: function(){
+    // todo ...
+  },
+});
+```
+我们将一个小程序看作一个栈，一个栈下可以拥有多个子页面，每张页面可以对自身的生命周期事件进行拦截。
+
+
+## 小程序风格适配
+
+小程序支持多种风格来满足开发者不同风格的需求，小程序除了胶囊按钮区域，其余全部可以个性化。
+
+<div class="halfW">
+
+![](assets/010/image_demo.png)
+
+</div>
+
+### 风格说明
+小程序支持两种风格："white"，"blue"，默认为 white 风格。
+
+<div class="halfW">
+**Blue:**
+![](assets/010/image_blue.png)
+
+<br>
+**White:**
+![](assets/010/image_white.png)
+
+</div>
+
+开发者可以通`plugin.json`文件中的配置参数 `window` ，对小程序设计风格进行配置。
+
+```js
+{
+    "moduleName": "module",
+    "indexURL": "module/index",
+    "appId": "xxxx",
+    "minEJSVersion": "4.0.0", // 支持的EJS最低版本
+    "version": "1.0.2",
+    "window": {// 全局的，设置之后对整个小程序起作用
+        "navigationBarBackgroundColor": "#000000",
+        "navigationBarTextStyle": "导航栏标题颜色，仅支持 blue / white",
+        "navigationBarTitleText": "导航栏标题文字内容",
+        "navigationStyle": "default/custom/translucent", // 导航栏样式，默认为 default，如果设置为 “custom”，则导航栏隐藏，仅保留胶囊按钮部分
+        "navigationBarToolBarStyle": "hidden" // 隐藏胶囊按钮
+    },
+    "miniH5Type": "app", // 'app'/'base'/'card'
+    "updateType": "realtime/nexttime", // 更新类型，实时/静默
+}
+```
+**参数说明**
+
+| 参数名称 | 描述 |
+| :------------- |:-------------:|
+| window.navigationBarBackgroundColor | 小程序全局导航栏背景色 |
+| window.navigationBarTextStyle | 小程序全局导航栏的文本风格，仅支持`blue/white` |
+| window.navigationBarTitleText | 小程序全局导航栏的标题 |
+| window.navigationStyle | 小程序全局导航栏的风格，仅支持`default/custom`，默认为 `default`，如果设置为 `custom`，则导航栏隐藏，仅保留胶囊按钮部分 |
+| window.navigationBarToolBarStyle | 隐藏胶囊按钮，可选值`hidden` |
+
+### 使用QueryString参数修改风格
+调用示例
+```
+ejs.page.open("./module_qs_setTitle.html?ejs_pagetitle=测试标题");
+```
+
+**支持的queryString参数说明**
+
+| 参数名称 | 描述 |
+| :------------- |:-------------:|
+| ejs_pagestyle | -1 导航栏隐藏，2 导航栏透明，仅保留返回键、标题和胶囊按钮部分 |
+| ejs_nav_bgcolor | 设置导航栏背景色 |
+| ejs_pagetitle | 设置导航栏标题 |
+| ejs_nav_style | 小程序风格，仅支持 `blue/white` 风格，默认为 `white` |
+
+### 使用API修改风格
+小程序也提供了新的 `API` 来修改小程序风格。
+
+#### setNavigationBarTitle
+设置导航栏的标题
+
+调用示例：
+```
+ejs.miniH5.setNavigationBarTitle({
+    title:"页面标题"
+});
+```
+**参数说明**
+
+| 参数名 | 类型 | 说明 |
+| :------------- |:-------------:|:-------------:|
+| title | String | 导航栏标题名称 |
+
+#### setNavigationBarColor
+设置导航栏背景色、风格
+
+调用示例：
+```
+ejs.miniH5.setNavigationBarColor({
+    "frontColor":"blue",
+    "backgroundColor":"#ff0000"
+});
+```
+**参数说明**
+
+| 参数名 | 类型 | 说明 |
+| :------------- |:-------------:|:-------------:|
+| frontColor | String | 前景色，支持设置胶囊按钮，标题，状态栏的风格，仅支持 `blue`、`white` |
+| backgroundColor | HexString | 导航栏背景色 |
+
+### 风格设置优先级
+<div class="halfW">
+![](assets/010/image_style.png)
+
+</div>
+
+说明：
+- 小程序优先根据 `plugin.json` 进行配置
+- 之后会根据 `QueryString` 参数进行配置
+- 最后再根据 `API` 调用进行配置

package/docs/m8mpdoc-develop/010-/346/226/260/347/202/271/345/260/217/347/250/213/345/272/217/003-/345/274/200/345/217/221/345/260/217/347/250/213/345/272/217.md

@@ -0,0 +1,267 @@
+# 开发小程序
+
+## 前置条件
+
+### 1. 获取应用`appId(AppKey)`
+
+首先，在**运营平台->应用中心->应用管理**中，点击**新建应用**，选择**小程序**：
+
+![](assets/010/createMiniApp_1.png)
+
+填写好表单中的必填项，点击**确定**：
+
+![](assets/010/createMiniApp_2.png)
+
+在小程序应用的所属分类中可以看到刚刚创建的小程序应用：
+
+![](assets/010/createMiniApp_3.png)
+
+点击**查看详情**，可获取小程序的`Appkey`:
+
+![](assets/010/createMiniApp_4.png)
+
+### 2. 准备开发环境
+
+- 根据[环境准备](?file=0001-前期准备/000-环境准备 '环境准备')章节搭建好开发环境
+- 根据[VSCode 插件](?file=0001-前期准备/004-VSCode插件 'VSCode插件')章节下载安装`M8`移动前端框架插件
+- 根据[框架获取](?file=001-页面开发/000-框架获取 '框架获取')章节获取移动前端`M8`框架
+
+## > 第一步：导入项目
+
+打开开发模板：打开`VSCode`，选择“文件 > 打开文件夹”，选择框架所在的文件夹打开。
+
+![](https://fdoc.epoint.com.cn/onlinedoc/rest/frame/base/attach/attachAction/getContent?isCommondto=true&attachGuid=1478d4c0-8f5d-4143-a183-3f760ab1485d)
+
+## > 第二步：设置`EMP8`平台信息
+
+在 `M8-VSCODE-TOOL` 中点击“设置”以设置相关信息。以下小程序预览和上传步骤都会将小程序包上传至填入的`EMP8`平台。
+
+`domain`设置开放平台地址（EMP开放平台地址，VSCode开发插件通过`domain`地址获取EMP平台前缀地址）
+
+ `clientId`设置应用唯⼀标识（AppKey）
+
+`clienttSecret`设置应用秘钥（AppSecret）
+
+![](assets/010/setting.png)
+
+## > 第三步：初始化
+
+因开发包在本地运行需要依赖一些文件，需要先下载这些文件并安装。
+
+**方法 1**：在 `M8-VSCODE-TOOL` 中点击**初始化**以安装项目依赖。
+
+![](assets/010/001.png)
+
+**方法 2**：通过在项目根目录执行如下命令安装依赖包。
+
+```js
+ npm install
+```
+
+## > 第四步：页面编写
+
+项目代码统一放在`src/pages`下，每个模块应用对应一个文件夹。
+
+我们在此路径下新建文件夹，例如`module`。
+
+`M8` 移动前端框架推荐使用 `SPA` 单页应用模式，所以我们的模块页面之间通过 `vue-router` 路由跳转。
+
+每一个页面可以当做一个`.vue` 来构建。当然，你也可以拆分成更细粒度的`.vue` 文件。
+
+在`module`文件夹下新建`router.js`,`store.js`与`helloworld.vue`文件：
+
+`helloworld.vue`
+
+```html
+<!-- html部分 -->
+<template>
+    <div class="container">
+        <h1>{{ message }}</h1>
+    </div>
+</template>
+
+<!-- js部分 -->
+<script>
+    export default {
+        components: {},
+        props: {},
+        // 定义用到的数据，在template中使用{{ }}包裹，自动实现绑定
+        data() {
+            return {
+                message: ''
+            };
+        },
+        // 计算属性
+        computed: {},
+        // 侦听属性
+        watch: {},
+        // 实例创建完成后调用
+        created() {},
+        // 实例被挂载后调用
+        mounted() {},
+        // 实例销毁后调用
+        destroyed() {},
+        // 定义函数
+        methods: {}
+    };
+</script>
+
+<!-- css部分 -->
+<style lang="scss" scoped></style>
+```
+
+`router.js`
+
+用于定义页面地址`url`，当使用`vue-router`或`ejs`方法访问地址时，打开指向的模板文件。
+
+```js
+// 引入helloworld组件
+import HelloWorld from './helloworld.vue';
+
+// 定义路由规则，url匹配path时，加载component组件页面
+const routes = [
+    {
+        // 匹配到helloworld时加载helloworld组件
+        path: '/module/helloworld',
+        component: HelloWorld
+    },
+    {
+        // 只匹配到模块重定向指定首页
+        path: '/module',
+        redirect: '/module/helloworld'
+    }
+];
+
+// 导出路由文件
+export default routes;
+```
+
+此时我们完成了一个 `helloworld` 的页面开发。
+
+后续页面只需要在模块内新建`.vue`单文件组件，在`router.js`内拓展规则即可。
+
+`store.js`
+
+使用`vuex`前端状态管理库，实现对数据获取，存储和传递的有效控制。具体参考`vuex`
+相关语法。
+
+```js
+export default {
+    // 独立命名名称
+    moduleName: 'module',
+    // 使用独立命名空间
+    namespaced: true,
+    state: {
+        moduleInfo: '状态信息'
+    },
+    mutations: {
+        setModuleInfo(state, data) {
+            state.moduleInfo = data;
+        }
+    }
+};
+```
+
+更多有关页面编写的内容可查看[页面编写](?file=001-页面开发/004-页面编写 '页面编写')章节
+
+## > 第五步：配置模块信息
+
+创建好自己的小程序模块后，需要在框架的配置文件 `plugin.json` 中配置各个小程序模块的信息，如下图所示：
+
+![](assets/010/plugin.png)
+
+**可配置的字段如下：**
+
+| 字段          | 说明                                                                   |
+| :------------ | :--------------------------------------------------------------------- |
+| moduleName    | 模块名称，必填                                                         |
+| indexURL      | 模块入口文件, 必填                                                     |
+| appId         | 应用`ID`，必填                                                         |
+| minEJSVersion | 支持的`EJS`最低版本，必填                                              |
+| version       | 应用版本，必填                                                         |
+| window        | 全局的导航栏配置，设置之后对整个小程序起作用，具体可查看小程序配置章节 |
+| miniH5Type    | 小程序三种形态，可选值为`app` `base` `card`                            |
+| updateType    | 小程序更新类型，可选值为`realtime` `nexttime`                          |
+
+具体可查看[小程序配置](?file=010-新点小程序/004-小程序配置 '小程序配置')。
+
+## > 第六步：预览调试
+
+#### 本地调试
+
+本地调试，指的是通过 PC 端浏览器的模拟手机功能调试小程序应用。
+
+**方法 1**
+
+通过 `M8-VSCODE-TOOL` 启动项目。安装项目依赖成功之后，点击**小程序-本地调试**，**输入启动的模块名称后**，默认浏览器会自动打开并访问`plugin.json`中该模块配置的项目首页 。
+
+![](assets/010/dev.png)
+
+**方法 2**
+
+通过在项目根目录下执行如下命令启动项目。
+
+```
+npm run dev -- --模块名称
+```
+
+#### 手机预览
+
+手机预览，指的是利用`M8-VSCODE-TOOL`在`VSCode`页面生成临时的应用调试二维码，然后**使用对应项目的 APP 客户端扫码调试。**
+
+通过 `M8-VSCODE-TOOL` 启动项目。安装项目依赖成功之后，点击**小程序-手机预览**，**输入启动的模块名称后**，插件根据设置的 EMP8 平台地址和账号密码，上传调试包临时生成二维码。
+
+![](assets/010/mobile_dev.png)
+
+上传调试包成功后，会自动跳出二维码，手机扫码即可实现手机预览。
+
+![](assets/010/mobile_dev2.png)
+
+**注：**
+
+- 在每次修改代码之后，需要重新打包上传成功后，扫描二维码才能查看更新内容
+- 预览调试的`debug`包不能当作`开发版本`手动上传到`EMP8`平台上，如果需要上传小程序，详见下文。
+
+## > 第七步：上传小程序
+
+上传小程序卡片有`插件上传`和`手动上传`两种方式。
+
+**方式 1**
+
+#### 插件上传
+
+代码构建，将小程序代码根据模块分类，通过`webpack`构建成独立可运行的代码包至`dist`文件夹内，并且自动根据模块名称打包成小程序压缩文件，上传至设定的`EMP8`平台内。
+
+- 代码构建
+
+通过 `M8-VSCODE-TOOL` 代码构建。安装项目依赖成功之后，点击**小程序-上传**，**输入上传的模块名称**，**小程序的版本号**后，插件会将小程序包构建，上传至 EMP8 平台。
+
+![](assets/010/update.png)
+
+![](assets/010/update2.png)
+
+- 自动上传
+
+待小程序卡片压缩包构建完成后，上传压缩包到指定平台的指定卡片小程序的开发版本下。
+![](assets/010/update3.png)
+
+**方式 2**
+
+#### 手动上传
+
+当上传接口报错无法自动上传时，可以使用平台的`版本发布`功能，将打包好的`zip`文件手动上传到平台。
+![](assets/010/mobile_upload1.png)
+
+## > 第八步：小程序上架
+
+经过以上步骤上传小程序包后，小程序需要上架才能在应用中心中看到创建的小程序。
+
+1. 打开**应用中心->应用管理**，找到创建的应用，点击**查看详情**:
+
+![](assets/010/grounding.png)
+
+2. 进入小程序详情页面，查看**版本管理**，在开发版本中可看到上传的小程序，点击**推此版本上线**，即可将小程序上架。
+
+![](assets/010/grounding2.png)
+
+![](assets/010/grounding3.png)

package/docs/m8mpdoc-develop/010-/346/226/260/347/202/271/345/260/217/347/250/213/345/272/217/004-/345/260/217/347/250/213/345/272/217/351/205/215/347/275/256.md

@@ -0,0 +1,71 @@
+# 小程序配置
+
+### 配置文件说明
+
+打包后的小程序必须包含 `plugin.json` 文件，该文件描述了当前包、外观等信息，`plugin.json` 不可有注释信息。
+
+```js
+{
+    "moduleName": "comdemo", // 小程序名称
+    "indexURL": "comdemo/index", // 小程序首页入口路径，必填
+    "appId": "f1ac3a7f-d76a-4ff1-bb50-722bf0518ed1", // 小程序唯一标识，必填
+    "minEJSVersion": "3.5.0", // 支持的EJS最低版本
+    "version": "1.0.2", // 小程序版本号，必填，或者检测versionName
+    "window": {// 全局配置，设置之后对整个小程序起作用（请勿在小程序卡片配置文件中配置window字段）
+        "navigationBarBackgroundColor": "#000000", // 导航栏背景色
+        "navigationBarTextStyle": "white / blue", // white(默认) 代表：导航栏白色系风格，状态栏文字、标题文字、返回键黑色; blue 代表：导航栏暗色系风格，状态栏文字、标题文字、返回键白色
+        "navigationBarTitleText": "", // 导航栏标题文字内容
+        "navigationStyle": "default/custom/translucent", // 导航栏样式，默认为 default，如果设置为 “custom”，则导航栏隐藏，仅保留胶囊按钮部分，“translucent”为导航栏透明
+        "navigationBarToolBarStyle": "hidden", // 隐藏胶囊按钮
+        "navigationBarBackStyle": "show", // 设置首页是否显示返回键
+        "navigationBarLayoutFromStatusBar": "auto" // auto是从状态栏下开始布局，默认：从屏幕顶部开始布局
+    },
+    "miniH5Type": "app", // 小程序类型，支持'app'/'card'，默认app
+    "updateType": "realtime/nexttime", // 更新类型，实时/静默，默认nexttime
+    "keepInMemory": "alive/dead", // 内存保活，如果配置dead，不进行内存保活，默认alive，
+    "keepInterval": "3600" // 内存保活的时长，单位s秒，默认为3600
+    // 内置小程序子页面配置
+    "pages":[
+        {
+            "path":'',// 子页面路由
+            // 子页面的导航栏/胶囊按钮/布局形式的个性化设置，配置项与全局window相同
+            "window":{}
+        }
+    ]
+}
+```
+
+**参数说明**
+
+| 参数名称      |                                                                              描述                                                                              |
+| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| moduleName    |                                                                         模块名称，必填                                                                         |
+| indexURL      |                                                       模块入口文件，小程序卡片固定为`模块名/index`, 必填                                                       |
+| appId         |                                                                 应用`ID`，卡片小程序不需要填写                                                                 |
+| cardId        |                                                                卡片`ID`，只有卡片小程序需要填写                                                                |
+| minEJSVersion |                                                                   支持的`EJS`最低版本，必填                                                                    |
+| version       |                                                                         应用版本，必填                                                                         |
+| versionName   |                             含义与`version`相同，如果存在`version`字段优先使用`version`字段，否则尝试读取并使用 `versionName`字段                              |
+| window        |           全局的导航栏配置，设置之后对整个小程序起作用，<br>具体可查看客户端开发指南小程序风格章节,选填(请勿在小程序卡片配置文件中配置 window 字段)            |
+| miniH5Type    |                                                           小程序二种形态，可选值为`app` `card`，必填                                                           |
+| updateType    |                                                      小程序更新类型，可选值为`realtime` `nexttime`，必填                                                       |
+| keepInMemory  | 小程序是否进入内存保活，可选值为 ` dead``alive `，默认为 `alive`，如果配置`dead`，本该进入内存保活的小程序不会进入，并且如果内存保活中有小程序则会被移除，选填 |
+| keepInterval  |                                内存保活的时长，单位`s`秒，默认为 `3600`，只允许填写 `<= 3600` 的值，`> 3600` 则使用默认值，选填                                |
+
+<!-- |cardList|小程序卡片`ID`，原生根据此项配置加载对应的小程序卡片，选填| -->
+
+**小程序二种形态（miniH5Type）**
+
+- `app`：应用小程序，上传应用中心的小程序应用（这是一种标准的小程序形态，右上角有“胶囊”按钮）。
+
+- `card`：卡片小程序，以小程序技术为支撑开发的卡片。
+
+**小程序的更新类型（updateType）**
+
+`realtime`: 实时更新，即在打开小程序时，若发现有新版本，立即更新小程序。
+
+`nexttime`: 静默更新，即在打开小程序时，若发现有新版本，则进行静默更新，不会有加载动画。
+
+<!-- **小程序卡片列表（cardList）**
+
+小程序中若需要使用其他卡片小程序，可使用组件 `cardrender` 渲染小程序卡片，只需将卡片`id`传入组件，即可自动加载卡片小程序，具体可查看**小程序组件->cardrender 渲染小程序卡片**章节。在小程序配置中，要将需要的卡片小程序的卡片`id`在`cardList`字段中列出。 -->