m8-framework-mcp 1.0.0 → 1.0.3

package/docs/m8mpdoc-develop/005-/346/240/270/345/277/203/351/200/232/347/224/250Util/001-Ajax/344/270/216/346/226/207/344/273/266/344/270/212/344/274/240.md

@@ -1,456 +0,0 @@
-# Ajax 与文件上传
-
-## 使用场景
-
-核心工具集中内置了 `Ajax` 与 `Upload`，适用于
-
--   前端页面需要用到接口请求时
-
--   需要用到文件上传时
-
-## 方法说明
-
-注：框架对 `axios` 进行封装并挂载到核心工具中，通过 `Util.method()` 调用，如 `Util.ajax()` ，`Ajax` 或 `Upload` 返回的是 `Promise` 对象，支持链式调用
-
-### ajax(options)
-
-进行 ajax 请求，有两种使用方法
-
--   普通版本，传入 `success` 和 `error` 处理回调，并且 `error` 如果不穿，有一个默认的实现效果
-
--   `Promise` 版本，`Ajax` 返回的 `Promise` 对象可以链式调用，注意如果要去除默认的失败回调实现，请将 `error` 传 `null`
-
-| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
-| :-: | :--------: | :--------: | :----------: |
-|  √  |     √      |     √      |      √       |
-
-**普通版本**
-
-```js
-Util.ajax({
-    url: Config.serverUrl + 'request.php?action=testV7Detail',
-    data: {
-        params: JSON.stringify({
-            guid: '12345'
-        })
-    },
-    // v8.3.10优化支持dataPath，建议使用
-    dataPath: 'custom',
-    success: (result) => {
-        // dataPath配置后，匹配成功result.code为1，返回的result.data直接就是 路径匹配 节点下的数据
-        if (result.code === 1) {
-            // xxx
-        }
-    },
-    error: (err) => {
-        // error callback
-    },
-    complete: () => {
-        // complete callback
-    }
-});
-```
-
-**Promise 版本**
-
-```js
-Util.ajax({
-    url: Config.serverUrl + 'request.php?action=testV7Detail',
-    data: {
-        params: JSON.stringify({
-            guid: '12345'
-        })
-    }
-})
-    .then((res) => {
-        console.log(res);
-    })
-    .catch((error) => {
-        // error callback
-    })
-    .finally(() => {
-        // complete callback
-    });
-```
-
-也可以控制多个 `Ajax` 请求
-
-```js
-const ajax1 = Util.ajax({
-    url: 'https://www.easy-mock.com/mock/5cb6ca44f6c8be4af31ae04d/mock/getTreeOuModel',
-    data: {
-        token: '123'
-    }
-});
-
-const ajax2 = Util.ajax({
-    url: 'https://www.easy-mock.com/mock/5cb6ca44f6c8be4af31ae04d/mock/getSingleTreeModule',
-    data: {
-        token: '321'
-    }
-});
-
-Util.ajaxAll(ajax1, ajax2).then((response) => {
-    // ajax1 返回的数据
-    const res1 = response[0];
-    // ajax2 返回的数据
-    const res2 = response[1];
-});
-```
-
-**参数说明**
-
-所有的参数都在 `options` 对象下 (AjaxOptions)
-
-| 参数              | 参数类型       | 说明                                                                                                                                                     | 平台差异说明        |
-| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
-| url               | String         | `必填`, 请求的 url                                                                                                                                       |                     |
-| data              | String 或 JSON | `必填`，请求的数据                                                                                                                                       |                     |
-| type              | String         | 请求类别，`GET` 或 `POST`，默认为 `POST`，                                                                                                               | 有效值详见下方说明  |
-| isAutoProxy       | Boolean        | 默认为 `true`，如设置为 `false`，则单个请求不会在请求头中携带用户 token                                                                                  |                     |
-| isAutoFingerprint | Boolean        | 默认为 `true`，如设置为 `false`，则单个请求不会在请求头中携带指纹，`isAutoProxy` 为 `true` 时生效                                                        |                     |
-| isAutoErrToast    | Boolean        | 默认为 `false`，是否开启错误状态码自动弹窗提示                                                                                                           |                     |
-| isUseEjsFetchAjax | Boolean        | 默认为 `false`，是否使用原生请求代理 ajax 请求                                                                                                           |                     |
-| isAutoDealError   | Boolean        | 默认为 `true`，如开启，框架会处理一些默认的返回错误并提示（非 200 情况下），处理的错误码有：401，403，417，429                                           |                     |
-| success           | Function       | 成功回调，如不写，则有个默认实现，或者通过 `.then` 进行链式调用                                                                                          |                     |
-| error             | Function       | 失败回调，默认有一个失败回调的实现，会打印错误信息                                                                                                       |                     |
-| complete          | Function       | 请求完成后的回调，不管是成功还是失败都会触发                                                                                                             |                     |
-| responseType      | String         | 服务器响应的数据类型                                                                                                                                     |                     |
-| timeout           | Number         | 请求超时的毫秒数                                                                                                                                         |                     |
-| headers           | Object         | 设置请求的 header，header 中不能设置 Referer                                                                                                             |                     |
-| withCredentials   | Boolean        | 跨域请求时是否需要使用凭证                                                                                                                               | 仅 H5 支持          |
-| contentType       | String         | 发送信息至服务器时内容编码类型，普通请求默认为 `application/json`，文件上传请求默认为 `multipart/form-data`                                              |                     |
-| statusErrorExtend | Function       | `v8.2.16`新增，http 状态扩展方法，产品项目可以根据业务自行判断 status 状态处理错误处理                                                                   |                     |
-| dataPath          | String/Array   | `v8.3.10`新增，需要获取的路径指令，例如 custum.infolist 或['custum.infolist', 'custum.infoList']，如果为 undefined 或 null，则不会处理，返回的是原始数据 |                     |
-| enableChunked     | Boolean        | `v8.3.17`新增，是否开启 SSE 流式响应，默认 false                                                                                                         | H5、微信小程序 支持 |
-| onChunkReceived   | Function       | `v8.3.17`新增，SSE 流式响应接收到数据时触发的回调函数，参数为接收到的数据                                                                                | H5、微信小程序 支持 |
-| lockTokenDuration | Number         | `v8.3.22`新增，锁定 token 的时长，单位 ms                                                                                                                |                     |
-| cancelKey         | String         | 中断请求的自定义 key 值，可通过该 key 值获取 ajax 的取消方法取消请求                                                                                     |                     |
-
-**type 有效值**
-
-注意：type 有效值必须大写，每个平台支持的 method 有效值不同，详细见下表。
-
-|  type   | EJS | H5  | 微信小程序 | 支付宝小程序 |
-| :-----: | :-: | :-: | :--------: | :----------: |
-|   GET   |  √  |  √  |     √      |      √       |
-|  POST   |  √  |  √  |     √      |      √       |
-|   PUT   |  x  |  √  |     √      |      √       |
-| DELETE  |  x  |  √  |     √      |      √       |
-| CONNECT |  x  |  √  |     √      |      x       |
-|  HEAD   |  x  |  √  |     √      |      x       |
-| OPTIONS |  x  |  √  |     √      |      x       |
-|  TRACE  |  x  |  √  |     √      |      x       |
-
-**referer 说明**
-
-网络请求的 referer Header 不可设置。
-
-`ejs`与`h5` referer 默认传当前页面的 URL。
-
-平台小程序格式固定
-
-###### 支付宝：
-
-为 https://{appid}.hybrid.alipay-eco.com/{appid}/{version}/index.html#pages/index，其中 {appid} 为小程序的 APPID，{version} 为小程序发布标识。
-
-###### 微信：
-
-为 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 为小程序的 appid，{version} 为小程序的版本号，版本号为 0 表示为开发版
-
-**成功返回**
-
--   返回一个 `response`，即返回的是原始数据`response`
-
--   配置`dataPath`:
-
-`v8.3.10`开始，支持配置`dataPath`，可以获取指定路径的数据。配置后的成功返回：
-
-|  参数   |   参数类型    |                                                 说明                                                 |
-| :-----: | :-----------: | :--------------------------------------------------------------------------------------------------: |
-|  code   |    Number     | 处理完的结果，为`1`代表处理成功，`0`代表失败，一般失败的原因是接口返回的 status 不正确或者格式不匹配 |
-|  data   |    Object     |                     处理完后的最终数据，如果没有获取到对应节点下的数据，为 null                      |
-| message |    String     |                   处理完后的提示，例如错误信息提示、接口返回的 status.text 信息等                    |
-| status  | Number/String |                                      接口返回的 status.code 值                                       |
-
-**失败返回**
-
-| 参数  | 参数类型 | 说明     |
-| ----- | -------- | -------- |
-| error | String   | 错误信息 |
-
-**Tips**
-
--   请求的 `header` 中 `content-type` 默认为 `application/json`。
--   避免在 `header` 中使用中文，或者使用 encodeURIComponent 进行编码。
--   网络请求的 `超时时间` 可以统一在 `manifest.json` 中配置。
--   注意平台小程序端不支持自动保持 cookie，服务器应避免验证 cookie。
-
-### 取消 Ajax
-
-可传递一个 `cancelKey` 给 `ajax`，在需要取消请求时，通过 `cancelKey` 获取到对应的取消方法，然后调用取消方法即可中断请求。
-
-```js
-Util.ajax({
-    url: Config.serverUrl + 'request.php?action=testV7Detail',
-    data: {
-        params: JSON.stringify({
-            guid: '12345'
-        })
-    },
-    // 传递一个key值
-    cancelKey: 'key1',
-    success: (result) => {},
-    error: (err) => {}
-});
-
-// ajax实例上绑定了cancels映射，通过该key值获取对应取消方法中断请求
-Util.ajax.cancels['key1']();
-```
-
-### Util.ajax 支持暴露 axios 实例
-
-`v8.3.10` 版本开始，Util.ajax 支持暴露 axios 实例，方便产品项目对 axios 进行拦截、封装等操作。
-产品项目如果想要实现通用的 Util.ajax 某些功能，可以借助于此功能实现。例如政务 BG 进行 ajax 统一 sm2 加密解密场景；产品项目对请求拦截、响应拦截有其他通用需求场景等。
-
-使用方式：
-
-`Util.ajax.instance`为 Util.ajax 的 axios 实例，可以在此进行请求拦截、响应拦截等功能开发。
-
-```js
-const instance = Util.ajax.instance;
-
-instance.interceptors.request.use((config) => {
-    // xxx
-
-    return config;
-});
-instance.interceptors.response.use((response) => {
-    // xxx
-
-    return response;
-});
-```
-
-::: ifdef M84
-
-### 拦截器管理
-
-`8.4.0-beta.3`版本开始，Util.ajax 新增了一些方法来更好的管理拦截器，方便产品项目基于框架方法进行拓展。
-
-#### create 方法
-
-创建一个新的 ajax 实例：UtilAjaxInstance，框架的 Util.ajax 就是通过该方法生成的。
-
-```ts
-interface UtilAjaxInstance {
-    (options: AjaxOptions): Promise<any>;
-    instance: AxiosInstance; // axios 实例
-    cancels?: cancels; // 请求取消方法数组
-    minirefreshPending?: Array<{ f: cancelFunc }>; // 下拉刷新请求取消方法数组
-    pluginFactory: InterceptorsPluginFactory; // 拦截器插件工厂方法
-    plugins: {
-        request: InterceptorsPlugin[]; // 请求拦截器插件数组
-        response: InterceptorsPlugin[]; // 响应拦截器插件数组
-    };
-    _defaultSettings: AjaxOptions; // 默认配置
-    create: (option?: AjaxOptions) => UtilAjaxInstance; // 创建一个新的 Util.ajax 实例
-    addInterceptors: (plugin?: InterceptorsPlugin | InterceptorsPlugin[]) => void; // 添加拦截器插件
-    removeInterceptors: (pluginName?: string | string[], type?: 'request' | 'response') => void; // 删除拦截器插件
-    request: (options: AjaxOptions) => Promise<any>; // 发送请求
-    createInterceptorsPlugin: (option: InterceptorsPluginOpt) => InterceptorsPlugin; // 创建拦截器插件
-}
-```
-
-使用示例：
-
-```ts
-// 创建时可传入默认配置
-// newAjax 功能与 Util.ajax 一致
-const newAjax: UtilAjaxInstance = Util.ajax.create({
-    headers: {
-        'Content-Type': 'application/json'
-    }
-});
-
-newAjax({
-    url: 'https://www.easy-mock.com/mock/5cb6ca44f6c8be4af31ae04d/mock/getTreeOuModel',
-    data: {
-        token: '123'
-    }
-}).then((response) => {
-    console.log(response);
-});
-```
-
-#### createInterceptorsPlugin 方法
-
-创建一个拦截器插件：InterceptorsPlugin
-
-```ts
-interface InterceptorsPlugin {
-    _interceptorsID: number; // 拦截器 ID
-    _opt: InterceptorsPluginOpt; // 拦截器配置，见下
-    name: string; // 拦截器名称
-    type: 'request' | 'response'; // 拦截器类型
-    description?: string; // 描述信息
-    install: (axiosInstance: AxiosInstance) => void; // 安装拦截器插件
-    uninstall: (axiosInstance: AxiosInstance) => void; // 卸载拦截器插件
-}
-
-interface InterceptorsPluginOpt {
-    name: string; // 拦截器名称
-    type: 'request' | 'response'; // 拦截器类型
-    description?: string; // 描述信息
-    success: {
-        <T extends AxiosRequestConfig>(config: T): T | Promise<T>;
-        <T extends AxiosResponse>(config: T): T | Promise<T>;
-        <T extends AxiosRequestConfig | AxiosResponse>(config: T): T | Promise<T>;
-    }; // 拦截器成功回调
-    error?: (error: any) => Promise<any>; // 拦截器失败回调
-    onUninstall?: (axiosInstance: AxiosInstance) => void; // 拦截器卸载时触发该回调，可在此处清除一些不需要的实例对象
-}
-```
-
-用法示例；
-
-```ts
-// 创建一个请求拦截器插件
-const testRequestPlugin = Util.ajax.createInterceptorsPlugin({
-    name: 'test',
-    type: 'request',
-    description: '测试请求拦截器',
-    success: (config) => {
-        // 这里可以对请求参数进行处理
-        return config;
-    }
-});
-// 创建一个响应拦截器插件
-const testResponsePlugin = Util.ajax.createInterceptorsPlugin({
-    name: 'test',
-    type: 'response',
-    description: '测试响应拦截器',
-    success: (response) => {
-        // 这里可以对返回参数进行处理
-        return response;
-    }
-});
-
-// 添加拦截器插件
-Util.ajax.addInterceptors([testRequestPlugin, testResponsePlugin]);
-
-// 不需要时移除拦截器插件
-// 传入拦截器插件名称，会移除所有该名称下的拦截器插件
-Util.ajax.removeInterceptors('test'); // 移除 testRequestPlugin 和 testResponsePlugin
-
-// 传入拦截器插件名称和类型，会移除该类型下的该名称的拦截器插件
-Util.ajax.removeInterceptors('test', 'request'); // 移除 testRequestPlugin
-```
-
-框架内置了一批拦截器插件，框架的自动代理、中断请求等功能都通过拦截器来实现，已安装的插件可通过 Util.ajax.plugins 查看，如果产品项目不需要某个功能，可以直接移除该拦截器插件。
-
-```ts
-const newAjax: UtilAjaxInstance = Util.ajax.create();
-
-// 移除框架的自动代理功能
-newAjax.removeInterceptors('proxy');
-```
-
-**注意：**
-
-框架功能都通过拦截器实现后，原先通过`Util.ajax.instance`添加的请求拦截器都会比框架的处理更先执行，而通过拦截器插件添加的请求拦截器则会在框架的处理之后执行。请注意下执行顺序。
-
-::: endif
-
-### upload(options)
-
-将本地资源上传到开发者服务器，客户端发起一个 `POST` 请求，其中 `content-type` 为 `multipart/form-data`。
-
-| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
-| :-: | :--------: | :--------: | :----------: |
-|  √  |     √      |     √      |      √       |
-
-    在各个平台小程序运行时，网络相关的 API 在使用前需要配置域名白名单。
-
-```html
-<template>
-    <div class="content">
-        <em-uploader :after-read="afterRead" />
-    </div>
-</template>
-
-<script>
-export default {
-    methods: {
-        afterRead(file) {
-            // filePath上传，支持跨端上传（H5、微信小程序、支付宝小程序）
-            Util.upload({
-                url: 'http://115.29.151.25:8012/webUploaderServer/testupload.php', //仅为示例，非真实的接口地址
-                filePath: file.path, // filePath需要与name配套使用
-                name: file.name, // filePath需要与name配套使用
-                formData: {
-                    user: 'test'
-                },
-                success: (res) => {
-                    console.log(res);
-                }
-            });
-            // 普通files上传，仅支持H5
-            Util.upload({
-                url: 'http://115.29.151.25:8012/webUploaderServer/testupload.php', //仅为示例，非真实的接口地址
-                files: [{
-                    file: file
-                }],
-                formData: {
-                    user: 'test'
-                },
-                success: (res) => {
-                    console.log(res);
-                }
-            });
-        }
-    }
-}
-
-
-```
-
-**参数说明**
-
-| 参数       | 参数类型 | 必填                           | 说明                                                                   | 平台差异说明 |
-| ---------- | -------- | ------------------------------ | ---------------------------------------------------------------------- | ------------ |
-| url        | String   | 是                             | 开发者服务器 url                                                       |              |
-| files      | Array    | 是（files 和 filePath 选其一） | 需要上传的文件列表。**使用 files 时，filePath 和 name 不生效。**       | 仅 H5 支持   |
-| filePath   | String   | 是（files 和 filePath 选其一） | 要上传文件资源的路径 （推荐使用）                                      |              |
-| name       | String   | 是                             | 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容 |              |
-| headers    | Object   | 否                             | 设置请求的 header，header 中不能设置 Referer                           |
-| timeout    | Number   | 否                             | 请求超时的毫秒数                                                       |
-| formData   | Object   | 否                             | HTTP 请求中其他额外的 form data                                        |
-| antiReplay | Boolean  | 否                             | 附件上传是否带上防重放标记，默认 true                                  |
-| success    | Function | 否                             | 接口调用成功的回调函数                                                 |
-| error      | Function | 否                             | 接口调用失败的回调函数                                                 |
-| complete   | Function | 否                             | 接口调用结束的回调函数（调用成功、失败都会执行）                       |
-| uploading  | Function | 否                             | 文件上传时，进度回调                                                   |              |
-
-**注意**
-
--   微信小程序只支持单文件上传，传多个文件需要反复调用本 API。所以跨端的写法就是循环调用本 API。
--   网络请求的 超时时间 可以统一在 `manifest.json` 中配置
-
-**files 参数说明**
-
-files 参数是一个 file 对象的数组，file 对象的结构如下：
-
-| 参数名 | 类型   | 必填 | 说明                                        |
-| :----- | :----- | :--- | :------------------------------------------ |
-| name   | String | 否   | multipart 提交时，表单的项目名，默认为 file |
-| file   | File   | 否   | 要上传的文件对象，仅 H5 支持                |
-| uri    | String | 是   | 文件的本地地址                              |
-
-### Util.upload 支持空附件上传
-
-`v8.3.14` 版本开始，Util.upload 附件上传支持空附件上传。
-
-某些项目场景下，表单与附件一起上传，同时附件为非必填项，请求参数要求 formData 形式，此时进上传表单数据时，原有的 Util.upload 会报错。
-
-`v8.3.14`版本之后可以使用 Util.upload 进行这类场景下调用，可以保证参数为 formData 格式，附件非必填。支持 H5、微信、支付宝小程序跨端场景。

