uni-app
App端内置 weex 渲染引擎,提供了原生渲染能力。
uni-app
里根据编译配置不同,可以使用 weex
的组件,也可以使用小程序组件(即uni-app组件)。编写页面时页面后缀名为 .nvue
(native vue的缩写)
nvue
相当于给 weex 补充了大量 uni-app 的组件和api,以及丰富的 Plus API、Native.js、原生插件。
以往的 weex ,有个很大的问题是它只是一个高性能的渲染器,没有足够的API能力,使得开发时非常依赖原生工程师协作,开发者本来想节约成本,结果需要前端、iOS、Android 3拨人开发,适得其反。而 nvue 解决了这个大问题,让前端工程师可以直接开发完整 App,并提供原生插件的市场交易和云打包。这些组合方案,开发者切实的提高效率、降低成本。
如果你已经是 weex 的开发者,具有 weex 的填坑能力,那么 nvue 是你的更优选择,能切实提升你的开发效率,降低成本。
如果你不开发App,那么你不太需要nvue。
如果你是web前端,不熟悉 weex,那么建议你仍然以使用 vue 为主,在App端某些 vue 表现不佳的场景下使用 nvue 作为强化补充:
- 左右拖动的长列表。在webview里,通过swiper+scroll-view实现左右拖动的长列表,前端模拟下拉刷新,这套方案的性能不好。此时推荐使用nvue,比如新建uni-app项目时的新闻示例模板,就是首页采用了nvue
- 如需要将软键盘右下角按钮文字改为“发送”,则需要使用nvue
- 前端控件无法覆盖原生控件的问题。在nvue下,都是原生控件,覆盖map、video等不需要cover-view(如需要发布到小程序,仍然推荐写cover-view)
- 同样因为层级问题得到解决,nvue可以实现video内嵌到swiper中,以实现抖音式视频滑动切换,例子见插件市场;nvue的视频全屏后,仍然可以通过cover-view实现内容覆盖,比如增加文字标题、分享按钮。
- nvue下有live-pusher组件,和小程序对齐。而vue页面下使用直播,需在条件编译里单独调用plus.video的API。
- App端nvue文件的map和小程序拉齐度更高。vue里的map则与plus.map功能一致,和小程序的地图略有差异。
- App端实现粘性布局,比如滚动吸顶,则nvue才能保证高性能,例子见插件市场
此外,App端,vue页面上也可以覆盖subnvue(一种非全屏的nvue页面覆盖在webview上),以解决App上的原生控件层级问题。详见
uni-app在App端,支持vue页面和nvue页面混搭、互相跳转。也支持纯nvue项目。
在manifest.json源码视图的"app-plus"
下配置"renderer":"native"
,即代表App端启用纯原生渲染模式。此时pages.json注册的vue页面将被忽略,vue组件中的代码也需覆盖nvue规范,并会被原生渲染。
启动纯原生渲染,可以减少App端的包体积、加快App启动速度。因为webview渲染模式的相关模块将被移除。
如果不指定该值,默认是不启动纯原生渲染的。
// manifest.json
{
// ...
/* App平台特有配置 */
"app-plus": {
"renderer": "native", //App端纯原生渲染模式
}
}
uni-app 深度改进了 weex,提供了2种编译模式,一种是常规的 weex 组件模式,即编写<div>
。另一种是 uni-app 组件模式,即编写<view>
。后者更提供了编译为小程序和H5的能力,实现了全端输出。
也可以理解为uni-app做了一个原生渲染的小程序引擎。
weex编译模式 | uni-app编译模式 | |
---|---|---|
平台 | 仅App | 所有端,包含小程序和H5 |
组件 | weex组件如div |
uni-app组件如view |
生命周期 | 只支持weex生命周期 | 支持所有uni-app生命周期 |
JS API | weex API、uni API、Plus API | weex API、uni API、Plus API |
单位 | 750px是屏幕宽度,wx是固定像素单位 | 750rpx是屏幕宽度,px是固定像素单位 |
全局样式 | 手动引入 | app.vue的样式即为全局样式 |
页面滚动 | 必须给页面套或组件 | 默认支持页面滚动 |
在 manifest.json 中修改2种编译模式,manifest.json
-> app-plus
-> nvueCompiler
切换编译模式。
nvueCompiler
有两个值:
- weex
- uni-app
// manifest.json
{
// ...
/* App平台特有配置 */
"app-plus": {
"nvueCompiler":"uni-app" //是否启用 uni-app 模式
}
}
- 如果没有在manifest里明确配置,默认是weex模式。这是为了向下兼容。
在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文件才会编译。
nvue
页面结构同 vue
, 由 template、style、script 构成。
- template: 模板写法、数据绑定同
vue
。组件支持2种模式,1、weex
组件,同weex写法,参考:weex 内置组件;2、uni-app
组件,同uni-app写法。部分组件还未在nvue下实现,具体见:nvue中还未支持的uni-app组件 - style:由于采用原生渲染,并非所有浏览器的 css 均支持,布局模型只支持 flex 布局,虽然不会造成某些界面布局无法实现,但写法要注意。详见:weex 样式
- script:写法同
vue
,并支持3种API:- weex API :使用前需先引入对应模块,参考:weex 模块引入
- uni API:nvue可以使用大部分 uni API,个别API不支持,不支持列表请参照:nvue 里还未支持的 uni-app API
- plus API:在自定义组件编译模式下,nvue里可直接使用plus API
weex组件代码示例(uni-app组件代码和普通uni-app的vue源码相同)
<template>
<div class="example">
<div class="item" @click="changeNum"><text class="text">点击文字,改变数字大小: {{num}}</text></div>
<div class="item" @click="showModal('native')"><text class="text">使用 weex 的 API 弹出模态框</text></div>
<div class="item" @click="showModal('uni')"><text class="text">使用 uni-app 的 API 弹出模态框</text></div>
<div class="item" @click="showModal('plus')"><text class="text">使用 plus 的 API 弹出模态框</text></div>
</div>
</template>
<script>
export default {
data() {return {num: 1}},
created() {console.log('页面created')},
methods: {
changeNum() { this.num += 1; },
showModal(type) {
if (type === 'uni') {
uni.showModal({content: '使用 uni-app 的 API 弹出模态框'});
}
else if (type === 'plus') {
plus.nativeUI.alert('使用 uni-app 的 API 弹出模态框');
} else {
var modal = weex.requireModule('modal')
modal.alert({message: '使用 weex 的 API 弹出模态框'});
}
}
}
}
</script>
<style>
.example {flex-direction: column;}
.text {line-height: 80px;font-size: 32px;color: #333;}
.item {height: 80px;width: 690px;margin: 30px;background-color: #f8f8f8;border-width: 1px;border-color: #eee;border-radius: 10px;align-items: center;}
</style>
HBuilderX内置了更好用的weex/uni-app调试工具,包括审查界面元素、看log、debug打断点,详见
nvue
的 uni-app 编译模式的生命周期同普通vue页面,参考。而 weex 编译模式,生命周期函数同weex,具体如下:
Vue 生命周期钩子 | 说明 |
---|---|
beforeCreate | 在实例初始化之后,数据观测 (data observer) 和 event/watcher 事件配置之前被调用 |
created | 在实例创建完成后被立即调用 |
beforeMount | 在挂载开始之前被调用 |
mounted | el 被新创建的 vm.$el 替换时调用 |
beforeUpdate | 数据更新时调用 |
updated | 页面元素更新后调用 |
beforeDestroy | 实例销毁之前调用 |
destroyed | 实例销毁后调用 |
errorCaptured | 当捕获一个来自子孙组件的错误时被调用 |
注意: weex 编译模式不支持 onNavigationBarButtonTap 生命周期函数的写法。在 nvue
中监听原生标题栏按钮点击事件,详见:uni.onNavigationBarButtonTap。
nvue 的页面跳转,与 weex 不同,仍然遵循 uni-app 的路由模型。vue 页面和 nvue 页面之间不管怎么跳转,都遵循这个模型。包括 nvue 页面跳向 nvue 页面。
每个页面都需要在 pages.json 中注册,调用 uni-app
的 路由 API 进行跳转。
在 uni-app 中,nvue 和 vue 页面可以混搭使用。
步骤:
- 在
nvue
使用uni.postMessage(data)
发送数据通讯,data
为JSON
格式(键值对的值仅支持String)。 - 在
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
里使用plus.webview.postMessageToUniNView(data,nvueId)
发送消息,data
为JSON
格式(键值对的值仅支持String),nvueId
为nvue
所在 webview 的 id,webview的 id 获取方式参考:$getAppWebview()。 - 在
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 页面之间还可以共享变量和存储。 uni-app提供的共享变量和数据的方案如下:
1. vuex:
自HBuilderX 2.2.5-alpha
起,nvue支持vuex
注意:
- 不支持直接引入
store
使用,可以使用mapState
、mapGetters
、mapMutations
等辅助方法或者使用this.$store
- 暂时只支持
uni-app
编译模式,不支持weex
编译模式 renderer:native
时也可以使用vuex
2. uni.storage:
vue和nvue页面可以使用相同的uni.storage
存储。这个存储是持久化的。
比如登陆状态可以保存在这里。
3. globalData:
小程序有globalData机制,这套机制在uni-app里也可以使用,全端通用。
在App.vue
文件里定义globalData,如下:
<script>
export default {
globalData: {
text: 'text'
},
onLaunch: function() {
console.log('App Launch')
},
onShow: function() {
console.log('App Show')
},
onHide: function() {
console.log('App Hide')
}
}
</script>
js中操作globalData的方式如下:
getApp().globalData.text = 'test'
如果需要把globalData的数据绑定到页面上,可在页面的onShow声明周期里进行变量重赋值。HBuilderX 2.0.3起,nvue页面在uni-app
编译模式下,也支持onShow。
weex编译模式不支持onShow,但熟悉5+的话,可利用监听webview的addEventListener show事件实现onShow效果。
nvue
的 weex 编译模式中,可以使用weex的第三方库,这里以 Weex Ui 为例,介绍如何使用。
1.初始化工程
npm init -y
2.安装依赖 (暂时只支持名称里包含weex的库)
npm i weex-ui -S
3.在nvue里面使用
<template>
<div>
<wxc-cell label="标题" title="Weex Ui" :has-arrow="true" @wxcCellClicked="wxcCellClicked" :has-margin="true"></wxc-cell>
</div>
</template>
<script>
import { WxcCell } from 'weex-ui';
export default {
components: { WxcCell },
methods: {
wxcCellClicked (e) {
console.log(e)
}
}
};
</script>
Tis:
- 插件市场有一个集成好 weex ui 的示例,可以直接查看https://ext.dcloud.net.cn/plugin?id=442
uni-app
内置了 BindingX,可在 nvue
中使用 BindingX 完成复杂的动画效果。
- 使用方式可参考 BindingX 快速开始,demo示例可参考 BindingX 示例 里
vue
的相关示例,将实验田里的vue
代码拷贝到nvue
文件里即可。 - 若引入 weex-bindingx 时发现不生效,检查项目路径,路径不能含有中文。
- 使用npm时如果命令行报错,需要注意看命令行的提示
代码示例
<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>
import Binding from 'weex-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);
Binding.bind({
eventType: 'timing',
exitExpression: {
origin: 't>800'
},
props: [{
element: main_image,
property: 'transform.rotateZ',
expression: {
origin: 'easeOutQuint(t,45,0-45,800)'
}
},{
element: main_btn,
property: 'background-color',
expression: {
origin: "evaluateColor('#607D8B','#ff0000',min(t,800)/800)"
}
}]
});
Binding.bind({
eventType: 'timing',
exitExpression: {
origin: 't>800'
},
props: [{
element: b1,
property: 'transform.translateY',
expression: {
origin: "easeOutQuint(t,-150,150,800)"
}
},{
element: b2,
property: 'transform.translateY',
expression: {
origin: "t<=100?0:easeOutQuint(t-100,-300,300,700)"
}
},{
element: b3,
property: 'transform.translateY',
expression: {
origin: "t<=200?0:easeOutQuint(t-200,-450,450,600)"
}
}]
})
},
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);
Binding.bind({
eventType: 'timing',
exitExpression: {
origin: 't>100'
},
props: [{
element: main_image,
property: 'transform.rotateZ',
expression: {
origin: 'linear(t,0,45,100)'
}
},{
element: main_btn,
property: 'background-color',
expression: {
origin: "evaluateColor('#ff0000','#607D8B',min(t,100)/100)"
}
}]
});
Binding.bind({
eventType: 'timing',
exitExpression: {
origin: 't>800'
},
props: [{
element: b1,
property: 'transform.translateY',
expression: {
origin: "easeOutBounce(t,0,0-150,800)"
}
}, {
element: b2,
property: 'transform.translateY',
expression: {
origin: "t<=100?0:easeOutBounce(t-100,0,0-300,700)"
}
}, {
element: b3,
property: 'transform.translateY',
expression: {
origin: "t<=200?0:easeOutBounce(t-200,0,0-450,600)"
}
}]
})
},
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>
- 自定义组件编译模式,HBuilderX 1.9.8起,nvue页面可直接使用plus的API,并且同样不需要等待plus ready。
- 非自定义组件编译模式,nvue无法直接调用 HTML5Plus 相关的 API,可以通过与vue通讯的方式,在 vue 页面调用 HTML5Plus 的API,传值给nvue页面,以达到类似的结果。
以下为非自定义组件模式下,通过页面通讯在nvue页面获得设备uuid的示例(推荐老项目尽快升级为自定义组件,享受更高的性能和功能):
nvue 页面
<template>
<div @click="test">
<text>点击页面得到设备的uuid为:{{uuid}}</text>
</div>
</template>
<script>
const globalEvent = weex.requireModule('globalEvent');
export default {
data() {
return {
uuid: null
}
},
created() {
globalEvent.addEventListener("plusMessage", e => {
console.log(e.data);
if (e.data.detail) {
this.uuid = e.data.detail
}
});
},
methods: {
test(e) {
uni.postMessage({module:"device",api:"uuid"});
}
}
}
</script>
App.vue
<script>
export default {
onUniNViewMessage: function(e) {
console.log("App.vue收到数据:" + JSON.stringify(e.data));
console.log("uuid:" + plus[e.data.module][e.data.api])
var pages = getCurrentPages();
var page = pages[pages.length - 1];
var currentWebview = page.$getAppWebview();
plus.webview.postMessageToUniNView({
detail: plus[e.data.module][e.data.api]
}, currentWebview.id);
}
}
</script>
nvue
支持大部分 uni-app API ,下面只列举目前还不支持的 API 。
动画
API | 说明 |
---|---|
uni.createAnimation() | 创建一个动画实例 |
滚动
API | 说明 |
---|---|
uni.pageScrollTo() | 将页面滚动到目标位置 |
绘画
canvas API使用,详见canvas文档。
节点信息
API | 说明 |
---|---|
uni.createSelectorQuery() | 返回一个 SelectorQuery 对象实例 |
节点布局交互
API | 说明 |
---|---|
uni.createIntersectionObserver() | 创建并返回一个 IntersectionObserver 对象实例 |
为了解决nvue的weex编译模式不支持uni-app生命周期的问题,在nvue
里新增了几个特殊的 API。如果是uni-app编译模式,无需使用这些API:
监听原生标题栏按钮点击事件。
CALLBACK 参数说明:
属性 | 类型 | 说明 |
---|---|---|
index | Number | 原生标题栏按钮数组的下标 |
代码示例
export default {
created() {
uni.onNavigationBarButtonTap((e) => {
console.log("监听到原生标题栏按钮点击事件");
console.log(e);
})
}
}
监听原生标题栏搜索输入框输入内容变化事件。
CALLBACK 参数说明:
属性 | 类型 | 说明 |
---|---|---|
text | String | 搜索输入框输入内容 |
代码示例
export default {
created() {
uni.onNavigationBarSearchInputChanged((e) => {
console.log("输入内容:"+ e.text);
})
}
}
监听原生标题栏搜索输入框搜索事件,用户点击软键盘上的“搜索”按钮时触发。
代码示例
export default {
created() {
uni.onNavigationBarSearchInputConfirmed(() => {
console.log("用户点击软键盘搜索");
})
}
}
监听原生标题栏搜索输入框点击事件。
代码示例
export default {
created() {
uni.onNavigationBarSearchInputClicked(() => {
console.log("点击输入框");
})
}
}
基于原生引擎的渲染,虽然还是前端技术栈,但和web开发肯定是有区别的。
比如没有dom、window等对象,比如只支持flex布局,好在uni-app
一直以来也是推动开发者不使用dom,默认使用flex布局。所以适应起来要好一些。
但仍然还有一些区别需要注意:
- nvue 页面只能使用 flex 布局,不支持其他布局方式。
- weex 下,页面内容高过屏幕高度并不会自动滚动,它没有页面滚动的概念,只有区域滚动,要滚得内容需要套在组件下。在 nvue 编译为 uni-app模式时,纠正了这个问题,页面内容过高会自动滚动。
- weex 下,px是与屏幕宽度相关的动态单位,750px代表成屏幕宽度100%,它的静态单位是wx。在 nvue 编译为 uni-app模式时,纠正了这个问题,rpx是与屏幕宽度相关的动态单位,px是静态单位。
- 页面开发前,首先想清楚这个页面的纵向内容有什么,哪些是要滚动的,然后每个纵向内容的横轴排布有什么,按 flex 布局设计好界面。
- 文字内容,必须、只能在组件下。不能在、的text区域里直接写文字。
- 支持的css有限,不过并不影响布局出你需要的界面,flex还是非常强大的。详见
- class 进行绑定时只支持数组语法。
- weex的css单位支持如下:
- px:以750宽的屏幕为基准动态计算的长度单位,与vue页面中的rpx理念相同。(一定要注意nvue里的px,和vue里的px逻辑不一样)
- wx:与设备屏幕宽度无关的长度单位,与vue页面中的px理念相同
- uni-app编译模式下单位和普通vue相同,rpx是以750宽屏幕为基准的动态单位。px则是固定像素单位。详见
- 现阶段 nvue 的定位是 vue 的补充。在 App 平台实现一些 vue 上无法实现或性能有问题的场景。
- nvue 的各组件在安卓端默认是透明的,如果不设置background-color,可能会导致出现重影的问题。
- 在 App.vue 中定义的全局js变量不会在 nvue 页面生效。globalData是生效的。
- nvue 切换横竖屏时可能导致样式出现问题,建议有 nvue 的页面锁定手机方向。
- 不能在 style 中引入字体文件,nvue 中字体图标的使用参考:weex 加载自定义字体。如果是本地字体,可以用plus.io的API转换路径。
- 目前不支持在 nvue 页面使用 typescript/ts。
- nvue 页面
titleNview
设为false
时,想要模拟状态栏,可以参考:https://ask.dcloud.net.cn/article/35111。