全平台小程序开发框架Uni-app重点概览

喜欢ヅ旅行 2022-12-08 05:09 136阅读 0赞

## 1. 通过vue-cli命令行创建Uni-app ##

#### 全局安装vue-cli ####

npm install -g @vue/cli

#### 创建uni-app ####

vue create -p dcloudio/uni-preset-vue my-project

#### 运行、发布uni-app ####

npm run dev:%PLATFORM%
    npm run build:%PLATFORM%

%PLATFORM% 可取值如下：

<table> 
 <thead> 
  <tr> 
   <th>值</th> 
   <th>平台</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>app-plus</td> 
   <td>app平台生成打包资源（支持npm run build:app-plus，可用于持续集成。不支持run，运行调试仍需在HBuilderX中操作）</td> 
  </tr> 
  <tr> 
   <td>h5</td> 
   <td>H5</td> 
  </tr> 
  <tr> 
   <td>mp-alipay</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>mp-baidu</td> 
   <td>百度小程序</td> 
  </tr> 
  <tr> 
   <td>mp-weixin</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>mp-toutiao</td> 
   <td>字节跳动小程序</td> 
  </tr> 
  <tr> 
   <td>mp-qq</td> 
   <td>qq 小程序</td> 
  </tr> 
  <tr> 
   <td>mp-360</td> 
   <td>360 小程序</td> 
  </tr> 
  <tr> 
   <td>quickapp-webview</td> 
   <td>快应用通用</td> 
  </tr> 
  <tr> 
   <td>quickapp-webview-union</td> 
   <td>快应用联盟</td> 
  </tr> 
  <tr> 
   <td>quickapp-webview-huawei</td> 
   <td>快应用华为</td> 
  </tr> 
 </tbody> 
</table>

*  目前使用npm run build:app-plus会在/dist/build/app-plus下生成app打包资源。如需制作wgt包，将app-plus中的文件压缩成zip（注意：不要包含app-plus目录），再重命名为$\{appid\}.wgt， appid为manifest.json文件中的appid。
 *  dev 模式编译出的各平台代码存放于根目录下的 /dist/dev/目录，打开各平台开发工具选择对应平台目录即可进行预览（h5 平台不会在此目录，存在于缓存中）；
 *  build 模式编译出的各平台代码存放于根目录下的 /dist/build/ 目录，发布时选择此目录进行发布；
 *  dev 和 build 模式的区别：

1.  dev 模式有 SourceMap 可以方便的进行断点调试；
2.  build 模式会将代码进行压缩，体积更小更适合发布为正式版应用；
3.  进行 环境判断 时，dev 模式 process.env.NODE\_ENV 的值为 development，build 模式 process.env.NODE\_ENV 的值为 production。

## 2. 使用cli创建项目和使用HBuilderX可视化界面创建项目的区别 ##

#### 编译器的区别 ####

*  cli 创建的项目，编译器安装在项目下。并且不会跟随HBuilderX升级。如需升级编译器，执行 npm update，或者手动修改 package.json 中的 uni 相关依赖版本后执行 npm install。更新后可能会有新增的依赖并不会自动安装，手动安装缺少的依赖即可。
 *  HBuilderX可视化界面创建的项目，编译器在HBuilderX的安装目录下的plugin目录，随着HBuilderX的升级会自动升级编译器。
 *  已经使用cli创建的项目，如果想继续在HBuilderX里使用，可以把工程拖到HBuilderX中。注意如果是把整个项目拖入HBuilderX，则编译时走的是项目下的编译器。如果是把src目录拖入到HBuilderX中，则走的是HBuilderX安装目录下plugin目录下的编译器。
 *  cli版如果想安装less、scss、ts等编译器，需自己手动npm安装。在HBuilderX的插件管理界面安装无效，那个只作用于HBuilderX创建的项目。

#### 开发工具的区别 ####

*  cli创建的项目，内置了d.ts，同其他常规npm库一样，可在vscode、webstorm等支持d.ts的开发工具里正常开发并有语法提示。
 *  使用HBuilderX创建的项目不带d.ts，HBuilderX内置了uni-app语法提示库。如需把HBuilderX创建的项目在其他编辑器打开并且补充d.ts，可以在项目下先执行 npm init，然后npm i @types/uni-app -D，来补充d.ts。
 *  但vscode等其他开发工具，在vue或uni-app领域，开发效率比不过HBuilderX。详见：https://ask.dcloud.net.cn/article/35451
 *  发布App时，仍然需要使用HBuilderX。其他开发工具无法发布App，但可以发布H5、各种小程序。如需开发App，可以先在HBuilderX里运行起来，然后在其他编辑器里修改保存代码，代码修改后会自动同步到手机基座。
 *  如果使用cli创建项目，那下载HBuilderX时只需下载10M的标准版即可。因为编译器已经安装到项目下了。

## 3. 生命周期 ##

#### 应用生命周期 ####

uni-app 支持如下应用生命周期函数：

