m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/015-/345/267/245/347/250/213/345/214/226/customize.md

@@ -0,0 +1,283 @@
+# 移动端二次个性化开发机制
+
+
+## 背景：
+
+产品与项目开发过程中，会存在一些个性化需求，往往是侵入式修改产品代码，导致产品代码不可维护，升级产品时需要重新修改个性化代码，增加维护成本。
+
+移动前端跨端框架在`v8.3.10`版本之后提供个性化代码隔离方案，可以将个性化代码与产品代码隔离，不侵入产品代码进行个性化修改，便于升级产品时不需要重新修改个性化代码。
+
+![](assets/015/custom.png)
+
+::: ifdef M84
+## 1.个性化实现路径：
+
+- config.js中提供`isCustomize`配置，配置为`true`时开启个性化功能，默认为`false`
+
+- 移动前端工程下提供`custom`个性化目录，与src目录、node_modules目录同级
+
+- 支持个性化 `src` 目录和 `node_modules/@epoint-mrc` 目录，用于个性化工程代码和框架依赖代码
+
+## 2.个性化功能：
+
+- 代码工程构建时 `src`、`node_modules/@epoint-mrc` 路径下文件与 `custom` 文件匹配，存在同路径同名文件时进行读取 `custom` 文件内容。
+
+## 3.目录结构
+
+```
+├── node_modules
+│   ├── @epoint-mrc
+│   │   ├── em-components
+|   │   │   ├── xxx.vue
+├── custom                     // 个性化目录
+│   ├── src
+│   │   ├── pages
+│   │   │  ├── index
+│   │   │  │   ├── index.vue   // 个性化覆盖代码工程同路径index.vue文件
+│   ├── node_modules
+│   │   ├── @epoint-mrc
+│   │   │  ├── em-components
+|   │   │  │   ├── xxx.vue     // 个性化覆盖框架xxx组件
+├── src
+│   ├── pages
+│   │  ├── index
+│   │  │   ├── index.vue   // 个性化覆盖代码工程同路径index.vue文件
+├── package.json
+```
+
+
+::: endif
+::: ifdef M83
+## 1.个性化实现路径：
+
+- config.js中提供`isCustomize`配置，配置为`true`时开启个性化功能，默认为`false`
+
+- 移动前端工程下提供`customize`个性化目录，与src目录同级
+
+```bash
+ejs.m8.mobileframe
+├─build
+├─customize   // 新增：个性化开发路径customize
+├─public
+├─src
+├─.editorconfig
+├─.eslintignore
+├─.eslintrc.js
+├─.gitignore
+├─plugin.json
+├─package.json
+├─README.md
+└─vue.config.js
+```
+
+- 代码工程构建加载src路径下文件时会与`customize`文件进行匹配，存在同路径同名文件时进行**构建过程处理**，不对原始文件进行修改，无需变动页面路由。
+
+<!-- img -->
+![](assets/015/custom.png)
+
+## 2.个性化文件类型支持功能：
+
+### 2.1 vue文件：
+
+- 支持全局替换
+
+- script支持替换、方法支持重写
+
+- template支持替换
+
+- style支持替换、插入
+
+
+### 2.2 js文件：
+
+- 支持全局替换
+
+- 支持导入源文件继承修改后导出
+
+### 2.3 css文件：
+
+- 全局替换
+
+- 支持插入
+
+
+### 2.4 其他文件：
+
+- 全局替换
+
+## 3.个性化文件代码开发：
+
+### 3.1 js文件：
+
+#### 3.1.1 全局替换
+
+默认会将个性化文件替换原始文件。
+
+#### 3.1.2 继承：
+
+支持`import`或`require`源文件，使用`{{@originalFilePath}}`，在构建时框架会将`{{@originalFilePath}}`替换为源文件路径，例如：
+
+```js
+// 使用{{@originalFilePath}}，在构建时框架会将{{@originalFilePath}}替换为源文件路径
+import  routerDefault from '{{@originalFilePath}}';
+
+routerDefault.routes.push({
+    path: 'pages/xxx/xxx', // 注意个性化文件的路径定义仍然为src下的路径
+    style: {
+        navigationBarTitleText: 'xxx'
+    }
+});
+
+// 导出路由文件
+export default routerDefault;
+```
+
+### 3.2 css文件：
+
+在个性化css文件头部添加注释，明确个性化类型。例如全局替换还是插入等。
+
+#### 3.2.1 全局替换
+
+```css
+/* {'customMixType': 'global'} */
+```
+
+#### 3.2.2 插入
+
+```css
+/* {'customMixType': 'append'} */
+```
+
+插入类型时，会将个性化css文件插入到原始css文件后面。
+
+### 3.3 vue文件：
+
+#### 3.3.1 全局替换
+
+按照正常开发vue组件，框架会将个性化vue组件替换原始文件。
+
+#### 3.3.2 部分替换
+
+可以单独只写需要替换的SFC部分，只替换对应部分。
+
+例如：
+
+1. 只需要替换template部分，script、style部分不需要修改，无需写script、style部分
+
+```html
+<template>
+<!-- xxx -->
+</template>
+```
+
+2. 只需要替换script部分，template、style部分不需要修改，无需写template、style部分
+
+```html
+<script>
+// xxx
+</script>
+```
+
+script部分支持重写方法，例如：
+
+```html
+<script>
+// {{@originalFilePath}}会被替换为源文件路径
+import origin from '{{@originalFilePath}}';
+
+export default {
+    // 先将原有属性方法继承
+    ...origin,
+    data() {
+        return {
+            ...origin.data(),
+            // 重写data.title
+            title: '页面跳转2'
+        };
+    },
+    methods: {
+        ...origin.methods,
+        // 重写click方法
+        click() {
+            // xxx
+        }
+    }
+    // 其他重写类似，对原有属性进行重写
+};
+</script>
+```
+
+3. 只需要替换style部分，script、template部分不需要修改，无需写script、template部分
+
+style部分默认为替换原始css。支持`customMixType`为`append`的属性，`append`会将个性化css插入到原始css后面。
+
+```html
+<style scoped  customMixType="append">
+/* xxx */
+</style>
+```
+
+4. 其他文件：
+
+    全局替换
+
+## 示例
+
+对`src/modules/m8showcase/`框架UI组件示例模块进行个性化开发，新增个性化示例页面。
+
+只需在`customize`下新建`customize/modules/m8showcase`目录，对需要个性化的部分进行开发即可。
+
+### 新增路由页面
+
+在`customize/modules/m8showcase`目录下新建`router.js`文件，对路由进行个性化开发。
+
+```js
+// 使用@originalFilePath，在构建时框架会将@originalFilePath替换为源文件路径
+import  routerDefault from '{{@originalFilePath}}';
+
+routerDefault.routes.push({
+    path: 'modules/m8showcase/examples/customize',
+    style: {
+        navigationBarTitleText: '个性化示例'
+    }
+});
+
+// 导出路由文件
+export default routerDefault;
+```
+
+### 修改示例列表页面
+
+在`customize/modules/m8showcase`目录下新建`customize/modules/m8showcase/index.vue`文件，对原有vue进行继承个性化开发。
+
+```html
+<script>
+import origin from '{{@originalFilePath}}';
+
+export default {
+    ...origin,
+    data() {
+        return {
+            ...origin.data(),
+            activeNames: [1, 2, 3, 4, 5, 6, 7, 8]
+        };
+    },
+    mounted() {
+        this.menu.push({
+            title: '个性化示例',
+            children: [
+                {
+                    title: '个性化页面',
+                    to: 'examples/customize'
+                }
+            ]
+        });
+    }
+};
+</script>
+```
+
+### 新增examples/customize页面
+
+在`customize/modules/m8showcase`目录下新建`customize/modules/m8showcase/examples/customize.vue`文件，新增具体个性化页面内容。
+::: endif

