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 支持如下应用生命周期函数：

注意

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

页面生命周期

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

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

onInit使用注意

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

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

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

注意

• 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对象说明：

注意

• 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 参数说明：

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

onBackPress 回调参数对象说明：

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

注意

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

组件生命周期

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

路由

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
 

属性说明

open-type 有效值

注意

• 跳转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)); }

页面栈

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