<table> 
 <thead> 
  <tr> 
   <th>函数名</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>onLaunch</td> 
   <td>当uni-app 初始化完成时触发（全局只触发一次）</td> 
  </tr> 
  <tr> 
   <td>onShow</td> 
   <td>当 uni-app 启动，或从后台进入前台显示</td> 
  </tr> 
  <tr> 
   <td>onHide</td> 
   <td>当 uni-app 从前台进入后台</td> 
  </tr> 
  <tr> 
   <td>onError</td> 
   <td>当 uni-app 报错时触发</td> 
  </tr> 
  <tr> 
   <td>onUniNViewMessage</td> 
   <td>对 nvue 页面发送的数据进行监听，可参考 nvue 向 vue 通讯</td> 
  </tr> 
  <tr> 
   <td>onUnhandledRejection</td> 
   <td>对未处理的 Promise 拒绝事件监听函数（2.8.1+）</td> 
  </tr> 
  <tr> 
   <td>onPageNotFound</td> 
   <td>页面不存在监听函数</td> 
  </tr> 
  <tr> 
   <td>onThemeChange</td> 
   <td>监听系统主题变化</td> 
  </tr> 
 </tbody> 
</table>

注意：

*  应用生命周期仅可在App.vue中监听，在其它页面监听无效。
 *  onlaunch里进行页面跳转，如遇白屏报错，请参考https://ask.dcloud.net.cn/article/35942

#### 页面生命周期 ####

uni-app 支持如下页面生命周期函数：

<table> 
 <thead> 
  <tr> 
   <th>函数名</th> 
   <th>说明</th> 
   <th>平台差异说明</th> 
   <th>最低版本</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>onLoad</td> 
   <td>监听页面加载，其参数为上个页面传递的数据，参数类型为Object（用于页面传参）</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onShow</td> 
   <td>监听页面显示。页面每次出现在屏幕上都触发，包括从下级页面点返回露出当前页面</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onReady</td> 
   <td>监听页面初次渲染完成。注意如果渲染速度快，会在页面进入动画完成前触发</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onHide</td> 
   <td>监听页面隐藏</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onUnload</td> 
   <td>监听页面卸载</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onResize</td> 
   <td>监听窗口尺寸变化</td> 
   <td>App、微信小程序</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onPullDownRefresh</td> 
   <td>监听用户下拉动作，一般用于下拉刷新</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onReachBottom</td> 
   <td>页面上拉触底事件的处理函数</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onTabItemTap</td> 
   <td>点击 tab 时触发，参数为Object，具体见下方注意事项</td> 
   <td>微信小程序、百度小程序、H5、App（自定义组件模式）</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onShareAppMessage</td> 
   <td>用户点击右上角分享</td> 
   <td>微信小程序、百度小程序、字节跳动小程序、支付宝小程序</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onPageScroll</td> 
   <td>监听页面滚动，参数为Object</td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onNavigationBarButtonTap</td> 
   <td>监听原生标题栏按钮点击事件，参数为Object</td> 
   <td>5+ App、H5</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onBackPress</td> 
   <td>监听页面返回，返回 event = {from:backbutton、 navigateBack} ，backbutton 表示来源是左上角返回按钮或 android 返回键；navigateBack表示来源是 uni.navigateBack ；详细说明及使用：onBackPress 详解</td> 
   <td>App、H5</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>onNavigationBarSearchInputChanged</td> 
   <td>监听原生标题栏搜索输入框输入内容变化事件</td> 
   <td>App、H5</td> 
   <td>1.6.0</td> 
  </tr> 
  <tr> 
   <td>onNavigationBarSearchInputConfirmed</td> 
   <td>监听原生标题栏搜索输入框搜索事件，用户点击软键盘上的“搜索”按钮时触发</td> 
   <td>App、H5</td> 
   <td>1.6.0</td> 
  </tr> 
  <tr> 
   <td>onNavigationBarSearchInputClicked</td> 
   <td>监听原生标题栏搜索输入框点击事件</td> 
   <td>App、H5</td> 
   <td>1.6.0</td> 
  </tr> 
  <tr> 
   <td>onShareTimeline</td> 
   <td>监听用户点击右上角转发到朋友圈</td> 
   <td>微信小程序</td> 
   <td>2.8.1+</td> 
  </tr> 
  <tr> 
   <td>onAddToFavorites</td> 
   <td>监听用户点击右上角收藏</td> 
   <td>微信小程序</td> 
   <td>2.8.1+</td> 
  </tr> 
 </tbody> 
</table>

## 4. 页面栈 ##

框架以栈的形式管理当前所有页面， 当发生路由切换的时候，页面栈的表现如下：