package/docs/m8mpdoc-develop/015-/345/267/245/347/250/213/345/214/226/customtoken.md

@@ -0,0 +1,74 @@
+# 自定义 token 最佳实践
+
+跨端框架中进行自定义获取 token 功能：
+
+在 Config.js 中，token 对象中可以配置是否开启自定义 token、获取自定义 token、刷新自定义 token 功能。
+
+`8.3.11` 版本中，增加了自定义 token 刷新失败处理。
+
+## 最佳实践：
+
+-   开启自定义 `isUseSelfToken` 配置；
+-   `getToken` 中实现自定义 token 获取逻辑，返回 Promise 对象，resolve 中返回 token；（自定义 token 获取过程需要做好 token 缓存功能，存在 token 返回缓存的 token，不存在或需要刷新时再动态获取）
+-   `refreshToken` 中实现刷新自定义的 token 获取逻辑
+-   `refreshTokenCountExceeded` 中实现自定义刷新失败处理
+
+### 注意：
+
+由于Util工具库依赖config.js文件，所以无法在congif.js中直接调用Util工具库，会造成构建时循环依赖引用。
+
+需要将与Util相关逻辑单独在外部js中实现，在config.js中引入，并在config.js中调用。
+
+## 示例：
+```js
+token: {
+    // 是否使用自定义token，可以用于非ejs环境下的token赋值刷新，影响到所有Util.ajax与下拉刷新请求
+    isUseSelfToken: true,
+    // 可以是字符串，也可以是方法
+    // 非ejs环境下有效，ejs下默认就是容器的token，不容改变
+    // 非ejs环境环境下isUseSelfToken为true生效
+    getToken() {
+        // 外部js中实现个性化token相关逻辑，引用后使用
+        const { getCustomToken, storeToken, saveToken } = require('./customToken');
+
+        // 返回Promise对象
+        return new Promise((resolve) => {
+            // 如果存在暂存的自定义token则直接返回
+            if (storeToken) {
+                resolve(storeToken);
+            } else {
+                // 动态获取
+                getCustomToken().then((token) => {
+                    saveToken(token);
+                    resolve(token);
+                });
+            }
+        });
+    },
+    //非ejs环境下isUseSelfToken为true生效
+    refreshToken: function () {
+        const { refreshCustomToken, saveToken } = require('./customToken');
+
+        // 自定义刷新token之后，请求的token仍然是从自定义getToken中获取token。
+        return new Promise((resolve) => {
+            refreshCustomToken().then((token) => {
+                saveToken(token);
+                resolve();
+            });
+        });
+    },
+    // 自定义刷新失败处理
+    // 非ejs环境下isUseSelfToken为true生效
+    // 超过允许最大刷新token次数后请求接口的响应状态码仍然403|401触发，可以在这里进行处理后续逻辑
+    refreshTokenCountExceeded: function () {
+        ejs.ui.alert({
+            title: '提醒',
+            message: '用户身份失效，请重新登录',
+            buttonName: '确定',
+            success() {
+                // ...
+            }
+        });
+    }
+}
+```