package/docs/m8mpdoc-develop/006-Util/345/267/245/345/205/267/351/233/206/000-charset.md

@@ -1,128 +0,0 @@
-# Util.charset
-
-## 使用场景
-
-- 需要用到 `UTF-16`，`UTF-8` 编码转换的地方
-
-- 需要用到 `Base64-UTF-16`，`Base64-UTF-8` 编码解码的地方
-
-- 可以通过在线工具测试 [BASE64方式加密、解密](https://www.sojson.com/base64.html)
-
-## 方法说明
-
-注：此工具集下的方法以 `Util.charset` 为前缀进行调用
-
-### strToBinary(str)
-
-将字符串转为二进制字符串
-
-**平台差异**
-
-|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
-| :---: | :--------: | :--------: | :----------: |
-|   √   |     √      |     √      |      √       |
-
-**示例**
-
-```js
-const str = '你好，世界！';
-
-// 10011110110000010110010111110111111111000011001001110000101101110101010011001111111100000001
-Util.charset.strToBinary(str);
-```
-
-### utf16ToUtf8(str)
-
-将 `UTF-16` 编码的字符串转成 `UTF-8` 编码的字符串
-
-**平台差异**
-
-|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
-| :---: | :--------: | :--------: | :----------: |
-|   √   |     √      |     √      |      √       |
-
-**示例**
-
-```js
-const str = '你好，世界！';
-
-// 你好ï¼\x8Cä¸\x96ç\x95\x8Cï¼\x81
-Util.charset.utf16ToUtf8(str);
-```
-
-### uft8ToUtf16(str)
-
-将 `UTF-8` 编码的字符串转成 `UTF-16` 编码的字符串
-
-**平台差异**
-
-|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
-| :---: | :--------: | :--------: | :----------: |
-|   √   |     √      |     √      |      √       |
-
-**示例**
-
-```js
-var str = '你好ï¼\x8Cä¸\x96ç\x95\x8Cï¼\x81';
-
-// 你好，世界！
-Util.charset.utf8ToUtf16(str);
-```
-
-### base64.encode(str, type, isUri)
-
-将目标字符串进行 `Base64` 编码
-
-**平台差异**
-
-|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
-| :---: | :--------: | :--------: | :----------: |
-|   √   |     √      |     √      |      √       |
-
-__参数说明__
-
-| 参数 | 参数类型 | 说明 |
-| --- | ---- | --- |
-| str | String | 目标字符串，只支持 `UTF-16` 编码形式，可以认为，`JS` 中默认的输入就是 `UTF-16` 形式 |
-| type | String | 类别，可选 `utf8`、`utf16`，默认为 `utf8`。`utf8`代表先转为 `UTF-8` 编码然后再进行 `Base64` 编码 |
-| isUri | Boolean | 是否进行 `uri` 编码，如果为 `true`，结果中一些特殊字符会进行 `uri` 编码（如 `=` 号） |
-
-**示例**
-
-```js
-var str = '你好，世界！';
-
-// 5L2g5aW977yM5LiW55WM77yB
-Util.charset.base64.encode(str);
-
-// 5L2g5aW977yM5LiW55WM77yBPT0%3D
-Util.charset.base64.encode('你好，世界！==', 'utf8', true);
-```
-
-### base64.deocde(str, type, isUri)
-
-将 `Base64` 编码的字符串解码
-
-**平台差异**
-
-|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
-| :---: | :--------: | :--------: | :----------: |
-|   √   |     √      |     √      |      √       |
-
-__参数说明__
-
-| 参数 | 参数类型 | 说明 |
-| --- | ---- | --- |
-| str | String | 目标字符串，只支持 `Base64` 编码后的字符串 |
-| type | String | 类别，可选 `utf8`，`utf16`，默认为 `utf8`。`utf8`代表先解码，然后将结果从 `UTF-8` 编码转换为 `UTF-16` 编码 |
-| isUri | Boolean | 是否进行 `uri` 编码，如果为 `true`，在编码前，会对特殊字符会进行 `uri` 解码(如 `=` 号) |
-
-**示例**
-
-```js
-// 你好，世界！
-Util.charset.base64.decode('5L2g5aW977yM5LiW55WM77yB');
-
-// 你好，世界！==
-Util.charset.base64.decode('5L2g5aW977yM5LiW55WM77yBPT0%3D', 'utf8', true);
-```