<table> 
 <thead> 
  <tr> 
   <th>路由方式</th> 
   <th>页面栈表现</th> 
   <th>触发时机</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>初始化</td> 
   <td>新页面入栈</td> 
   <td>uni-app 打开的第一个页面</td> 
  </tr> 
  <tr> 
   <td>打开新页面</td> 
   <td>新页面入栈</td> 
   <td>调用 API uni.navigateTo 、使用组件 <code>&lt;navigator open-type="navigate"/&gt;</code></td> 
  </tr> 
  <tr> 
   <td>页面重定向</td> 
   <td>当前页面出栈，新页面入栈</td> 
   <td>调用 API uni.redirectTo 、使用组件 <code>&lt;navigator open-type="redirectTo"/&gt;</code></td> 
  </tr> 
  <tr> 
   <td>页面返回</td> 
   <td>页面不断出栈，直到目标返回页</td> 
   <td>调用 API uni.navigateBack 、使用组件 <code>&lt;navigator open-type="navigateBack"/&gt;</code> 、用户按左上角返回按钮、安卓用户点击物理back按键</td> 
  </tr> 
  <tr> 
   <td>Tab 切换</td> 
   <td>页面全部出栈，只留下新的 Tab 页面</td> 
   <td>调用 API uni.switchTab 、使用组件 <code>&lt;navigator open-type="switchTab"/&gt;</code> 、用户切换 Tab</td> 
  </tr> 
  <tr> 
   <td>重加载</td> 
   <td>页面全部出栈，只留下新的页面</td> 
   <td>调用 API uni.reLaunch 、使用组件 <code>&lt;navigator open-type="reLaunch"/&gt;</code></td> 
  </tr> 
 </tbody> 
</table>

## 5. 运行环境判断 ##

uni-app 可通过 `process.env.NODE_ENV` 判断当前环境是开发环境还是生产环境。一般用于连接测试服务器或生产服务器的动态切换。

*  在HBuilderX 中，点击“运行”编译出来的代码是开发环境，点击“发行”编译出来的代码是生产环境。
 *  cli模式下，是通行的编译环境处理方式。

if(process.env.NODE_ENV === 'development'){ 
        console.log('开发环境')
    }else{ 
        console.log('生产环境')
    }

## 6. Uni-app中使用nvue ##

### 介绍 ###

uni-app App端内置了一个基于 weex 改进的原生渲染引擎，提供了原生渲染能力。  
在App端，如果使用vue页面，则使用webview渲染；如果使用nvue页面(native vue的缩写)，则使用原生渲染。一个App中可以同时使用两种页面，比如首页使用nvue，二级页使用vue页面，hello uni-app示例就是如此。  
虽然nvue也可以多端编译，输出H5和小程序，但nvue的css写法受限，所以如果你不开发App，那么不需要使用nvue。  
以往的 weex ，有个很大的问题是它只是一个高性能的渲染器，没有足够的API能力（比如各种push sdk集成、蓝牙等能力调用），使得开发时非常依赖原生工程师协作，开发者本来想节约成本，结果需要前端、iOS、Android 3拨人开发，适得其反。 nvue 解决了这个问题，让前端工程师可以直接开发完整 App，并提供丰富的插件生态和云打包。这些组合方案，帮助开发者切实的提高效率、降低成本。  
同时uni-app扩展了weex原生渲染引擎的很多排版能力，修复了很多bug。比如：

*  Android端良好支持边框阴影
 *  iOS端支持高斯模糊，详情
 *  可实现区域滚动长列表+左右拖动列表+吸顶的复杂排版效果
 *  优化圆角边框绘制性能

### 适用场景 ###

nvue的组件和API写法与vue页面一致，其内置组件还比vue页面内置组件增加了更多，详见。但nvue在css的写法限制较多，具体如下：

*  nvue的css仅支持flex布局，是webview的css语法的子集。这是因为操作系统原生排版不支持非flex之外的web布局。当然flex足以排布出各种页面，只是写法需要适应。
 *  nvue的css，在选择器方面支持的较少，只支持简单的class=“classA”。
 *  class 进行绑定时只支持数组语法。
 *  有些web的css属性在nvue里无法支持，比如背景图。但可以使用image组件和层级来实现类似web中的背景效果。因为原生开发本身也没有web这种背景图概念

如果你熟悉 weex或react native 开发，那么 nvue 是你的更优选择，能切实提升你的开发效率，降低成本。  
如果你是web前端，不熟悉原生排版，那么建议你仍然以使用vue页面为主，在App端某些vue页面表现不佳的场景下使用 nvue 作为强化补充。这些场景如下：

*  需要高性能的区域长列表或瀑布流滚动。webview的页面级长列表滚动时没有性能问题的（就是滚动条覆盖webview整体高度），但页面中某个区域做长列表滚动，则需要使用nvue的list、recycle-list、waterfall等组件。这些组件的性能要高于vue页面里的区域滚动组件scroll-view。
 *  复杂高性能的自定义下拉刷新。uni-app的pages.json里可以配置原生下拉刷新，但引擎内置的下拉刷新样式只有雪花和circle圈2种样式。如果你需要自己做复杂的下拉刷新，推荐使用nvue的refresh组件。当然插件市场里也有很多vue下的自定义下拉刷新插件，只要是基于renderjs或wxs的，性能也可以商用，只是没有nvue的refresh组件更极致。
 *  左右拖动的长列表。在webview里，通过swiper+scroll-view实现左右拖动的长列表，前端模拟下拉刷新，这套方案的性能不好。此时推荐使用nvue，比如新建uni-app项目时的新闻示例模板，就采用了nvue，切换很流畅。
 *  实现区域滚动长列表+左右拖动列表+吸顶的复杂排版效果，效果可参考hello uni-app模板里的swiper-list
 *  如需要将软键盘右下角按钮文字改为“发送”，则需要使用nvue。比如聊天场景，除了软键盘右下角的按钮文字处理外，还涉及聊天记录区域长列表滚动，适合nvue来做。
 *  解决前端控件无法覆盖原生控件的层级问题。当你使用map、video、live-pusher等原生组件时，会发现前端写的view等组件无法覆盖原生组件，层级问题处理比较麻烦，此时使用nvue更好。或者在vue页面上也可以覆盖一个subnvue（一种非全屏的nvue页面覆盖在webview上），以解决App上的原生控件层级问题。
 *  如深度使用map组件，建议使用nvue。除了层级问题，App端nvue文件的map功能更完善，和小程序拉齐度更高，多端一致性更好。
 *  如深度使用video，建议使用nvue。比如如下2个场景：video内嵌到swiper中，以实现抖音式视频滑动切换，例子见插件市场；nvue的视频全屏后，通过cover-view实现内容覆盖，比如增加文字标题、分享按钮。
 *  直播推流：nvue下有live-pusher组件，和小程序对齐，功能更完善，也没有层级问题。
 *  对App启动速度要求极致化。App端v3编译器模式下，如果首页使用nvue且在manifest里配置fast模式，那么App的启动速度可以控制在1秒左右。而使用vue页面的话，App的启动速度一般是3秒起，取决于你的代码性能和体积。

