Merge pull request #1392 from didi/feat-mode-change-docs

Feat mode change docs

docs-vuepress/api/compile.md

@@ -1006,7 +1006,11 @@ module.exports = defineConfig({
 
 [`Rules`](#rules)
 
-render 函数中可能会存在一些重复变量，该配置可消除 render 函数中的重复变量，进而减少包体积。不配置该参数，则不会消除重复变量
+render 函数中可能会存在一些重复变量，该配置可消除 render 函数中的重复变量，进而减少包体积。不配置该参数，则不会消除重复变量。
+
+同时框架 render 函数优化提供了两个等级，使用 level 字段来进行控制，默认为 level = 1
+* level = 1时，框架生成 render 函数中完成保留 template 中的计算逻辑，setData 传输量保持了最优。
+* level = 2时，框架生成 render 函数中仅保留所有 template 中使用到的响应性变量，无任何计算逻辑保留，render 函数体积达最小状态，但 setData 传输量相对于 level=1 会有所增加。
 
 ```js
 // vue.config.js
@@ -1015,18 +1019,11 @@ module.exports = defineConfig({
     mpx: {
       plugin: {
         optimizeRenderRules: {
-        include: [
-          resolve('src')
-        ],
-        /*
-        include: [
-          (pageResourcePath) => pageResourcePath.includes('pages')
-        ],
-        include: [
-          () => true
-        ]
-        */
-      }
+          include: [
+            resolve('src')
+          ],
+          level: 1
+        }
       }
     }
   }

docs-vuepress/api/directives.md

@@ -382,7 +382,7 @@ wx:model并不会影响相关的事件处理函数，比如像下面这样：
 ## wx:model-prop
 
 wx:model 默认使用 `value` 属性传值，使用 `wx:model-prop` 定义 wx:model 指令对应的属性；
- 
+
 ## wx:model-event
 
 wx:model 默认监听 `input` 事件，可以使用 `wx:model-event` 定义 wx:model 指令对应的事件；
@@ -675,3 +675,103 @@ capture-catch中断捕获阶段和取消冒泡阶段
 点击inner view仅执行handleTap2
 
 **参考：** [事件处理 - capture-catch](../guide/basic/event.html)
+
+
+## @mode
+
+`type mode = 'wx' | 'ali' | 'qq' | 'swan' | 'tt' | 'web' | 'qa'`
+
+跨平台输出场景下，Mpx 框架允许用户在组件上使用 @ 和 | 符号来指定某个节点或属性只在某些平台下有效。
+
+```html
+<button
+  open-type@wx|swan="getUserInfo"
+  bindgetuserinfo@wx|swan="getUserInfo"
+  open-type@ali="getAuthorize"
+  scope@ali="userInfo"
+  onTap@ali="onTap">
+  获取用户信息
+</button>
+```
+在上方示例中，开发者可以便捷的设置在支付宝小程序与微信和百度小程序等平台分别生效的 open-type 属性，
+以及事件绑定或其他属性。假设当前 srcMode 为 wx，目标平台为 ali，则输出产物为：
+```html
+<button
+  open-type="getAuthorize"
+  scope="userInfo"
+  onTap="onTap">
+  获取用户信息
+</button>
+```
+同时，该指令也可以作用在单个节点上，但需要注意的是，该指令作用在单个节点时，节点仅在目标平台输出，同时节点自身属性不会进行跨平台语法转换，不过其子节点不受影响。
+```html
+<!--当srcMode为wx，跨平台输出ali时-->
+<!--错误写法-->
+<view @ali bindtap="someClick">
+    <view wx:if="{{flag}}">text</view>
+</view>
+<!--正确写法-->
+<view @ali onTap="someClick">
+    <view wx:if="{{flag}}">text</view>
+</view>
+```
+
+## @_mode
+
+`type _mode = '_wx' | '_ali' | '_qq' | '_swan' | '_tt' | '_web' | '_qa'`
+
+有时开发者期望使用 @mode 这种方式仅控制节点的展示，保留节点属性的平台转换能力，为此 Mpx 实现了一个隐式属性条件编译能力。
+```html
+<!--srcMode为 wx，输出 ali 时，bindtap 会被正常转换为 onTap-->
+<view @_ali bindtap="someClick">test</view>
+```
+在对应的平台前加一个_，例如@_ali、@_swan、@_tt等，使用该隐式规则仅有条件编译能力，节点属性语法转换能力依旧。
+
+## @env
+
+`string`
+
+跨平台输出场景下，除了 mode 平台场景值，Mpx 框架还提供自定义 env 目标应用，来实现在不同应用下编译产出不同的代码。
+
+关于 env 的详细介绍可以点击[查看](../guide/advance/platform.html#use-env)
+
+跨平台输出使用 env 与 mode 一样支持文件纬度、区块纬度、节点纬度、属性纬度等条件编译，这里我们仅介绍下节点和属性纬度的指令模式使用，env 与 mode 可以组合使用。
+
+env 属性维度条件编译与 mode 的用法大致相同，使用 : 符号与 mode 和其他 env 进行串联，与 mode 组合使用格式形如 attr@mode:env:env|mode:env，为了不与 mode 混淆，当条件编译中仅存在 env 条件时，也需要添加 : 前缀，形如 attr@:env。
+
+```html
+<!--open-type 属性仅在百度平台且应用 env 为 didi 时保留-->
+<button open-type@swan:didi="getUserInfo">获取用户信息</button>
+<!--open-type 属性在应用 env 为 didi 的任意小程序平台保留-->
+<button open-type@:didi="getUserInfo">获取用户信息</button>
+<!--open-type 属性在微信平台且应用 env 为 didi 或 qingju 时保留-->
+<button open-type@wx:didi:qingju="getUserInfo">获取用户信息</button>
+```
+
+env 也可在单个节点上进行条件编译：
+
+```html
+<!--整个节点在应用 env 为 didi时进行保留-->
+<view @:didi>this is a  view component</view>
+```
+
+需要注意的时，如果只声明了 env，没有声明 mode，跨平台输出时框架对于节点属性默认会进行转换：
+
+```html
+<!--srcMode为wx，跨平台输出ali时，bindtap会被转为onTap-->
+<view @:didi bindtap="someClick">this is a  view component</view>
+<view bindtap@:didi ="someClick">this is a  view component</view>
+```
+
+## mpxTagName
+
+`string`
+
+跨平台输出时，有时开发者不仅需要对节点属性进行条件编译，可能还需对节点标签进行条件编译。
+
+为此，Mpx 框架支持了一个特殊属性 mpxTagName，如果节点存在这个属性，在最终输出时将节点标签修改为该属性的值，配合属性维度条件编译，即可实现对节点标签进行条件编译，例如在百度环境下希望将某个 view 标签替换为 cover-view，我们可以这样写：
+
+```html
+<view mpxTagName@swan="cover-view">will be cover-view in swan</view>
+```
+

docs-vuepress/api/reactivity-api.md

@@ -526,6 +526,10 @@ scope.run(() => {
 
 scope.stop()
 ```
+
+需要注意的是，effectScope 接受一个 detached 参数，默认为false，该参数来表示当前作用域是否和父级作用域进行分离，若 detached 为 true，
+当前 effectScope 则不会被父级作用域收集。
+
 * 暂停侦听
 
 Mpx 提供了 pause 方法可以将整个作用域中的响应性副作用批量暂停侦听。

docs-vuepress/guide/advance/platform.md

@@ -352,7 +352,7 @@ module.exports = {
 <view mpxTagName@swan="cover-view">will be cover-view in swan</view>
 ```
 
-### 通过 env 实现自定义目标环境的条件编译
+### 通过 env 实现自定义目标环境的条件编译 {#use-env}
 
 Mpx 支持在以上四种条件编译的基础上，通过自定义 env 的形式实现在不同环境下编译产出不同的代码。