DigitalScholl/Learun.Framework.Ultimate V7/LearunApp-2.2.0/docs/platform.md

# 力软框架移动端 · 运行平台差异介绍文档
力软框架移动端支持运行到6个平台，包括 H5、安卓 App、iOS App、微信小程序、支付宝小程序、钉钉小程序。  
这些平台各自存在不同的 API 差异、组件差异、页面渲染差异，甚至存在不同的 bug，需要开发者特别注意。  
  
## 平台差异简介
**App 平台：**  
- 需要云打包，提交应用商店上架审核（安卓 App 可以直接发布 .apk 让使用者安装）；
- 更新版本需要用户重新安装，也可以用 uni-app 提供的 [wgt 热更新](https://ask.dcloud.net.cn/article/35667)；
- 可以使用 uni-app 插件市场的原生组件，实现例如文件选择、文档预览、直播推流等功能；
- App 平台功能强大，支持本地文件操作，定位/联系人/蓝牙/扫码/推送等功能均可使用，与手机系统的交互能力最强。
  
**H5 平台：**
- 手机网页版，发布到服务器，用户用手机访问网站即可使用；
- 发布新版，只需要更新服务器上的网站即可；
- 更新发布最简单，性能优秀，几乎无兼容性问题，还可以使用浏览器独有的 WebAPI 操作 DOM 和 BOM；
- 受浏览器上的功能限制，例如受浏览器跨域请求限制、无法扫码、无法使用蓝牙连接等。

**小程序平台：**
- 需到小程序平台申请 AppID，调试需要使用小程序专用工具，发布需审核；
- 用户端自动推送新版本，更新较方便；
- 可以通讯的域名需要提前配置，小程序中打开网页使用的是平台内置的浏览器；
- 可以深度结合平台自身的功能，例如微信支付、微信卡券、微信运动、支付宝支付、支付宝人脸识别、小程序账号登录等；
- 小程序平台还可以预览 pdf、docx 等文档（钉钉小程序不支持）；
- 小程序支持消息分享，分享给自己的联系人，联系人点击进入可以直接跳转到指定页面；
- 微信小程序功能最强，堪比 App 平台，支付宝小程序较差（缺少很多组件和 API），钉钉小程序最差（缺少大量组件和 API，部分功能完全不支持）。
  
## 条件编译  
不同平台存在差异，代码无法直接通用。例如：H5 平台不能扫码，其他平台可以；H5 平台涉及到跨域通讯限制，其他平台无此问题等。  
uni-app 允许使用条件编译来为每一种平台单独编写一部分代码：[uni-app 条件编译官方文档](https://uniapp.dcloud.io/platform?id=%E6%9D%A1%E4%BB%B6%E7%BC%96%E8%AF%91)。      
  
**注意：**钉钉小程序的条件编译是 `MP-DINGTALK`，文档里没有写；  
**注意：**如果写成 `MP-ALIPAY`，那么这一块的代码支付宝小程序、钉钉小程序都会编译进去；  
只编译到支付宝小程序而不想编译到钉钉小程序，则需要写成嵌套形式。  

  
``` javascript
// #ifdef MP-ALIPAY 
// 【注意】这里面的代码，支付宝小程序和钉钉小程序都会编译进来
// #endif

// #ifdef MP-DINGTALK 
// 这里面的代码，只有钉钉小程序会编译进来
dd.httpRequest()
// #endif

// #ifdef MP-ALIPAY 
// #ifndef MP-DINGTALK 
// 这里面的代码，只有支付宝小程序会编译进来
my.request()
// #endif
// #endif

// #ifdef MP-WEIXIN
// 这里面的代码，只有微信小程序会编译进来
wx.getWeRunData()
// #endif

// #ifdef MP
// 这里面的代码只会编译到所有小程序平台
uni.scanCode()
// #endif

// #ifdef H5
// 这里面的代码只会编译到 H5 平台
window.document.getElementById()
// #endif

// #ifdef APP-VUE
// 这里面的代码只会编译到 App 平台
uni.preloadPage()
plus.io.requestFileSystem()
// #endif
```

## 二次开发须知
通用注意点：
- 【通用】`<canvas>` 组件在不同端的 API 不同，因此需要使用条件编译来进行处理（可以参考 /pages/nworkflow/myflow/sign.vue 中的做法）；
- 【通用】文件上传，H5、小程序一般只能上传图片和视频，App 虽然能上传其他文件，但是 uni-app 原生不支持，需要安装第三方插件，且 iOS 和安卓需要的插件不一样；文化下载，小程序一般看
- 【通用】Vue 生命周期和常规网页不同，存在「页面生命周期」、「应用生命周期」两个概念，请阅读[uni-app 生命周期文档](https://uniapp.dcloud.io/api/lifecycle)了解。
  
微信小程序的注意点：
- 【微信小程序】中，部分标签属于原生组件，例如 `<textarea>` 、`<map>`，任何页面内容都无法覆盖原生组件（除了 `<cover-view>`，但是限制太多），因此在使用诸如 `<textarea>` 的原生组件时，需要特别处理覆盖显示问题；
- 【微信小程序】中使用组件时，组件在页面中的元素节点外侧会被包裹一层元素，例如某个组件名为 `my-component`，那么运行时组件外面会包裹一层 `<my-component>` 的节点；因此在编写涉及到组件的样式时，请慎用 `>` 这个父子级 CSS 选择器，慎用父子级百分比定位，慎用 flex 布局；
- 【微信小程序】基于上一条，给组件自身设置样式，可以使用 `:host { }` 这个选择器，给这个选择器设置的样式适用于组件包裹的标签本身（在上个例子中，如果设置了 `:host { }` 的样式，这些样式适用到 `<my-component>` 这个节点上），注意这个选择器在标记了 `scoped` 的样式块中无效；
  
阿里小程序（阿里=支付宝+钉钉）的注意点：
- 【阿里小程序】组件化方式有较大区别： 在阿里小程序中，组件在页面中的元素节点会直接替换成组件内的节点，这个行为和常规 Vue 的 Web 开发相同；但是使用组件时给组件绑定的 class、style 均会丢失，因此组件需要接受 className（注意不是 class，否则会报错）、style 两个属性，并绑定到组件的根节点的 class、style 属性上，这样才能让组件显示正常；注意此种方式会导致 H5 平台报错，因此需要使用条件编译加以区分；力软框架为所有组件额外开发了一套阿里系专用版本，编译成阿里系小程序时会自动使用，尽可能减少以上问题的出现；
- 【阿里小程序】组件插槽需要特殊处理： 在阿里小程序中，组件的默认插槽如果有默认内容，那么使用组件时将只会显示插槽里的默认内容，因此需要进行特殊判断，推荐使用 `v-if="$slots.$default"` 来判断（其他平台默认插槽位于 `$slots.default`，阿里系小程序多了一个 $ 符号）；具名插槽无此问题；
- 【阿里小程序】中，因为不存在全局 `global` 或 `globalThis`，会导致直接引入 lodash 报错，使用 lodash 时请使用部分引入；力软框架在使用 lodash 的代码文件中均做了部分引入处理（常规方式 `import _ from 'lodash'` 在阿里小程序中报错，需要把 lodash 中用到每一种方法分别写成 `import get from 'lodash/get'` 这种形式）；
- 【阿里小程序】不存在 `page { }` 这个选择器；可以为页面根节点 `<view>` 赋予一个 class 或者 id，然后使用对应的选择器来设置页面样式；
- 【阿里小程序】页面高度如果不是整个屏幕的高度，请附加 `height: 100%; position: absolute;` 这两条样式；
- 【阿里系程序】样式不支持属性选择器，因此在处理例如 checkbox 选中态等情况下需要额外处理；
- 【阿里小程序】CSS 变量 `env(safe-area-inset-bottom)` 在阿里系小程序中获取不到，请使用条件编译额外判断；
- 【钉钉小程序】中，使用 `this.RELAUNCH_TO` 或 `uni.reLaunch` 来跳转页面会导致重新加载整个小程序，`SET_GLOBAL` 中的数据等都将被清空；因此开发钉钉小程序时需要特别注意处理调用 `this.RELAUNCH_TO` 或  `uni.reLaunch` 的情形；
- 【钉钉小程序】中在组件中再使用子组件，有可能绑定事件会报错（尤其是绑定到内部子组件的根节点上的事件）；
- 【钉钉小程序】中在组件中再使用子组件，如果绑定 ref，那么 `this.$refs` 会获取不到子组件，请避免使用（本条请真机调试测试，模拟器上运行正常）。
  
App 平台的注意点：
- 【App】还可以使用 [Plus API](https://ask.dcloud.net.cn/docs/)，这些 API 一般以 `plus.*` 开头，涵盖了文件操作、推送、设备硬件操作等紧密结合手机系统的 API，也是 uni-app 公司开发的；注意小程序平台、H5 平台调用均会报错，因此如果开发多端 App，这一块的代码请使用条件编译；
- 【App】中，部分标签属于原生组件，例如 `<map>`，任何页面内容都无法覆盖原生组件（除了 `<cover-view>`，但是限制太多），因此在使用诸如 `<map>` 的原生组件时，需要特别处理覆盖显示问题。

H5 平台的注意点：
- 【H5】中，存在 HTTP 跨域限制，跨域通讯时返回的响应需要带有 `Access-Control-*` 相关的响应头；
- 【H5】中，如果使用了导航栏和底边栏，uni-app 会在页面顶部和底部用 `<div>` 模拟标题栏和底边栏，这时使用 `top` 、`bottom` 属性获取的相对窗口的定位是不准确的，需要分别替换成 `var(--window-top)` 和 `var(--window-bottom)`；例如某个元素如果需要距离窗口顶部10像素，应该写成 `top: calc(10px + var(--window-top))`；
- 【H5】中，组件在页面中的元素节点外侧会被包裹一层 `<uni-view>` 的元素，请慎用 `>` 这个父子级 CSS 选择器。