但注意，在某些场景下，nvue不如vue页面，如下：

*  canvas。nvue的canvas性能不高，尤其是Android App平台，所以这个组件干脆没有内置，而是需要单独引入。操作canvas动画，最高性能的方式是使用vue页面的renderjs技术，在hello uni-app里的canvas示例就是如此。
 *  动态横竖屏。nvue页面的css不支持媒体查询，所以横竖屏动态切换、动态适配屏幕是很困难的。

### 纯原生渲染模式 ###

uni-app在App端，支持vue页面和nvue页面混搭、互相跳转。也支持纯nvue原生渲染。  
启用纯原生渲染模式，可以减少App端的包体积、减少使用时的内存占用。因为webview渲染模式的相关模块将被移除。  
在manifest.json源码视图的"app-plus"下配置"renderer":“native”，即代表App端启用纯原生渲染模式。此时pages.json注册的vue页面将被忽略，vue组件也将被原生渲染引擎来渲染。  
如果不指定该值，默认是不启动纯原生渲染的。

// manifest.json 
    {     
        // ... 
         /* App平台特有配置 */    
        "app-plus": {     
            "renderer": "native", //App端纯原生渲染模式
        }    
    }

### weex编译模式和uni-app编译模式 ###

weex的组件和jsapi，与uni-app不同。uni-app与微信小程序相同。  
考虑到weex用户的迁移，uni-app 也支持weex的代码写法。在manifest.json中可以配置使用weex编译模式或uni-app编译模式。选择weex编译模式时将不支持uni-app的组件和jsapi，需要开发者参考weex官方文档的写法来写代码。 比如 weex 编译模式用`<div>`。uni-app 编译模式则使用`<view>`。  
一般情况建议使用uni-app模式，除非历史weex代码较多，需要逐步过渡。同时注意weex编译模式的切换是项目级的，不支持同项目下某个nvue页面使用weex模式，另一个nvue页面使用uni-app模式。

<table> 
 <thead> 
  <tr> 
   <th></th> 
   <th>weex编译模式</th> 
   <th>uni-app编译模式</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>平台</td> 
   <td>仅App</td> 
   <td>所有端，包含小程序和H5</td> 
  </tr> 
  <tr> 
   <td>组件</td> 
   <td>weex组件如div</td> 
   <td>uni-app组件如view</td> 
  </tr> 
  <tr> 
   <td>生命周期</td> 
   <td>只支持weex生命周期</td> 
   <td>支持所有uni-app生命周期</td> 
  </tr> 
  <tr> 
   <td>JS API</td> 
   <td>weex API、uni API、Plus API</td> 
   <td>weex API、uni API、Plus API</td> 
  </tr> 
  <tr> 
   <td>单位</td> 
   <td>750px是屏幕宽度，wx是固定像素单位</td> 
   <td>750rpx是屏幕宽度，px是固定像素单位</td> 
  </tr> 
  <tr> 
   <td>全局样式</td> 
   <td>手动引入</td> 
   <td>app.vue的样式即为全局样式</td> 
  </tr> 
  <tr> 
   <td>页面滚动</td> 
   <td>必须给页面套或组件</td> 
   <td>默认支持页面滚动</td> 
  </tr> 
 </tbody> 
</table>

在 manifest.json 中修改2种编译模式，manifest.json -> app-plus -> nvueCompiler 切换编译模式。  
nvueCompiler 有两个值：

*  weex
 *  uni-app

// manifest.json 
    {     
        // ... 
         /* App平台特有配置 */    
        "app-plus": {     
            "nvueCompiler":"uni-app" //是否启用 uni-app 模式 
        }    
    }