package/docs/m8mpdoc-develop/015-/345/267/245/347/250/213/345/214/226/i18n.md

@@ -0,0 +1,220 @@
+# 国际化
+
+国际化改造分三部分，第一部分是`EM`UI 组件的国际化配置，第二部分是业务代码的国际化改造，第三部分是框架全局文件中的国际化改造。
+
+## UI 组件国际化
+
+跨端组件库默认语言为中文，支持中英文切换。
+
+### 使用方法
+
+组件库通过 `Locale` 组件实现多语言支持，使用 `Locale.use` 方法可以切换当前使用的语言。
+
+```js
+// 由于 Locale 是全局函数，可以不用手动引入该函数
+import Locale from '@components/locale/index.js';
+
+// 切换为英文，可以通过uni.getLocale()获取应用语言
+Locale.use('en');
+```
+
+#### 覆盖语言包
+
+通过 `Locale.add` 方法可以实现文案的修改和扩展，示例如下：
+
+```js
+const messages = {
+    'zh-Hans': {
+        emPicker: {
+            confirm: '关闭' // 将'确认'修改为'关闭'
+        }
+    }
+};
+
+Locale.add(messages);
+```
+
+#### 语言包
+
+目前支持的语言:
+
+| 语言     |   key   | 文件名       |
+| :------- | :-----: | :----------- |
+| 简体中文 | zh-Hans | zh-Hans.json |
+| 英文     |   en    | en.json      |
+
+在`@epoint-mrc\em-components\src\components\locale\i18n`查看所有语言文件
+
+若需要翻译成其他语言，可以使用`Locale.add`进行扩展。
+
+## 业务代码改造
+
+业务代码部分使用`vue-i18n`插件进行改造。
+
+首先，需要安装该插件：
+
+```js
+npm install --save vue-i18n@8
+```
+
+注意：请注意插件版本，否则可能会报错。
+
+然后配置语言文件：
+
+### 语言配置文件：
+
+设置本地语言配置文件，在项目`src`目录下新建 `locale` 文件夹，在`locale` 文件夹下新建`zh-Hans.json`中文语言配置和`en.json`英文语言配置。
+
+```javascript
+// locale/zh-Hans.json
+{
+    "hello": "你好，世界"
+}
+```
+
+```javascript
+// locale/en.json
+{
+    "hello": "hello world"
+}
+```
+
+### 初始化
+
+在`main.js`内引用`vue-i18n`插件，初始化：
+
+```JavaScript
+// 引入vue-i18n
+import VueI18n from 'vue-i18n';
+// 引入语言配置文件
+import en from './locale/en.json';
+import zhHans from './locale/zh-Hans.json';
+
+Vue.use(VueI18n);
+const i18n = new VueI18n({
+    locale: 'zh-Hans', // 设置默认语言，这里可以通过uni.getLocale()获取应用语言
+    messages: {
+        en,
+        'zh-Hans': zhHans
+    }
+});
+
+const app = new Vue({
+    i18n,
+    store: new Vuex.Store({
+        modules: storeModules
+    }),
+    ...App
+});
+```
+
+### 业务代码修改
+
+`vue-i18n`初始化完成后，在具体业务组件内，使用`$t('xxx')`代替原有中文内容。例如：
+
+```html
+<h1>你好世界</h1>
+```
+
+修改为：
+
+```html
+<h1>{{ $t('hello') }}</h1>
+```
+
+将会根据语言配置文件，显示不同内容值。
+
+在`locale:'zh-Hans'`时，显示 `你好，世界`，在`locale: 'en'`时，显示`hello world`。
+
+### 修改语言环境
+
+在 vue 组件内，使用 `i18n.locale` 修改语言环境：
+
+```js
+this.$i18n.locale = 'en-US';
+```
+
+可以使用此方法动态修改语言。
+
+更多功能可以参考[vue-i18n 官方文档](https://kazupon.github.io/vue-i18n/zh 'vue-i18n 官方文档')
+
+## 框架全局文件国际化改造
+
+### pages.json 国际化@pages
+
+框架的router.js文件最终会合并至全局文件pages.json中，pages.json不属于vue页面，其中的原生tabbar和原生导航栏里也有文字内容。这部分内容的国际化方案如下：
+
+项目`src`目录的`locale`目录下配置语言json文件，src/locale/`语言地区代码`.json，如：en.json，zh-Hans.json
+
+```
+├── locale
+│   ├── en.json
+│   ├── zh-Hans.json
+```
+
+语言文件示例（zh-Hans.json）
+
+```json
+{
+  "app.name": "Hello uni-app",
+  "index.title": "首页"
+}
+```
+
+pages.json 示例（router.js也适用）
+
+```json
+{
+  "pages": [
+    {
+      "path": "pages/index/index",
+      "style": {
+        "navigationBarTitleText": "%index.title%" // locale目录下 语言地区代码.json 文件中定义的 key，使用 %% 占位
+      }
+    }
+  ],
+  "tabBar": {
+    "list": [{
+        "pagePath": "pages/index/index",
+        "text": "%index.home%"
+      }
+    ]
+  }
+}
+```
+
+pages.json 支持以下属性配置国际化信息
+
+- navigationBarTitleText
+- titleNView->titleText
+- titleNView->searchInput->placeholder
+- tabBar->list->text
+
+注：小程序下不支持这种国际化方案，也可以使用设置tabbar和navigationbar的API来设置文字，例如`ejs.navigator.setTitle`。或者废弃原生tabbar和navigationbar，使用自定义方式。
+
+### manifest.json 国际化@manifest
+
+和 pages.json 一致，在项目目录增加 src/locale/uni-app.`语言地区代码`.json 文件，然后在 `manifest.json` 中使用 %% 占位
+
+```json
+{
+  "name" : "%app.name%",
+  "appid" : "",
+  "description" : "",
+  "versionName" : "1.0.0",
+  "versionCode" : "100",
+  "locale": "zh-Hans" // 设置默认语言，
+}
+```
+
+`manifest.json` 中支持配置应用默认语言，参见上面的示例，默认为auto，跟随系统OS的语言。
+
+## 语言API
+
+跨端框架内置了一批与国际化相关的API和生命周期。
+
+- 获取应用当前使用的语言：[uni.getLocale](https://uniapp.dcloud.net.cn/api/ui/locale.html#getlocale)
+
+- 设置应用语言：[uni.setLocale](https://uniapp.dcloud.net.cn/api/ui/locale.html#setlocale)
+
+- 当前应用语言发生变化时，触发回调。也就是`uni.setLocale`执行时：[uni.onLocaleChange](https://uniapp.dcloud.net.cn/api/ui/locale.html#onlocalechange)

package/docs/m8mpdoc-develop/015-/345/267/245/347/250/213/345/214/226/modules.md

@@ -0,0 +1,44 @@
+# modules目录说明
+
+## 说明：
+
+为了方便开发人员，M8跨端框架`v8.3.9`之后封装了一些固定业务功能模块，通过路由页面跳转可以访问。
+
+## 什么样的业务模块？
+
+一些固定的业务功能的模块，并且这些模块也存在一定的路由跳转功能。产品项目也可以将一些固定的业务功能模块放在modules目录下，
+
+比如：
+
+  - 通用的跨端选人模块
+
+  - 通用的平台小程序用户绑定注册模块
+
+  - m8showcase示例模块
+
+  - m8demo示例模块
+
+  - 产品项目自定义的通用模块
+
+
+## 集成到了框架的什么地方？
+
+目录结构如下
+
+```
+ejs.m8.mobileframe
+    |- src
+    |   |- modules          // 存放框架集成的模块的地方
+    |   |   |- m8showcase   // 对应的M8UI组件示例模块
+    |   |   |- xxx          // 对应的模块资源
+    |   |- pages            // 存放所有业务相关代码
+```
+## modules分包
+
+modules目录以分包的形式提供，框架读取modules/**下的目录中的router.js/mock.js/store.js文件。会与pages目录下的模块注册方式一致，同时自动以分包的方式注册到src/pages.json中的分包节点中。
+
+## 注意：
+
+- 项目产品开发的业务模块**入口**始终在pages目录下，不要放在modules目录下。
+
+- pages下的模块始终支持router.js中配置为分包模块。