uni-app 学习笔记

html标签和uni-app内置组件的映射表：

• div 改成 view
• span、font 改成 text
• a 改成 navigator
• img 改成 image
• input 仅仅是输入框。 原html规范中input不仅是输入框，还有radio、checkbox、时间、日期、文件选择功能。在uni-app和小程序规范中，input仅仅是输入框。其他功能uni-app有单独的组件或API：radio组件、checkbox组件、时间选择、日期选择、图片选择、视频选择、多媒体文件选择(含图片视频)、通用文件选择。
• form、button、label、textarea、canvas、video 这些还在。
• select 改成 picker
• iframe 改成 web-view
• ul、li没有了，都用view替代。做列表一般使用uList组件
• audio 不再推荐使用，改成api方式，背景音频api文档
  其实老的HTML标签也可以在uni-app里使用，uni-app编译器会在编译时把老标签转为新标签，比如把div编译成view。但不推荐这种用法，调试H5端时容易混乱。

除了改动外，新增了一批手机端常用的新组件

• scroll-view 可区域滚动视图容器
• swiper 可滑动区域视图容器
• icon 图标
• rich-text 富文本（不可执行js，但可渲染各种文字格式和图片）
• progress 进度条
• slider 滑块指示器
• switch 开关选择器
• camera 相机
• live-player 直播
• map 地图

• cover-view 可覆盖原生组件的视图容器 

  cover-view需要多强调几句，uni-app的非h5端的video、map、canvas、textarea是原生组件，层级高于其他组件。如需覆盖原生组件，则需要使用cover-view组件。详见层级介绍

除了内置组件，还有很多开源的扩展组件，把常用操作都进行封装，DCloud建立了插件市场收录这些扩展组件，详见插件市场

uni-app 中原生组件清单如下：