*  如果没有在manifest里明确配置，默认是weex模式。这是为了向下兼容。
 *  weex 编译模式不支持 onNavigationBarButtonTap 生命周期函数的写法。在 nvue 中监听原生标题栏按钮点击事件，详见：uni.onNavigationBarButtonTap。
 *  weex编译模式不支持onShow生命周期，但熟悉5+的话，可利用监听webview的addEventListener show事件实现onShow效果。
 *  weex 编译模式不支持vuex。
 *  nvue 的页面跳转，与 weex 不同，仍然遵循 uni-app 的路由模型。vue 页面和 nvue 页面之间不管怎么跳转，都遵循这个模型。包括 nvue 页面跳向 nvue 页面。每个页面都需要在 pages.json 中注册，调用 uni-app 的 路由 API 进行跳转。
 *  原生开发没有页面滚动的概念，页面内容高过屏幕高度并不会自动滚动，只有部分组件可滚动（list、waterfall、scroll-view/scroller），要滚得内容需要套在可滚动组件下。这不符合前端开发的习惯，所以在 nvue 编译为 uni-app模式时，给页面外层自动套了一个 scroller，页面内容过高会自动滚动。（组件不会套，页面有recycle-list时也不会套）。 可以设置不自动套。

{ 
      "path": "",
      "style": { 
        "disableScroll": true // 不嵌套 scroller
      }
    }

weex 编译模式下支持使用 weex ui ，例子见：https://ext.dcloud.net.cn/plugin?id=442。但相比uni-app插件市场及官方uni ui而言，weex语法的组件生态还是比较欠缺的。

### 快速上手 ###

#### 1. 新建 nvue 页面 ####

在HBuilderX的 uni-app 项目中，新建页面，弹出界面右上角可以选择是建立vue页面还是nvue页面，或者2个同时建。  
不管是vue页面还是nvue页面，都需要在pages.json中注册。如果在HBuilderX中新建页面是会自动注册的，如果使用其他编辑器，则需要自行在pages.json里注册。  
如果一个页面路由下同时有vue页面和nvue页面，即出现同名的vue和nvue文件。那么在App端，会仅使用nvue页面，同名的vue文件将不会被编译到App端。而在非App端，会优先使用vue页面。  
如果不同名，只有nvue页面，则在非app端，只有uni-app编译模式的nvue文件才会编译。

#### 2. 开发 nvue 页面 ####

nvue 页面结构同 vue, 由 template、style、script 构成。

*  template： 模板写法、数据绑定同 vue。组件支持2种模式，1、 weex 组件，同weex写法，参考：weex 内置组件；2、uni-app组件，同uni-app写法。
 *  style：由于采用原生渲染，并非所有浏览器的 css 均支持，布局模型只支持 flex 布局，虽然不会造成某些界面布局无法实现，但写法要注意。详见：weex 样式
 *  script：写法同 vue，并支持3种API：

1.  weex API ：仅支持App端，uni-app编译模式也可使用。使用前需先引入对应模块，参考：weex 模块引入
2.  uni API：https://uniapp.dcloud.io/api/README
3.  plus API：仅支持App端。http://www.html5plus.org/doc/h5p.html

#### 3. 调试 nvue 页面 ####

HBuilderX内置了weex调试工具的强化版，包括审查界面元素、看log、debug打断点

### nvue 和 vue 相互通讯 ###

在 uni-app 中，nvue 和 vue 页面可以混搭使用。  
推荐使用uni. o n , u n i . on,uni. on,uni.emit的方式进行页面通讯，旧的通讯方式（uni.postMessage及plus.webview.postMessageToUniNView）不再推荐使用。

#### 通讯实现方式 ####

// 接收信息的页面
    // $on(eventName, callback) 
    uni.$on('page-popup', (data) => {   
        console.log('标题：' + data.title)
        console.log('内容：' + data.content)
    })  
    
    // 发送信息的页面
    // $emit(eventName, data) 
    uni.$emit('page-popup', {   
        title: '我是title',  
        content: '我是content'  
    });

使用此页面通讯时注意事项：要在页面卸载前，使用 uni.$off 移除事件监听器。

### nvue 向 vue 通讯（已过期，推荐使用上面的`uni.$on`、`uni.$emit`） ###

步骤：

1.  在 nvue 使用 uni.postMessage(data) 发送数据通讯，data 为 JSON 格式（键值对的值仅支持String）。
2.  在 App.vue 里使用 onUniNViewMessage 进行监听。

代码示例：

//test.nvue
    <template>
        <div @click="test">
            <text>点击页面发送数据</text>
        </div>
    </template>
    <script> export default { methods: { test(e) { uni.postMessage({ test: "数据",value:"数据"}); } } } </script>
    //App.vue
    <script> export default { onUniNViewMessage:function(e){ console.log("App.vue收到数据") console.log(JSON.stringify(e.data)) }, onLaunch: function() { console.log('App Launch'); } } </script>

### vue 向 nvue 通讯（已过期，推荐使用上面的`uni.$on`、`uni.$emit`） ###

步骤：

1.  在 vue 里使用 plus.webview.postMessageToUniNView(data,nvueId) 发送消息，data 为 JSON 格式（键值对的值仅支持String），nvueId 为 nvue 所在 webview 的 id，webview的 id 获取方式参考：$getAppWebview()。
2.  在 nvue 里引用 globalEvent 模块监听 plusMessage 事件，如下：

const globalEvent = weex.requireModule('globalEvent');
    globalEvent.addEventListener("plusMessage", e => { 
      console.log(e.data);//得到数据
    });

代码示例：

