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/005-/345/274/200/345/217/221/345/260/217/347/250/213/345/272/217/345/215/241/347/211/207.md

@@ -0,0 +1,307 @@
+# 开发小程序卡片
+
+## 前置条件
+
+### 1. 获取卡片标识
+
+在 `EMP8` 平台的`应用中心>卡片管理`创建一个小程序卡片应用，获取到卡片标识 `cardId`。
+
+首先，在**运营平台->应用中心->卡片管理**中，点击**新增卡片**，选择**小程序卡片**：
+
+![](assets/010/createMiniCard_1.png)
+
+填写好表单中的必填项，点击**确定**：
+
+![](assets/010/createMiniCard_2.png)
+
+在卡片列表中可以看到刚刚创建的小程序卡片，及其卡片标识 `cardId`：
+
+![](assets/010/createMiniCard_3.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`设置开放平台地址（SSO_URL地址，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`下，每个模块应用对应一个文件夹。
+
+我们在此路径下新建文件夹，例如 `carddemo`。
+
+`M8` 移动前端框架推荐使用 `SPA` 单页应用模式，所以我们的模块页面之间通过 `vue-router` 路由跳转。
+
+每一个页面可以当做一个`.vue` 来构建。当然，你也可以拆分成更细粒度的`.vue` 文件。
+
+在`carddemo`文件夹下新建`router.js`与`index.vue`文件以及`cardboot.js`：
+
+`index.vue`
+
+```html
+<!-- html部分 -->
+<template>
+    <div class="container">
+        <h1 @click="click">{{ message }}</h1>
+    </div>
+</template>
+
+<!-- js部分 -->
+<script>
+    // 小程序卡片构建时只会构建此vue文件,需要自行引入组件等
+    import { Util, Config } from './cardboot';
+
+    export default {
+        components: {},
+        props: {},
+        // 定义用到的数据，在template中使用{{ }}包裹，自动实现绑定
+        data() {
+            return {
+                message: 'hello world',
+                id: ''
+            };
+        },
+        // 计算属性
+        computed: {},
+        // 侦听属性
+        watch: {},
+        // 实例数据创建完成后调用
+        created() {},
+        // 实例DOM被挂载后调用
+        mounted() {
+            Config.configReady([], () => {
+                // M8.2.14之后小程序卡片相关逻辑在此之后执行
+                this.id = Util.getExtraDataByKey('xxx') || '';
+            });
+        },
+        // 实例销毁后调用
+        destroyed() {},
+        // 定义函数
+        methods: {
+            click() {
+                ejs.ui.toast(123);
+            }
+        }
+    };
+</script>
+
+<!-- css部分 -->
+<style scoped></style>
+<style lang="css">
+    @import '../../assets/css/common.css';
+    @import 'vant/lib/index.css';
+</style>
+```
+
+`router.js`
+
+用于定义页面地址`url`，当使用`vue-router`或`ejs`方法访问地址时，打开指向的模板文件。
+
+```js
+// 引入index组件
+import Index from './index.vue';
+
+// 定义路由规则，url匹配path时，加载component组件页面
+const routes = [
+    {
+        // 匹配到index时加载index组件
+        path: '/carddemo/index',
+        component: Index
+    },
+    {
+        // 只匹配到模块重定向指定首页
+        path: '/carddemo',
+        redirect: '/carddemo/index'
+    }
+];
+
+// 导出路由文件
+export default routes;
+```
+
+`cardboot.js`用来引入一些需要的资源或配置，如`ejs`、`Util`、`config`等。
+
+```js
+import 'vant/lib/icon/local.css';
+import Config from '@shared/config.js';
+import '@shared/ejs/ejsloader.vue';
+import Util from '@utils';
+import loaderLibrary from '@utils/loadlibrary';
+
+if (Config.isDebugPanel) {
+    loaderLibrary({
+        inject: 'head',
+        src: './lib/vconsole.min.js',
+        type: 'js'
+    });
+}
+
+if (Config.isTestPerformance) {
+    loaderLibrary({
+        inject: 'body',
+        src: './lib/performance.js',
+        type: 'js'
+    });
+}
+
+if (Config.isMock) {
+    require('@mock/index');
+}
+
+export { Util, Config };
+```
+
+此时我们完成了一个 `carddemo` 的页面开发。
+
+需要注意的是:
+
+1. 小程序卡片的内容要限定在 **创建卡片应用** 时确定的高度以内。
+
+2. 小程序卡片的入口文件不是`main.js`，需要的一些必要资源，如`ejs`、`config`，要手动引入。
+
+3. 小程序卡片的入口文件不是`main.js`，涉及业务地址的获取时，小程序卡片需要在入口文件中调用`Config.configReady`方法。
+
+更多有关页面编写的内容可查看[页面编写](?file=001-页面开发/004-页面编写 '页面编写')章节
+
+## > 第五步：配置模块信息
+
+创建好自己的小程序卡片模块后，需要在框架的配置文件 `plugin.json` 中配置各个小程序卡片模块的信息，如下图所示：
+
+![](assets/010/pluginCard.png)
+
+**注意**：此处与小程序不同的是:
+
+1. 小程序卡片入口文件固定为 `模块名/index`
+
+2. 要填写的是**卡片`ID`**
+
+3. `miniH5Type`字段的值为`card`，代表小程序卡片类型。
+
+**可配置的字段如下：**
+
+| 字段          | 说明                                                                   |
+| :------------ | :--------------------------------------------------------------------- |
+| moduleName    | 模块名称，必填                                                         |
+| indexURL      | 模块入口文件, 小程序卡片固定为`模块名/index`, 必填                     |
+| cardId        | 卡片`ID`，必填                                                         |
+| minEJSVersion | 支持的`EJS`最低版本，必填                                              |
+| version       | 应用版本，必填                                                         |
+| window        | 全局的导航栏配置，设置之后对整个小程序起作用，具体可查看小程序配置章节 |
+| miniH5Type    | 小程序三种形态，可选值为`app` `base` `card`                            |
+| updateType    | 小程序更新类型，可选值为`realtime` `nexttime`                          |
+| cardList      | 小程序卡片`ID`，原生根据此项配置加载对应的小程序卡片                   |
+
+更多可配置字段可查看[小程序配置](?file=010-新点小程序/004-小程序配置 '小程序配置')。
+
+## > 第六步：预览调试
+
+#### 本地调试
+
+本地调试，指的是通过 PC 端浏览器的模拟手机功能调试小程序应用。
+
+**方法 1**：通过 `M8-VSCODE-TOOL` 启动项目。安装项目依赖成功之后，点击**小程序-本地调试**，**输入启动的模块名称后**，默认浏览器会自动打开并访问`plugin.json`中该模块配置的项目首页 。
+
+![](assets/010/devCard.png)
+
+**方法 2**： 通过在项目根目录下执行如下命令启动项目。
+
+```
+npm run dev -- --模块名称
+```
+
+#### 手机预览
+
+手机调试，指的是临时生成应用调试二维码，通过客户端扫码调试应用。
+
+- 上传调试包
+
+通过 `M8-VSCODE-TOOL` 启动项目。安装项目依赖成功之后，点击**小程序-手机预览**，**输入启动的模块名称后**，插件根据设置的`EMP8`平台地址和账号密码上传调试包.
+
+![](assets/010/mobile_devCard.png)
+
+- 手机扫码
+
+上传调试包成功后，会自动跳出二维码，手机扫码即可实现手机预览。
+
+![](assets/010/mobile_dev2.png)
+
+**注：**
+
+- 在每次修改代码之后，需要重新打包上传成功后，扫描二维码才能查看更新内容
+- 预览调试的`debug`包不能当作`开发版本`手动上传到`EMP8`平台上，如果需要上传小程序，详见下文。
+
+## > 第七步：上传小程序卡片
+
+上传小程序卡片有`插件上传`和`手动上传`两种方式。
+
+**方式 1**
+
+#### 插件上传
+
+将小程序卡片代码根据模块分类，通过`webpack`构建成独立可运行的代码包至`dist`文件夹内，并且自动根据模块名称打包成小程序卡片压缩文件，上传至设定的`EMP8`平台内。
+
+- 代码构建
+
+通过 `M8-VSCODE-TOOL` 代码构建。安装项目依赖成功之后，点击**小程序-上传**，**输入上传的模块名称**，**小程序的版本号**后，插件会自动构建小程序卡片包。
+
+![](assets/010/update.png)
+
+![](assets/010/update2.png)
+
+- 自动上传
+
+待小程序卡片压缩包构建完成后，上传压缩包到指定平台的指定卡片小程序的开发版本下。
+![](assets/010/update3.png)
+
+**方式 2**
+
+#### 手动上传
+
+当上传接口报错无法自动上传时，可以使用平台的`版本发布`功能，将打包好的`zip`文件手动上传到平台。
+![](assets/010/mobile_upload1.png)
+
+## > 第八步：小程序卡片上架
+
+经过以上步骤上传小程序包后，小程序卡片需要上架才能在首页管理中获取创建的小程序卡片。
+
+1. 打开**应用中心->卡片管理**，找到创建的应用，点击**查看详情**:
+
+![](assets/010/groundingCard.png)
+
+2. 进入小程序卡片详情页面，在开发版本中可看到刚刚上传的小程序卡片，点击**推此版本上线**，即可将小程序卡片上架。
+
+![](assets/010/groundingCard2.png)
+
+![](assets/010/groundingCard3.png)

package/docs/m8mpdoc-develop/010-/346/226/260/347/202/271/345/260/217/347/250/213/345/272/217/006-/345/274/200/345/217/221/345/206/205/347/275/256/345/260/217/347/250/213/345/272/217.md

@@ -0,0 +1,222 @@
+# 开发内置小程序
+
+内置小程序是指无需通过 EMP8 平台管理，在 app 构建时直接打包放置在 app 某一功能模块中，以 H5 开发能力实现指定原生功能的小程序。
+
+## 前置条件
+
+- 由于内置小程序不通过`EMP8`平台进行管理，所以无需通过在`EMP8`平台创建小程序来获取小程序的`appId`，可自定义`appId`
+
+- 不过结合`EMP8`平台的`tab、portal`的配置能力，如果需要在`EMP8`平台创建应用模块，可在平台新建小程序设置`appId`为`xxx.local`，即可在`EMP8`平台上进行配置
+
+### 1. 准备开发环境
+
+- 根据[环境准备](?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)
+
+## > 第二步：初始化
+
+因开发包在本地运行需要依赖一些文件，需要先下载这些文件并安装。
+
+**方法 1**：在 `M8-VSCODE-TOOL` 中点击**初始化**以安装项目依赖。
+
+![](assets/010/001.png)
+
+**方法 2**：通过在项目根目录执行如下命令安装依赖包。
+
+```js
+ npm install
+```
+
+## > 第三步：页面编写
+
+内置小程序的页面编写方式与一般小程序相同。
+
+项目代码统一放在`src/pages`下，每个模块应用对应一个文件夹。
+
+我们在此路径下新建文件夹，例如`module`。
+
+`M8` 移动前端框架推荐使用 `SPA` 单页应用模式，所以我们的模块页面之间通过 `vue-router` 路由跳转。
+
+每一个页面可以当做一个`.vue` 来构建。当然，你也可以拆分成更细粒度的`.vue` 文件。
+
+在`module`文件夹下新建`router.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: 'hello world'
+            };
+        },
+        // 计算属性
+        computed: {},
+        // 侦听属性
+        watch: {},
+        // 实例创建完成后调用
+        created() {},
+        // 实例被挂载后调用
+        mounted() {},
+        // 实例销毁后调用
+        destroyed() {},
+        // 定义函数
+        methods: {}
+    };
+</script>
+
+<!-- css部分 -->
+<style scoped></style>
+```
+
+`router.js`定义页面的`url`访问路由对应展示的模板文件。
+
+文件内定义指向`module/helloworld`时展示`helloworld`组件
+
+```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`内拓展规则即可。
+
+更多有关页面编写的内容可查看[页面编写](?file=001-页面开发/004-页面编写 '页面编写')章节
+
+## > 第四步：配置模块信息
+
+创建好自己的小程序模块后，需要在框架的配置文件 `plugin.json` 中配置各个小程序模块的信息，如下图所示：
+
+![](assets/010/plugin.png)
+
+**可配置的字段如下：**
+
+| 字段          | 说明                                                                       |
+| :------------ | :------------------------------------------------------------------------- |
+| moduleName    | 模块名称，必填                                                             |
+| indexURL      | 模块入口文件, 必填                                                         |
+| appId         | 应用`ID`，必填                                                             |
+| minEJSVersion | 支持的`EJS`最低版本，必填                                                  |
+| version       | 应用版本，必填                                                             |
+| window        | 全局的导航栏配置，设置之后对整个小程序起作用，具体可查看小程序配置章节     |
+| miniH5Type    | 小程序三种形态，可选值为`app` `base` `card`                                |
+| updateType    | 小程序更新类型，可选值为`realtime` `nexttime`                              |
+| cardList      | 小程序卡片`ID`，原生根据此项配置加载对应的小程序卡片                       |
+| **pages**     | 内置小程序的子页面配置项，设置后对指定页面起作用，具体可查看小程序配置章节 |
+
+具体可查看[小程序配置](?file=010-新点小程序/004-小程序配置 '小程序配置')。
+
+## > 第五步：预览调试
+
+#### 本地调试
+
+本地调试，指的是通过 PC 端浏览器的模拟手机功能调试小程序应用。
+
+**方法 1**：通过 `M8-VSCODE-TOOL` 启动项目。安装项目依赖成功之后，点击**小程序-本地调试**，**输入启动的模块名称后**，默认浏览器会自动打开并访问`plugin.json`中该模块配置的项目首页 。
+
+![](assets/010/dev.png)
+
+**方法 2**： 通过在项目根目录下执行如下命令启动项目。
+
+```
+npm run dev -- --模块名称
+```
+
+#### 手机扫码实时调试
+
+手机在线扫码调试，指的是临时生成应用调试二维码，**使用对应项目并支持小程序 2.0 的 APP 客户端扫码调试应用。**
+
+- 首先需要将模块在本地启动，参考**本地调试**方法实现。
+
+- 之后需要使用二维码生成工具按照以下格式生成二维码。
+
+```js
+h5://appid.ecdebug:inner?页面本地地址
+```
+
+![](assets/010/mobile_dev3.png)
+
+- 最后，使用 APP 客户端扫码即可实现实时调试。
+
+![](assets/010/mobile_dev4.jpg)
+
+_注：在线调试页面右上角的胶囊按钮是固定存在的，无法通过`plugin.json`配置去除。_
+
+## > 第六步：小程序内置化
+
+小程序内置化的方式可分为`持续集成平台构建`和`小程序本地构建`两种方式。
+
+**方式 1**
+
+#### 持续集成平台构建
+
+持续集成平台构建，是指利用持续集成开发平台的集成开发能力，自动引入小程序和原生代码进行打包，最终构成 app 安装包。
+
+1. 在项目开发初期，H5 开发要与原生约定好存储代码的`git`**仓库地址，分支名称**，以及需要内置进入 app 包的小程序的`appId`交由项目开发负责人或原生进行配置；
+
+    ![](assets/010/mobile_build1.png)
+
+2. H5 开发在按照开发进程完成阶段性开发后，要及时将代码上传到指定的`git`仓库中;
+
+3. 在[持续集成开发平台](https://dev.epoint.com.cn:5888/clouddev-web/frame/fui/pages/themes/clouddev/clouddev)中“选中项目>持续集成>构建计划>选择系统>开始构建”
+
+    ![](assets/010/mobile_build2.png)
+
+4. 最后在`查看制品`中可以查阅每次构建后生成的压缩包和安卓包，开发人员可以选择`下载`，将安装包上传到`EMP8`平台上进行测试和上架。
+
+    ![](assets/010/mobile_build3.png)
+
+    ![](assets/010/mobile_build4.png)
+
+**方式 2**
+
+#### 小程序本地构建
+
+小程序本地构建是直接向原生提供使用`VScode`插件打包生成的小程序构建包，由原生手动将构建包放置在 app 内。
+
+**由于此种方式容易出错，除需要调试某个特定版本的内置小程序之外，并不推荐此方式内置小程序。**
+
+代码构建同一般小程序一致，将小程序代码根据模块分类，通过`webpack`构建成独立可运行的代码包至`dist`文件夹内，并且自动根据模块名称打包成小程序压缩文件。
+
+通过 `M8-VSCODE-TOOL` 代码构建。安装项目依赖成功之后，点击**小程序-上传**，**输入上传的模块名称**，**小程序的版本号**后，插件会自动构建小程序包，最后无需考虑上传到`EMP8`平台，只需在`dist`文件夹下拿到构建好的压缩包，传递给原生即可。
+
+![](assets/010/update.png)
+
+![](assets/010/update2.png)