• map
• video
• camera（仅微信小程序、百度小程序支持）
• canvas（仅在微信小程序、百度小程序表现为原生组件）
• input（仅在微信小程序、支付宝小程序、字节跳动小程序、QQ小程序中且input置焦时表现为原生组件，其中支付宝小程序的input仅为text且置焦时才表现为原生组件）
• textarea（仅在微信小程序、百度小程序、字节跳动小程序表现为原生组件）
• live-player（仅微信小程序、百度小程序支持，App端直接使用video组件可同时实现拉流）
• live-pusher（仅微信小程序、百度小程序、app-nvue支持，app-vue使用plus.video.LivePusher可实现推流）
• cover-view
• cover-image
• ad (仅app、微信小程序、百度小程序、字节跳动小程序、QQ小程序支持

js api的变化

因为uni-app的api是参考小程序的，所以和浏览器的js api有很多不同，如

1. alert,confirm 改成 uni.showmodel
2. ajax 改成 uni.request
3. cookie、session 没有了，local.storage 改成 uni.storage

css的变化

标准的css基本都是支持的。

选择器有2个变化：*选择器不支持；元素选择器里没有body，改为了page。

单位方面

px无法动态适应不同宽度的屏幕，rem无法用于nvue/weex。如果想使用根据屏幕宽度自适应的单位，推荐使用rpx，全端支持。 

uni-app推荐使用flex布局

uni-app的vue文件里支持所有web排版方式，不管是流式还是flex。但nvue里，只支持flex，因为它在app端是使用原生排版引擎渲染的

文件大小

注意css里背景图和字体文件，尽量不要大于40k，因为会影响性能。在小程序端，如果要大于40k，需放到服务器侧远程引用或base64后引入，不能放到本地作为独立文件引用。

文件目录

• 编译到任意平台时，static 目录下的文件均会被打包进去，非 static 目录下的文件（vue、js、css 等）被引用到才会被包含进去。
• static 目录下的 js 文件不会被编译，如果里面有 es6 的代码，不经过转换直接运行，在手机设备上会报错。
• css、less/scss 等资源同样不要放在 static 目录下，建议这些公用的资源放在 common 目录下。
• HbuilderX 1.9.0+ 支持在根目录创建 ext.json sitemap.json 文件。
• @开头的绝对路径以及相对路径会经过base64转换规则校验
• 引入的静态资源在非h5平台，均不转为base64。
• H5平台，小于4kb的资源会被转换成base64，其余不转。
• 自HBuilderX 2.6.6-alpha起template内支持@开头路径引入静态资源，旧版本不支持此方式
• App平台自HBuilderX 2.6.9-alpha起template节点中引用静态资源文件时（如：图片），调整查找策略为【基于当前文件的路径搜索】，与其他平台保持一致
• 支付宝小程序组件内 image 标签不可使用相对路径

js文件引入

• js文件不支持使用/开头的方式引入

// 绝对路径，@指向项目根目录，在cli项目中@指向src目录
import add from '@/common/add.js'
// 相对路径
import add from '../../common/add.js'

css文件引入

/* 绝对路径 */
background-image: url(/static/logo.png);
background-image: url(@/static/logo.png);
/* 相对路径 */
background-image: url(../../static/logo.png);

字体图标

• 支持 base64 格式字体图标。
• 支持网络路径字体图标。
• 小程序不支持在css中使用本地文件，包括本地的背景图和字体文件。需以base64方式方可使用。App端在v3模式以前，也有相同限制。v3编译模式起支持直接使用本地背景图和字体。
• 网络路径必须加协议头 https。
• 从 http://www.iconfont.cn 上拷贝的代码，默认是没加协议头的。
• 从 http://www.iconfont.cn 上下载的字体文件，都是同名字体（字体名都叫iconfont，安装字体文件时可以看到），在nvue内使用时需要注意，此字体名重复可能会显示不正常，可以使用工具修改。
• 使用本地路径图标字体需注意：
  1. 为方便开发者，在字体文件小于 40kb 时，uni-app 会自动将其转化为 base64 格式；
  2. 字体文件大于等于 40kb，仍转换为 base64 方式使用的话可能有性能问题，如开发者必须使用，则需自己将其转换为 base64 格式使用，或将其挪到服务器上，从网络地址引用；
  3. 字体文件的引用路径推荐使用以 ~@ 开头的绝对路径。
• @开头的绝对路径以及相对路径会经过base64转换规则校验
• 不支持本地图片的平台，小于40kb，一定会转base64。（共四个平台mp-weixin, mp-qq, mp-toutiao, app v2）
• h5平台，小于4kb会转base64，超出4kb时不转。
• 其余平台不会转base64

 @font-face {
     font-family: test1-icon;
     src: url('~@/static/iconfont.ttf');
 }

nvue中不可直接使用css的方式引入字体文件，需要使用以下方式在js内引入。nvue内不支持本地路径引入字体，请使用网络链接或者base64形式。src字段的url的括号内一定要使用单引号。

var domModule = weex.requireModule('dom');
domModule.addRule('fontFace', {
  'fontFamily': "fontFamilyName",
  'src': "url('https://...')"
})

<template>
    <view>
        <view>
            <text class="test">&#xe600;</text>
            <text class="test">&#xe687;</text>
            <text class="test">&#xe60b;</text>
        </view>
    </view>
</template>
<style>
    @font-face {
        font-family: 'iconfont';
        src: url('https://at.alicdn.com/t/font_865816_17gjspmmrkti.ttf') format('truetype');
    }
    .test {
        font-family: iconfont;
        margin-left: 20rpx;
    }
</style>

应用生命周期

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

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

注意

• 应用生命周期仅可在App.vue中监听，在其它页面监听无效。

页面生命周期

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

onInit
onLoad
onShow
onReady
onHide
onUnload
onResize
onPageScroll
onBackPress
onPullDownRefresh
onReachBottom
onTabItemTap
onShareAppMessage
onShareTimeline
onAddToFavorites
onNavigationBarBottonTap
onNavigationBarSearchInputChanged
onNavigationBarSearchInputConfirmed
onNavigationBarSearchInputClicked

 

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

onInit使用注意

• 仅百度小程序基础库 3.260 以上支持 onInit 生命周期
• 其他版本或平台可以同时使用 onLoad 生命周期进行兼容，注意避免重复执行相同逻辑
• 不依赖页面传参的逻辑可以直接使用 created 生命周期替代

onReachBottom使用注意 可在pages.json里定义具体页面底部的触发距离onReachBottomDistance，比如设为50，那么滚动页面到距离底部50px时，就会触发onReachBottom事件。

onPageScroll （监听滚动、滚动监听、滚动事件）参数说明：

属性	类型	说明
scrollTop	Number	页面在垂直方向已滚动的距离（单位px）

注意

• onPageScroll里不要写交互复杂的js，比如频繁修改页面。因为这个生命周期是在渲染层触发的，在非h5端，js是在逻辑层执行的，两层之间通信是有损耗的。如果在滚动过程中，频发触发两层之间的数据交换，可能会造成卡顿。
• 如果想实现滚动时标题栏透明渐变，在App和H5下，可在pages.json中配置titleNView下的type为transparent，参考。
• 如果需要滚动吸顶固定某些元素，推荐使用css的粘性布局，参考插件市场。插件市场也有其他js实现的吸顶插件，但性能不佳，需要时可自行搜索。
• 在App、微信小程序、H5中，也可以使用wxs监听滚动，参考；在app-nvue中，可以使用bindingx监听滚动，参考。
• onBackPress上不可使用async，会导致无法阻止默认返回

onPageScroll : function(e) { //nvue暂不支持滚动监听，可用bindingx代替
    console.log("滚动距离为：" + e.scrollTop);
},

onTabItemTap 返回的json对象说明：

属性	类型	说明
index	String	被点击tabItem的序号，从0开始
pagePath	String	被点击tabItem的页面路径
text	String	被点击tabItem的按钮文字

注意

• onTabItemTap常用于点击当前tabitem，滚动或刷新当前页面。如果是点击不同的tabitem，一定会触发页面切换。
• 如果想在App端实现点击某个tabitem不跳转页面，不能使用onTabItemTap，可以使用plus.nativeObj.view放一个区块盖住原先的tabitem，并拦截点击事件。
• 支付宝小程序平台onTabItemTap表现为点击非当前tabitem后触发，因此不能用于实现点击返回顶部这种操作

onTabItemTap : function(e) {
    console.log(e);
    // e的返回格式为json对象： {"index":0,"text":"首页","pagePath":"pages/index/index"}
},

onNavigationBarButtonTap 参数说明：

属性	类型	说明
index	Number	原生标题栏按钮数组的下标

onNavigationBarButtonTap : function (e) {
    console.log(e);
    // e的返回格式为json对象：{"text":"测试","index":0}
}

onBackPress 回调参数对象说明：

属性	类型	说明
from	String	触发返回行为的来源：'backbutton'——左上角导航栏按钮及安卓返回键；'navigateBack'——uni.navigateBack() 方法。支付宝小程序端不支持返回此字段

export default {
    data() {
        return {};
    },
    onBackPress(options) {
        console.log('from:' + options.from)
    }
}

注意

• nvue 页面weex编译模式支持的生命周期同weex，具体参考：weex生命周期介绍。
• 支付宝小程序真机可以监听到非navigateBack引发的返回事件（使用小程序开发工具时不会触发onBackPress），不可以阻止默认返回行为

组件生命周期

uni-app 组件支持的生命周期，与vue标准组件的生命周期相同。这里没有页面级的onLoad等生命周期：

函数名	说明	平台差异说明	最低版本
beforeCreate	在实例初始化之后被调用。详见
created	在实例创建完成后被立即调用。详见
beforeMount	在挂载开始之前被调用。详见
mounted	挂载到实例上去之后调用。详见 注意：此处并不能确定子组件被全部挂载，如果需要子组件完全挂载之后在执行操作可以使用$nextTickVue官方文档
beforeUpdate	数据更新时调用，发生在虚拟 DOM 打补丁之前。详见	仅H5平台支持
updated	由于数据更改导致的虚拟 DOM 重新渲染和打补丁，在这之后会调用该钩子。详见	仅H5平台支持
beforeDestroy	实例销毁之前调用。在这一步，实例仍然完全可用。详见
destroyed	Vue 实例销毁后调用。调用后，Vue 实例指示的所有东西都会解绑定，所有的事件监听器会被移除，所有的子实例也会被销毁。详见

路由

uni-app页面路由为框架统一管理，开发者需要在pages.json里配置每个路由页面的路径及页面样式。类似小程序在app.json中配置页面路由一样。所以 uni-app 的路由用法与 Vue Router 不同

uni-app 有两种页面路由跳转方式：使用navigator组件跳转、调用API跳转。

navigator

页面跳转。

该组件类似HTML中的<a>组件，但只能跳转本地页面。目标页面必须在pages.json中注册。

url
open-type:navigate、redirect、switchTab、reLaunch、navigateBack、exit
delta
animation-type
animation-duration
hover-class
hover-stop-propagation
hover-start-time
hover-stay-time
target
 

属性说明

属性名	类型	默认值	说明	平台差异说明
url	String		应用内的跳转链接，值为相对路径或绝对路径，如："../first/first"，"/pages/first/first"，注意不能加 .vue 后缀
open-type	String	navigate	跳转方式
delta	Number		当 open-type 为 'navigateBack' 时有效，表示回退的层数
animation-type	String	pop-in/out	当 open-type 为 navigate、navigateBack 时有效，窗口的显示/关闭动画效果，详见：窗口动画	App
animation-duration	Number	300	当 open-type 为 navigate、navigateBack 时有效，窗口显示/关闭动画的持续时间。	App
hover-class	String	navigator-hover	指定点击时的样式类，当hover-class="none"时，没有点击态效果
hover-stop-propagation	Boolean	false	指定是否阻止本节点的祖先节点出现点击态	微信小程序
hover-start-time	Number	50	按住后多久出现点击态，单位毫秒
hover-stay-time	Number	600	手指松开后点击态保留时间，单位毫秒
target	String	self	在哪个小程序目标上发生跳转，默认当前小程序，值域self/miniProgram	微信2.0.7+、百度2.5.2+、QQ

open-type 有效值

值	说明	平台差异说明
navigate	对应 uni.navigateTo 的功能
redirect	对应 uni.redirectTo 的功能
switchTab	对应 uni.switchTab 的功能
reLaunch	对应 uni.reLaunch 的功能	字节跳动小程序不支持
navigateBack	对应 uni.navigateBack 的功能
exit	退出小程序，target="miniProgram"时生效	微信2.1.0+、百度2.5.2+、QQ1.4.7+

注意

• 跳转tabbar页面，必须设置open-type="switchTab"
• navigator-hover 默认为 {background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}, <navigator> 的子节点背景色应为透明色。
• app-nvue 平台只有纯nvue项目（render为native）才支持 <navigator>。非render为native的情况下，nvue暂不支持navigator组件，请使用API跳转。
• app下退出应用，Android平台可以使用plus.runtime.quit。iOS没有退出应用的概念。
• 如果想实现web外链跳转，可参考uLink组件

示例 查看示例

<template>
    <view>
        <view class="page-body">
            <view class="btn-area">
                <navigator url="navigate/navigate?title=navigate" hover-class="navigator-hover">
                    <button type="default">跳转到新页面</button>
                </navigator>
                <navigator url="redirect/redirect?title=redirect" open-type="redirect" hover-class="other-navigator-hover">
                    <button type="default">在当前页打开</button>
                </navigator>
                <navigator url="/pages/tabBar/extUI/extUI" open-type="switchTab" hover-class="other-navigator-hover">
                    <button type="default">跳转tab页面</button>
                </navigator>
            </view>
        </view>
    </view>
</template>

// navigate.vue页面接受参数
export default {
    onLoad: function (option) { //option为object类型，会序列化上个页面传递的参数
        console.log(option.id); //打印出上个页面传递的参数。
        console.log(option.name); //打印出上个页面传递的参数。
    }
}

url有长度限制，太长的字符串会传递失败，可使用窗体通信、全局变量，或encodeURIComponent等多种方式解决，如下为encodeURIComponent示例。

<navigator :url="'/pages/navigate/navigate?item='+ encodeURIComponent(JSON.stringify(item))"></navigator>

// navigate.vue页面接受参数
onLoad: function (option) {
    const item = JSON.parse(decodeURIComponent(option.item));
}

 

 

页面栈

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

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