// index.nvue
    <template>
        <div @click="test">
            <text>点击页面发送数据{
       {num}}</text>
        </div>
    </template>
    <script>
        const globalEvent = weex.requireModule('globalEvent');
        export default {
            data() {
                return {
                    num: "0"
                }
            },
            created() {
                globalEvent.addEventListener("plusMessage", e => {
                    console.log(e.data);
                    if (e.data.num) { //存在num时才赋值，在nvue里调用uni的API也会触发plusMessage事件，所以需要判断需要的数据是否存在
                        this.num = e.data.num
                    }
                });
            },
            methods: {
                test(e) {
                    uni.navigateTo({
                        url: '../test/test'
                    })
                }
            }
        }

// test.vue
    <template>
        <view>
            <button type="primary" @click="test">点击改变nvue的数据</button>
        </view>
    </template>
    <script> export default { methods: { test() { var pages = getCurrentPages(); var page = pages[pages.length - 2]; var currentWebview = page.$getAppWebview(); plus.webview.postMessageToUniNView({ num: "123" }, currentWebview.id); uni.navigateBack() } } } </script>

### vue 和 nvue 共享的变量和数据 ###

除了通信事件，vue 和 nvue 页面之间还可以共享变量和存储。 uni-app提供的共享变量和数据的方案如下：

#### 1. vuex: ####

自HBuilderX 2.2.5起，nvue支持vuex。这是vue官方的状态管理工具。  
注意：

*  不支持直接引入store使用，可以使用mapState、mapGetters、mapMutations等辅助方法或者使用this.$store

#### 2. uni.storage: ####

vue和nvue页面可以使用相同的uni.storage存储。这个存储是持久化的。 比如登陆状态可以保存在这里。  
App端还支持plus.sqlite，也是共享通用的。

#### 3. globalData: ####

小程序有globalData机制，这套机制在uni-app里也可以使用，全端通用。 在App.vue文件里定义globalData，如下：

js中操作globalData的方式如下：`getApp().globalData.text = 'test'`  
如果需要把globalData的数据绑定到页面上，可在页面的onShow声明周期里进行变量重赋值。

### nvue 里使用 BindingX ###

uni-app是逻辑层和视图层分离的。此时会产生两层通信成本。比如拖动视图层的元素，如果在逻辑层不停接收事件，因为通信损耗会产生不顺滑的体验。  
BindingX是weex提供的一种预描述交互语法。由原生解析BindingX规则，按此规则处理视图层的交互和动效。不再实时去js逻辑层运行和通信。  
BindingX类似一种强化版的css，运行性能高，但没有js那样足够强的编程灵活性。  
uni-app 内置了 BindingX，可在 nvue 中使用 BindingX 完成复杂的动画效果。

*  从HBuilderX 2.3.4起，uni-app 编译模式可直接引用`uni.requireNativePlugin('bindingx')`模块，weex 模式还需使用 npm 方式引用。
 *  BindingX demo示例可参考 BindingX 示例 里 vue 的相关示例，将实验田里的 vue 代码拷贝到 nvue 文件里即可。

代码示例：

