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

Feat mode change docs
didi · Jan 23, 2024 · 8865ad4 · 8865ad4
2 parents f3dcf34 + 45a6842
commit 8865ad4
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 3 deletions.
diff --git a/docs-vuepress/api/compile.md b/docs-vuepress/api/compile.md
@@ -160,7 +160,7 @@ module.exports = defineConfig({
 ```
 
 ::: warning
-抹平支付宝和微信之间的差异，微信转支付宝时可以使用该功能。
+抹平支付宝和微信之间的差异，当使用了微信 **externalClasses** 语法时，跨端输出需要在 @mpxjs/webpack-plugin 的配置中添加此配置来辅助框架进行转换。
 :::
 
 ### resolveMode

diff --git a/docs-vuepress/guide/advance/platform.md b/docs-vuepress/guide/advance/platform.md
@@ -308,11 +308,41 @@ module.exports = {
 </button>
 ```
 
-属性维度的编译也可以对整个节点进行条件编译，例如只想在百度小程序中输出某个节点：
+属性维度的编译也可以对整个节点进行条件编译，例如只想在支付宝小程序中输出某个节点：
 
 ```html
-<view @swan>this is view</view>
+<view @ali>this is view</view>
 ```
+需要注意使用上述用法时，节点自身在构建时框架不会对节点属性进行平台语法转换，但对于其子节点，框架并不会继承父级节点 mode，会进行正常跨平台语法转换。
+```html
+<!--错误示例-->
+<view @ali bindtap="otherClick">
+    <view bindtap="someClick">tap click</view>
+</view>
+// srcMode 为 wx 跨端输出 ali 结果为
+<view @ali bindtap="otherClick">
+    <view onTap="someClick">tap click</view>
+</view>
+```
+上述示例为错误写法，假如srcMode为微信小程序，用上述写法构建输出支付宝小程序时，父节点 bindtap 不会被转为 onTap，在支付宝平台执行时事件会无响应。
+
+正确写法如下：
+```html
+<!--正确示例-->
+<view @ali onTap="otherClick">
+    <view bindtap="someClick">tap click</view>
+</view>
+// 输出 ali 产物
+<view @ali onTap="otherClick">
+    <view onTap="someClick">tap click</view>
+</view>
+```
+有时开发者期望使用 @ali 这种方式仅控制节点的展示，保留节点属性的平台转换能力，为此 Mpx 实现了一个隐式属性条件编译能力
+```html
+<!--srcMode为 wx，输出 ali 时，bindtap 会被正常转换为 onTap-->
+<view @_ali bindtap="someClick">test</view>
+```
+在对应的平台前加一个_，例如@_ali、@_swan、@_tt等，使用该隐式规则仅有条件编译能力，节点属性语法转换能力依旧。
 
 有时候我们不仅需要对节点属性进行条件编译，可能还需要对节点标签进行条件编译。
 
@@ -416,6 +446,13 @@ env 属性维度的编译同样支持对整个节点或者节点标签名进行
 <view @:didi>this is a  view component</view>
 <view mpxTagName@:didi="cover-view">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>
+```
+
 ### 其他注意事项
 
 * 当目标平台为支付宝时，需要启用支付宝最新的component2编译才能保障框架正常工作，关于component2[点此查看详情](https://docs.alipay.com/mini/framework/custom-component-overview)；