m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/006-Util/345/267/245/345/205/267/351/233/206/013-2.socketTask.md

@@ -0,0 +1,92 @@
+# 扩展-网络API
+
+**SocketTask** 由 [Util.connectSocket()](./index.html?file=006-Util工具集/013-2.network) 接口创建。
+
+**平台差异说明**
+
+支付宝小程序没有明确的文档来具体说明这个对象，而是指向了 [Web Websocket](https://developer.mozilla.org/zh-CN/docs/Web/API/WebSocket) 对象。
+
+### SocketTask.onMessage(CALLBACK)
+监听 WebSocket 接受到服务器的消息事件
+
+**回调函数**
+
+`Function`
+
+WebSocket 接受到服务器的消息事件的回调函数
+
+**回调函数中的参数**
+
+`Object`
+
+|属性|类型|说明|
+|:-|:-|:-|
+|data|String/ArrayBuffer|服务器返回的消息|
+
+### SocketTask.send(OBJECT)
+通过 WebSocket 连接发送数据
+
+**参数**
+
+|属性|类型|是否必填|说明|
+|:-|:-|:-|:-|
+|data|String/ArrayBuffer|是|需要发送的内容|
+|success|Function|否|接口调用成功的回调函数|
+|fail|Function|否|接口调用失败的回调函数|
+|complete|Function|否|接口调用结束的回调函数（调用成功、失败都会执行）|
+
+### SocketTask.close(OBJECT)
+关闭 WebSocket 连接
+
+**参数**
+
+|属性|类型|默认值|是否必填|说明|
+|:-|:-|:-|:-|:-|
+|code|Number|1000（表示正常关闭连接）|否|一个数字值表示关闭连接的状态号，表示连接被关闭的原因。|
+|reason|String||否|一个可读的字符串，表示连接被关闭的原因。|
+|success|Function||否|接口调用成功的回调函数|
+|fail|Function||否|接口调用失败的回调函数|
+|complete|Function||否|接口调用结束的回调函数（调用成功、失败都会执行）|
+
+### SocketTask.onOpen(CALLBACK)
+监听 WebSocket 连接打开事件
+
+**回调函数**
+
+`Function`
+
+WebSocket 连接打开事件的回调函数
+
+**回调函数中的参数**
+
+`Object`
+
+|属性|类型|说明|
+|:-|:-|:-|
+|data|String/ArrayBuffer|服务器返回的消息|
+
+### SocketTask.onClose(CALLBACK)
+监听 WebSocket 连接关闭事件
+
+**回调函数**
+
+`Function`
+
+WebSocket 连接关闭事件的回调函数
+
+### SocketTask.onError(CALLBACK)
+监听 WebSocket 错误事件
+
+**回调函数**
+
+`Function`
+
+WebSocket 错误事件的回调函数
+
+**回调函数中的参数**
+
+`Object`
+
+|属性|类型|说明|
+|:-|:-|:-|
+|errMsg|String|错误信息|

package/docs/m8mpdoc-develop/006-Util/345/267/245/345/205/267/351/233/206/013-3.uiapi.md

@@ -0,0 +1,412 @@
+# 扩展-界面 API
+
+## 使用场景
+
+使用到涉及界面的 API 场景。
+
+### Util.createSelectorQuery()
+
+`v8.3.17-beta.4`开始支持。
+
+返回一个 `SelectorQuery` 对象实例。可以在这个实例上使用 `select` 等方法选择节点，并使用 `boundingClientRect` 等方法选择需要查询的信息。
+
+**Tips:**
+
+-   使用 `Util.createSelectorQuery()` 需要在生命周期 `mounted` 后进行调用。
+-   默认需要使用到 `selectorQuery.in` 方法。
+
+**平台差异说明**
+
+| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :-: | :--------: | :--------: | :----------: |
+|  √  |     √      |     √      |      √       |
+
+#### SelectorQuery
+
+查询节点信息的对象
+
+##### selectorQuery.in(component)
+
+将选择器的选取范围更改为自定义组件 `component` 内，返回一个 `SelectorQuery` 对象实例。（初始时，选择器仅选取页面范围的节点，不会选取任何自定义组件中的节点）。
+
+**代码示例**
+
+```javascript
+const query = Util.createSelectorQuery().in(this);
+query
+    .select('#id')
+    .boundingClientRect((data) => {
+        console.log('得到布局位置信息' + JSON.stringify(data));
+        console.log('节点离页面顶部的距离为' + data.top);
+    })
+    .exec();
+```
+
+**注意**
+
+-   支付宝小程序不支持 in(component)，使用无效果
+
+##### selectorQuery.select(selector)
+
+在当前页面下选择第一个匹配选择器 `selector` 的节点，返回一个 `NodesRef` 对象实例，可以用于获取节点信息。
+
+**selector 说明：**
+
+`selector` 类似于 CSS 的选择器，但仅支持下列语法。
+
+-   ID 选择器：`#the-id`
+-   class 选择器（可以连续指定多个）：`.a-class.another-class`
+-   子元素选择器：`.the-parent > .the-child`
+-   后代选择器：`.the-ancestor .the-descendant`
+-   跨自定义组件的后代选择器：`.the-ancestor >>> .the-descendant` (H5 暂不支持)
+-   多选择器的并集：`#a-node, .some-other-nodes`
+
+##### selectorQuery.selectAll(selector)
+
+在当前页面下选择匹配选择器 `selector` 的所有节点，返回一个 `NodesRef` 对象实例，可以用于获取节点信息。
+
+##### selectorQuery.selectViewport()
+
+选择显示区域，可用于获取显示区域的尺寸、滚动位置等信息，返回一个 `NodesRef` 对象实例。
+
+##### selectorQuery.exec(callback)
+
+执行所有的请求。请求结果按请求次序构成数组，在 callback 的第一个参数中返回。
+
+#### NodesRef
+
+用于获取节点信息的对象
+
+##### nodesRef.fields(object,callback)
+
+获取节点的相关信息。第一个参数是节点相关信息配置（必选）；第二参数是方法的回调函数，参数是指定的相关节点信息。
+
+**object 参数说明**
+
+| 字段名        | 类型               | 默认值 | 必填 | 说明                                                                                                                                    | 平台差异说明      |
+| :------------ | :----------------- | :----- | :--- | :-------------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
+| id            | Boolean            | false  | 否   | 是否返回节点 `id`                                                                                                                       |                   |
+| dataset       | Boolean            | false  | 否   | 是否返回节点 `dataset`                                                                                                                  | 微信小程序、H5    |
+| rect          | Boolean            | false  | 否   | 是否返回节点布局位置（`left` `right` `top` `bottom`）                                                                                   |                   |
+| size          | Boolean            | false  | 否   | 是否返回节点尺寸（`width` `height`）                                                                                                    |                   |
+| scrollOffset  | Boolean            | false  | 否   | 是否返回节点的 `scrollLeft` `scrollTop`，节点必须是 `scroll-view` 或者 `viewport`                                                       |                   |
+| properties    | Array ＜ string ＞ | []     | 否   | 指定属性名列表，返回节点对应属性名的当前属性值（只能获得组件文档中标注的常规属性值，`id`、`class`、`style` 和事件绑定的属性值不可获取） | 仅 微信小程序支持 |
+| computedStyle | Array ＜ string ＞ | []     | 否   | 指定样式名列表，返回节点对应样式名的当前值                                                                                              | 仅微信小程序支持  |
+| context       | Boolean            | false  | 否   | 是否返回节点对应的 Context 对象                                                                                                         | 仅微信小程序支持  |
+
+##### nodesRef.boundingClientRect(callback)
+
+添加节点的布局位置的查询请求。相对于显示区域，以像素为单位。其功能类似于 DOM 的 `getBoundingClientRect`。返回 `NodesRef` 对应的 `SelectorQuery`。
+
+**callback 返回参数**
+
+| 属性    | 类型   | 说明             |
+| ------- | ------ | ---------------- |
+| id      | String | 节点的 ID        |
+| dataset | Object | 节点的 dataset   |
+| left    | Number | 节点的左边界坐标 |
+| right   | Number | 节点的右边界坐标 |
+| top     | Number | 节点的上边界坐标 |
+| bottom  | Number | 节点的下边界坐标 |
+| width   | Number | 节点的宽度       |
+| height  | Number | 节点的高度       |
+
+##### nodesRef.scrollOffset(callback)
+
+添加节点的滚动位置查询请求。以像素为单位。节点必须是 `scroll-view` 或者 `viewport`。返回 `NodesRef` 对应的 `SelectorQuery`。
+
+**callback 返回参数**
+
+| 属性       | 类型   | 说明               |
+| ---------- | ------ | ------------------ |
+| id         | String | 节点的 ID          |
+| dataset    | Object | 节点的 dataset     |
+| scrollLeft | Number | 节点的水平滚动位置 |
+| scrollTop  | Number | 节点的竖直滚动位置 |
+
+##### nodesRef.context(callback)
+
+添加节点的 Context 对象查询请求。支持 [`VideoContext`](https://uniapp.dcloud.net.cn/api/media/video-context.html)、[`CanvasContext`](https://uniapp.dcloud.net.cn/api/canvas/CanvasContext.html)、和 [`MapContext`](https://uniapp.dcloud.net.cn/api/location/map.html) 等的获取。
+
+**平台差异说明**
+
+| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :-: | :--------: | :--------: | :----------: |
+|  √  |     √      |     √      |      x       |
+
+**callback 返回参数**
+
+| 属性    | 类型   | 说明                    |
+| ------- | ------ | ----------------------- |
+| context | Object | 节点对应的 Context 对象 |
+
+##### nodesRef.node(callback)
+
+获取 `Node` 节点实例。目前支持 `Canvas` 的获取。
+
+**平台差异说明**
+
+| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :-: | :--------: | :--------: | :----------: |
+|  x  |     x      |     √      |      x       |
+
+**callback 返回参数**
+
+| 属性 | 类型   | 说明                 |
+| ---- | ------ | -------------------- |
+| node | Object | 节点对应的 Node 实例 |
+
+**注意**
+
+-   目前仅能用于`canvas`
+-   `canvas`需设置`type="webgl"`才能正常使用
+
+#### 代码示例
+
+```javascript
+uni.createSelectorQuery()
+    .selectViewport()
+    .scrollOffset((res) => {
+        console.log('竖直滚动位置' + res.scrollTop);
+    })
+    .exec();
+
+let view = uni.createSelectorQuery().in(this).select('.test');
+
+view.fields(
+    {
+        size: true,
+        scrollOffset: true
+    },
+    (data) => {
+        console.log('得到节点信息' + JSON.stringify(data));
+        console.log('节点的宽为' + data.width);
+    }
+).exec();
+
+view.boundingClientRect((data) => {
+    console.log('得到布局位置信息' + JSON.stringify(data));
+    console.log('节点离页面顶部的距离为' + data.top);
+}).exec();
+```
+
+**注意**
+
+-   weex 暂不支持 `Util.createSelectorQuery`，暂时使用下面的方案
+
+```html
+<template>
+    <view class="wrapper">
+        <view ref="box" class="box">
+            <text class="info">Width: {{size.width}}</text>
+            <text class="info">Height: {{size.height}}</text>
+            <text class="info">Top: {{size.top}}</text>
+            <text class="info">Bottom: {{size.bottom}}</text>
+            <text class="info">Left: {{size.left}}</text>
+            <text class="info">Right: {{size.right}}</text>
+        </view>
+    </view>
+</template>
+```
+```js
+// 注意平台差异
+// #ifdef APP-NVUE
+const dom = weex.requireModule('dom');
+// #endif
+
+export default {
+    data() {
+        return {
+            size: {
+                width: 0,
+                height: 0,
+                top: 0,
+                bottom: 0,
+                left: 0,
+                right: 0
+            }
+        };
+    },
+    onReady() {
+        setTimeout(() => {
+            const result = dom.getComponentRect(this.$refs.box, (option) => {
+                console.log('getComponentRect:', option);
+                this.size = option.size;
+            });
+            console.log('return value:', result);
+            console.log('viewport:', dom.getComponentRect('viewport'));
+        }, 100);
+    }
+};
+```
+
+### Util.pageScrollTo(OBJECT)
+
+将页面滚动到目标位置。
+
+**平台差异**
+
+| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :-: | :--------: | :--------: | :----------: |
+|  √  |     √      |     √      |      √       |
+
+**OBJECT 参数说明**
+
+| 参数名    | 类型     | 必填 | 说明                                                     |
+| :-------- | :------- | :--- | :------------------------------------------------------- |
+| scrollTop | Number   | 否   | 滚动到页面的目标位置（单位 px）                          |
+| selector  | String   | 否   | 选择器，H5、微信小程序 2.7.3+ 、支付宝小程序 1.20.0+支持 |
+| duration  | Number   | 否   | 滚动动画的时长，默认 300ms，单位 ms                      |
+| success   | function | 否   | 接口调用成功的回调函数                                   |
+| fail      | function | 否   | 接口调用失败的回调函数                                   |
+| complete  | function | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）         |
+
+**selector 语法**
+selector 类似于 CSS 的选择器，但仅支持下列语法。
+
+-   ID 选择器：#the-id
+-   class 选择器（可以连续指定多个）：`.a-class.another-class`
+-   子元素选择器：`.the-parent > .the-child`
+-   后代选择器：`.the-ancestor .the-descendant`
+-   跨自定义组件的后代选择器：`.the-ancestor >>> .the-descendant`
+-   多选择器的并集：`#a-node, .some-other-nodes`
+
+**示例**
+
+```javascript
+Util.pageScrollTo({
+    scrollTop: 0,
+    duration: 300
+});
+```
+
+### Util.onWindowResize(CALLBACK)
+
+监听窗口尺寸变化事件
+
+**平台差异**
+
+| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :-: | :--------: | :--------: | :----------: |
+|  √  |     √      |     √      |      X       |
+
+**CALLBACK 参数说明**
+
+| 属性 | 类型   | 说明                                                       |
+| ---- | ------ | ---------------------------------------------------------- |
+| size | Object | 变化后的窗口的大小，单位为 px ，{windowWidth,windowHeight} |
+
+**代码示例**
+
+```javascript
+Util.onWindowResize((res) => {
+    console.log('变化后的窗口宽度=' + res.size.windowWidth);
+    console.log('变化后的窗口高度=' + res.size.windowHeight);
+});
+```
+
+**TIPS**
+
+-   横竖屏切换时，会触发此事件。
+
+### Util.offWindowResize(CALLBACK)
+
+取消监听窗口尺寸变化事件
+
+**平台差异**
+
+| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :-: | :--------: | :--------: | :----------: |
+|  √  |     √      |     √      |      X       |
+
+**代码示例**
+
+```javascript
+Util.offWindowResize(() => {
+    console.log('取消监听窗口尺寸变化事件');
+});
+```
+
+### Util.loadFontFace(Object object)
+
+动态加载网络字体，文件地址需为下载类型。微信小程序 `'2.10.0'`起支持全局生效，需在 `app.vue` 中调用。
+
+注意:
+
+1. 引入中文字体，体积过大时会发生错误，建议抽离出部分中文，减少体积，或者用图片替代
+2. 微信小程序端只支持网络字体，字体链接必须是 https。
+3. 微信小程序端字体链接必须是同源下的，或开启了 cors 支持，微信小程序的域名是 servicewechat.com
+4. 工具里提示 Faild to load font 可以忽略
+
+**平台差异说明**
+
+**平台差异**
+
+| H5  | 新点小程序 |  微信小程序   | 支付宝小程序 |
+| :-: | :--------: | :-----------: | :----------: |
+|  √  |     √      | 基础库 2.1.0+ |   1.11.0+    |
+
+**参数说明**
+
+| 属性     | 类型     | 默认值 | 必填 | 说明                                                                      |
+| :------- | :------- | :----- | :--- | :------------------------------------------------------------------------ |
+| global   | Boolean  | false  | 否   | 是否全局生效                                                              |
+| family   | String   |        | 是   | 定义的字体名称                                                            |
+| source   | String   |        | 是   | 字体资源的地址。建议格式为 TTF 和 WOFF，WOFF2 在低版本的 iOS 上会不兼容。 |
+| desc     | Object   |        | 否   | 可选的字体描述符                                                          |
+| success  | Function |        | 否   | 接口调用成功的回调函数                                                    |
+| fail     | Function |        | 否   | 接口调用失败的回调函数                                                    |
+| complete | Function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                          |
+
+**Object.desc 的结构**
+
+| 属性    | 类型   | 默认值 | 必填 | 说明                                                                   |
+| :------ | :----- | :----- | :--- | :--------------------------------------------------------------------- |
+| style   | String | normal | 否   | 字体样式，可选值为 normal / italic / oblique                           |
+| weight  | String | normal | 否   | 字体粗细，可选值为 normal / bold / 100 / 200../ 900                    |
+| variant | String | normal | 否   | 设置小型大写字母的字体显示文本，可选值为 normal / small-caps / inherit |
+
+**代码示例**
+
+```javascript
+Util.loadFontFace({
+    family: 'Bitstream Vera Serif Bold',
+    source: 'url("https://sungd.github.io/Pacifico.ttf")',
+    success() {
+        console.log('success');
+    }
+});
+```
+
+### Util.getMenuButtonBoundingClientRect()
+
+在平台小程序中，如果原生导航栏被隐藏，仍然在右上角会有一个悬浮按钮，微信下也被称为胶囊按钮。本 API 用于获取小程序下该菜单按钮的布局位置信息，方便开发者布局顶部内容时避开该按钮。
+
+坐标信息以屏幕左上角为原点。
+
+**平台差异**
+
+| H5  | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :-: | :--------: | :--------: | :----------: |
+|  x  |     x      |     √      |      √       |
+
+**返回值说明**
+
+|  属性  |  类型  |         说明         |
+| :----: | :----: | :------------------: |
+| width  | number |    宽度，单位：px    |
+| height | number |    高度，单位：px    |
+|  top   | number | 上边界坐标，单位：px |
+| right  | number | 右边界坐标，单位：px |
+| bottom | number | 下边界坐标，单位：px |
+|  left  | number | 左边界坐标，单位：px |
+
+**示例**
+
+```javascript
+let menuButtonInfo = Util.getMenuButtonBoundingClientRect();
+```
+
+**注意**
+
+-   支付宝小程序：其逻辑与微信小程序不同，它提供了菜单点击后按钮的自定义功能，可以选择显示那些系统按钮，[规范详情](https://docs.alipay.com/mini/api/optionmenuitem)

package/docs/m8mpdoc-develop/006-Util/345/267/245/345/205/267/351/233/206/013-4.eventapi.md

@@ -0,0 +1,146 @@
+# 扩展-通讯API
+
+## 使用场景
+
+使用到涉及通讯的API场景。
+
+注意，在EJSAPP中，仅单页应用下生效。
+
+**平台差异**
+
+|  H5   | 新点小程序 | 微信小程序 | 支付宝小程序 |
+| :---: | :--------: | :--------: | :----------: |
+|   √   |     √      |     √      |      √       |
+
+### Util.$emit(eventName,OBJECT)
+
+触发全局的自定义事件，附加参数都会传给监听器回调函数。
+
+|属性		|类型	|描述				|
+|---		|---	|---				|
+|eventName	|String	|事件名				|
+|OBJECT		|Object	|触发事件携带的附加参数	|
+
+**代码示例**
+```javascript
+Util.$emit('update',{msg:'页面更新'})
+```
+
+
+### Util.$on(eventName,callback)
+
+监听全局的自定义事件，事件由 `Util.$emit` 触发，回调函数会接收事件触发函数的传入参数。
+
+|属性		|类型		|描述			|
+|---		|---		|---			|
+|eventName	|String		|事件名			|
+|callback	|Function	|事件的回调函数	|
+
+
+**代码示例**
+```javascript
+Util.$on('update',function(data){
+    console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
+})
+```
+
+
+### Util.$once(eventName,callback)
+
+监听全局的自定义事件，事件由 `Util.$emit` 触发，但仅触发一次，在第一次触发之后移除该监听器。
+
+|属性		|类型		|描述			|
+|---		|---		|---			|
+|eventName	|String		|事件名			|
+|callback	|Function	|事件的回调函数	|
+
+
+**代码示例**
+```javascript
+Util.$once('update',function(data){
+    console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
+})
+```
+
+### Util.$off([eventName, callback])
+
+移除全局自定义事件监听器。
+
+|属性		|类型			|描述			|
+|---		|---			|---			|
+|eventName	|Array＜String＞ |事件名			|
+|callback	|Function		|事件的回调函数	|
+
+**Tips**
+- 如果Util.$off没有传入参数，则移除App级别的所有事件监听器；
+- 如果只提供了事件名（eventName），则移除该事件名对应的所有监听器；
+- 如果同时提供了事件与回调，则只移除这个事件回调的监听器；
+- 提供的回调必须跟$on的回调为同一个才能移除这个回调的监听器；
+
+**代码示例**
+
+`$emit`、`$on`、`$off`常用于跨页面、跨组件通讯，这里为了方便演示放在同一个页面
+
+```html
+<template>
+    <view class="content">
+        <view class="data">
+            <text>{{val}}</text>
+        </view>
+        <button type="primary" @click="comunicationOff">结束监听</button>
+    </view>
+</template>
+
+<script>
+    export default {
+        data() {
+            return {
+                val: 0
+            }
+        },
+        onLoad() {
+            setInterval(()=>{
+                Util.$emit('add', {
+                    data: 2
+                })
+            },1000)
+            Util.$on('add', this.add)
+        },
+        methods: {
+            comunicationOff() {
+                Util.$off('add', this.add)
+            },
+            add(e) {
+                this.val += e.data
+            }
+        }
+    }
+</script>
+
+<style>
+    .content {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+    }
+
+    .data {
+        text-align: center;
+        line-height: 40px;
+        margin-top: 40px;
+    }
+
+    button {
+        width: 200px;
+        margin: 20px 0;
+    }
+</style>
+	
+```
+
+
+**注意事项**
+- Util.$emit、 Util.$on 、 Util.$once 、Util.$off 触发的事件都是 App 全局级别的，跨任意组件，页面，vue 等
+- 使用时，注意及时销毁事件监听，比如，页面 onLoad 里边 Util.$on 注册监听，onUnload 里边 Util.$off 移除，或者一次性的事件，直接使用 Util.$once 监听
+- 注意 Util.$on 定义完成后才能接收到 Util.$emit 传递的数据