<template>
        <div class="container">
            <div ref="b1" class="btn" style="background-color:#6A1B9A" @click="clickBtn">
                <text class="text">A</text>
            </div>
            <div ref="b2" class="btn" style="background-color:#0277BD" @click="clickBtn">
                <text class="text">B</text>
            </div>
            <div ref="b3" class="btn" style="background-color:#FF9800" @click="clickBtn">
                <text class="text">C</text>
            </div>
            <div ref="main_btn" class="btn" @click="clickBtn">
                <image class="image" ref="main_image" src="https://gw.alicdn.com/tfs/TB1PZ25antYBeNjy1XdXXXXyVXa-128-128.png" />
            </div>
        </div>
    </template>
    <script> const Binding = uni.requireNativePlugin('bindingx'); module.exports = { data: { isExpanded: false }, methods: { getEl: function(el) { if (typeof el === 'string' || typeof el === 'number') return el; if (WXEnvironment) { return el.ref; } else { return el instanceof HTMLElement ? el : el.$el; } }, collapse: function() { let main_btn = this.getEl(this.$refs.main_btn); let main_image = this.getEl(this.$refs.main_image); let b1 = this.getEl(this.$refs.b1); let b2 = this.getEl(this.$refs.b2); let b3 = this.getEl(this.$refs.b3); let main_binding = Binding.bind({ eventType: 'timing', exitExpression: 't>800', props: [{ element: main_image, property: 'transform.rotateZ', expression: 'easeOutQuint(t,45,0-45,800)' }, { element: main_btn, property: 'background-color', expression: "evaluateColor('#607D8B','#ff0000',min(t,800)/800)" }] }, function(res) { if (res.state === 'exit') { Binding.unbind({ token: main_binding.token, eventType: 'timing' }) } }); let btn_binding = Binding.bind({ eventType: 'timing', exitExpression: 't>800', props: [{ element: b1, property: 'transform.translateY', expression: "easeOutQuint(t,-150,150,800)" }, { element: b2, property: 'transform.translateY', expression: "t<=100?0:easeOutQuint(t-100,-300,300,700)" }, { element: b3, property: 'transform.translateY', expression: "t<=200?0:easeOutQuint(t-200,-450,450,600)" }] }, function(res) { if (res.state === 'exit') { Binding.unbind({ token: btn_binding.token, eventType: 'timing' }) } }) }, expand: function() { let main_btn = this.getEl(this.$refs.main_btn); let main_image = this.getEl(this.$refs.main_image); let b1 = this.getEl(this.$refs.b1); let b2 = this.getEl(this.$refs.b2); let b3 = this.getEl(this.$refs.b3); let main_binding = Binding.bind({ eventType: 'timing', exitExpression: 't>100', props: [{ element: main_image, property: 'transform.rotateZ', expression: 'linear(t,0,45,100)' }, { element: main_btn, property: 'background-color', expression: "evaluateColor('#ff0000','#607D8B',min(t,100)/100)" }] }, function(res) { if (res.state === 'exit') { Binding.unbind({ token: main_binding.token, eventType: 'timing' }) } }); let btn_binding = Binding.bind({ eventType: 'timing', exitExpression: 't>800', props: [{ element: b1, property: 'transform.translateY', expression: "easeOutBounce(t,0,0-150,800)" }, { element: b2, property: 'transform.translateY', expression: "t<=100?0:easeOutBounce(t-100,0,0-300,700)" }, { element: b3, property: 'transform.translateY', expression: "t<=200?0:easeOutBounce(t-200,0,0-450,600)" }] }, function(res) { if (res.state === 'exit') { Binding.unbind({ token: btn_binding.token, eventType: 'timing' }) } }) }, clickBtn: function(e) { if (this.isExpanded) { this.collapse(); } else { this.expand(); } this.isExpanded = !this.isExpanded; } } } </script>
    <style> .container { flex: 1; } .image { width: 60px; height: 60px; } .text { color: #ffffff; font-size: 30px; } .btn { width: 100px; height: 100px; background-color: #ff0000; align-items: center; justify-content: center; position: absolute; border-radius: 50px; bottom: 25px; right: 25px; } </style>

注意：

*  暂时不要在expression内使用origin

### nvue 里使用 HTML5Plus API ###

*  nvue页面可直接使用plus的API，并且不需要等待plus ready。

### nvue 里不支持的 uni-app API ###

nvue 支持大部分 uni-app API ，下面只列举目前还不支持的 API 。

#### 动画 ####

<table> 
 <thead> 
  <tr> 
   <th>API</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>uni.createAnimation()</td> 
   <td>创建一个动画实例</td> 
  </tr> 
 </tbody> 
</table>

#### 滚动 ####

<table> 
 <thead> 
  <tr> 
   <th>API</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>uni.pageScrollTo()</td> 
   <td>将页面滚动到目标位置</td> 
  </tr> 
 </tbody> 
</table>

#### 绘画 ####

canvas API使用，详见canvas文档。

#### 节点布局交互 ####

<table> 
 <thead> 
  <tr> 
   <th>API</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>uni.createIntersectionObserver()</td> 
   <td>创建并返回一个 IntersectionObserver 对象实例</td> 
  </tr> 
 </tbody> 
</table>

### nvue开发与vue开发的常见区别 ###

基于原生引擎的渲染，虽然还是前端技术栈，但和web开发肯定是有区别的。

*  nvue 页面控制显隐只可以使用v-if不可以使用v-show。
 *  nvue 页面只能使用 flex 布局，不支持其他布局方式。页面开发前，首先想清楚这个页面的纵向内容有什么，哪些是要滚动的，然后每个纵向内容的横轴排布有什么，按 flex 布局设计好界面。
 *  原生开发没有页面滚动的概念，页面内容高过屏幕高度并不会自动滚动，只有部分组件可滚动（list、waterfall、scroll-view/scroller），要滚得内容需要套在可滚动组件下。这不符合前端开发的习惯，所以在 nvue 编译为 uni-app模式时，给页面外层自动套了一个 scroller，页面内容过高会自动滚动。（组件不会套，页面有recycle-list时也不会套）。后续会提供配置，可以设置不自动套。
 *  文字内容，必须、只能在  组件下。不能在
    
    、的text区域里直接写文字。否则即使渲染了，也无法绑定js里的变量。
 *  只有text标签可以设置字体大小，字体颜色。
 *  布局不能使用百分比、没有媒体查询。
 *  nvue 切换横竖屏时可能导致样式出现问题，建议有 nvue 的页面锁定手机方向。
 *  支持的css有限，不过并不影响布局出你需要的界面，flex还是非常强大的。
 *  不支持背景图。但可以使用image组件和层级来实现类似web中的背景效果。因为原生开发本身也没有web这种背景图概念。
 *  css选择器支持的比较少，只能使用 class 选择器。详见weex的样式文档
 *  class 进行绑定时只支持数组语法。
 *  nvue页面没有bounce回弹效果，只有几个列表组件有bounce效果，包括 list、recycle-list、waterfall。
 *  Android端在一个页面内使用大量圆角边框会造成性能问题，尤其是多个角的样式还不一样的话更耗费性能。应避免这类使用。
 *  nvue 的各组件在安卓端默认是透明的，如果不设置background-color，可能会导致出现重影的问题。
 *  在 App.vue 中定义的全局js变量不会在 nvue 页面生效。globalData和vuex是生效的。
 *  App.vue 中定义的全局css，对nvue和vue页面同时生效。如果全局css中有些css在nvue下不支持，编译时控制台会报警，建议把这些不支持的css包裹在条件编译里，`APP-PLUS-NVUE`
 *  不能在 style 中引入字体文件，nvue 中字体图标的使用参考：weex 加载自定义字体。如果是本地字体，可以用plus.io的API转换路径。
 *  目前不支持在 nvue 页面使用 typescript/ts。
 *  nvue 页面关闭原生导航栏时，想要模拟状态栏，可以参考：https://ask.dcloud.net.cn/article/35111。但是，仍然强烈建议在nvue页面使用原生导航栏。nvue的渲染速度再快，也没有原生导航栏快。原生排版引擎解析json绘制原生导航栏耗时很少，而解析nvue的js绘制整个页面的耗时要大的多，尤其在新页面进入动画期间，对于复杂页面，没有原生导航栏会在动画期间产生整个屏幕的白屏或闪屏。
 *  nvue 页面的布局排列方向默认为竖排（column），如需改变布局方向，可以在 manifest.json -> app-plus -> nvue -> flex-direction 节点下修改，仅在 uni-app 模式下生效。
 *  nvue页面编译为H5、小程序时，会做一件css默认值对齐的工作。因为weex渲染引擎只支持flex，并且默认flex方向是垂直。而H5和小程序端，使用web渲染，默认不是flex，并且设置display:flex后，它的flex方向默认是水平而不是垂直的。所以nvue编译为H5、小程序时，会自动把页面默认布局设为flex、方向为垂直。当然开发者手动设置后会覆盖默认设置。  
    下面有些正确和错误的写法示例对比：
 *  选择器仅支持class 选择器

/* 错误 */
    #id { }
    .a .b .c { }
    .a > .b { }
    
    /* 正确 */
    .class { }

*  border 不支持简写

/* 错误 */
    .class { 
        border: 1px red solid;
    }
    
    /* 正确 */
    .class { 
        border-width: 1px;
        border-style: solid;
        border-color: red;
    }

*  background 不支持简写

/* 错误 */
    .class { 
        background: red;
    }
    
    /* 正确 */
    .class { 
        background-color: red;
    }

*  nvue的uni-app编译模式下，App.vue 中的样式，会编译到每个 nvue文件。对于共享样式，如果有不合法属性控制台会给出警告，可以通过条件编译APP-PLUS-NVUE屏蔽 App 中的警告。

/* 错误 */
    /* 控制台警告： WARNING: `border` is not a standard property name (may not be supported) WARNING: `-webkit-transform` is not a standard property name (may not be supported) */
    .class { 
        border: 1px red solid;
      -webkit-transform: scaleY(.5);
    }
    
    /* 正确 */
    .class { 
        border-width: 1px;
        border-style: solid;
        border-color: red;
      /* #ifndef APP-PLUS-NVUE */
      -webkit-transform: scaleY(.5);
      /* #endif*/
    }

### Android平台阴影(box-shadow)问题 ###

Android平台weex对阴影样式(box-shadow)支持不完善，如设置圆角边框时阴影样式显示不正常、设置动画时在Android7上显示不正常、在Android10上出现闪烁现象等。为解决这些问题，从HBuilderX 2.4.7起，新增elevation属性（组件的属性，不是css样式）设置组件的层级，Number类型，层级值越大阴影越明显，阴影效果也与组件位置有关，越靠近页面底部阴影效果越明显  
用法：

注意：

*  设置elevation属性产生的阴影暂时无法修改颜色
 *  为了避免elevation属性的阴影效果与阴影样式(box-shadow)冲突，设置elevation属性后box-shadow样式失效
 *  使用elevation需要阴影元素的父元素大于阴影范围，否则会对阴影进行裁剪
 *  IOS不支持elevation属性，请使用box-shadow设置阴影

### iOS平台下拉组件refresh组件注意问题 ###

iOS平台默认情况下滚动容器组件（如list、waterfall组件）内容不足时，由于没有撑满容器的可视区域会导致无法上下滚动，此时无法操作下拉刷新功能，无法触发refresh组件的@refresh、@pullingdown事件。 此时可在容器组件中配置alwaysScrollableVertical属性值为true来设置支持上下滚动，支持下拉刷新操作。  
用法：

<list class="scroll-v list" enableBackToTop="true" scroll-y alwaysScrollableVertical="true">
      <refresh class="refresh" @refresh="onrefresh()" @pullingdown="onpullingdown">
        //refresh content
      </refresh>
      <cell v-for="(newsitem,index) in list" :key="newsitem.id">
        //cell content
      </cell>
    </list>

注意：

*  Android平台不存在此问题

## 7. 备注 ##

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dvbmd4aWZhY2FpX2JlbGlldmU_size_16_color_FFFFFF_t_70_pic_center][]  
![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dvbmd4aWZhY2FpX2JlbGlldmU_size_16_color_FFFFFF_t_70_pic_center 1][]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dvbmd4aWZhY2FpX2JlbGlldmU_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/aec1b477278049e78e20a8119d2a8633.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2dvbmd4aWZhY2FpX2JlbGlldmU_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221123/4222fdbabfdc48a28014cd529fef0226.png