uni-app的基本使用

uni-app介绍

uni-app是一个使用Vue.js开发所有前端应用的框架，开发者编写一套代码。可发布到iOS、Android、H5、以及各种小程序（微信/支付宝/百度/头条/QQ/钉钉）等多个平台。

即使不跨端。uni-app同时也是更好的小程序开发框架。

为什么要去学习uni-app?
相对开发者来说，减少了学习成本，因为只学会uni-app之后，即可开发出iOS、Android、H5、以及各种小程序的应用，不需要再去学习开发其他应用的框架。相对公司而言，也大大减少了开发成本。

环境搭建

安装编辑器hbuilderX 下载地址
HBuilderX是通用的前端开发工具，但为uni-app做了特别强化。
下载APP开发版，可开箱即用
安装微信开发者工具 下载地址 根据电脑配置下载

利用HbuilderX初始化项目

点击HbuilderX菜单栏 ：文件>新建>项目
选择uni-app，填些项目名称，项目创建的目录

介绍项目目录和文件作用

• pages.json 文件用来对 uni-app 进行全局配置，决定页面文件的路径，窗口样式，原生的导航栏，底部的原生 tabbar 等
• manifest.json 文件是应用的配置文件，用于指定应用的名称，图标，权限等
• App.vue 是我们的根组件，所有页面都是在App.vue 下切换的，是页面入口文件，可以调用应用的生命周期函数
• main.js 是我们项目的入口文件，主要作用是初始化 vue 实例并使用需要的插件
• uni.scss 文件的用途是为了方便整体控制应用的风格，比如按钮的颜色，边框风格，该文件里预置了一批 scss 变量预置
• unpackage 就是打包目录，在这里有各个平台的打包文件
• pages 所有页面存放目录
• static 静态资源目录，例如图片，字体文件
• compontents 组件存放目录

为了实现多端兼容，综合考虑编译速度、运行性能等因素，uni-app 约定了如下开发规范：

• 页面文件遵循 Vue 单文件组件 (SFC) 规范
• 组件标签靠近小程序规范，详见uni-app 组件规范
• 接口能力（JS API）靠近微信小程序规范，但需将前缀 wx 替换为 uni，详见uni-app接口规范
• 数据绑定及事件处理同 Vue.js 规范，同时补充了App及页面的生命周期
• 为兼容多端运行，建议使用flex布局进行开发

全局配置和页面配置

通过globalStyle进行全局配置

用于设置应用的状态栏、导航条、标题、窗口背景色等。详细文档

通过pages来配置页面

官网pages链接

pages数组数组中第一项表示应用启动页

"pages": [ 、
		{
			"path":"pages/message/message" //启动页
		},
		{
			"path": "pages/index/index",
			"style": {
				"navigationBarTitleText": "uni-app" //导航栏标题
			}
		}
	]

通过style修改页面的标题和导航栏背景色，并且设置h5下拉刷新的特有样式

{
	"pages": [ //pages数组中第一项表示应用启动页，参考：https://uniapp.dcloud.io/collocation/pages
		{
			"path": "pages/message/message",
			"style":{
				"navigationBarTitleText":"信息页",
				"navigationBarBackgroundColor":"#007AFF",
				"h5":{
					"pullToRefresh":{
						"color":"#7D26CD"
					}
				}
			}
		},
		{
			"path": "pages/index/index"
		}
	]

配置tabbar

如果应用是一个多 tab 应用，可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页。

Tips

• 当设置 position 为 top 时，将不会显示 icon
• tabBar 中的 list 是一个数组，只能配置最少2个、最多5个 tab，tab 按数组的顺序排序。

属性说明：

其中 list 接收一个数组，数组中的每个项都是一个对象，其属性值如下：

案例代码：

	"tabBar":{
		"color":"#a0522d",
		"selectedColor":"#B3EE3A",
		"backgroundColor":"#FFFFFF",
		"borderStyle":"white",
		"position":"bottom",
		"list":[
			{
				"text":"首页",
				"pagePath":"pages/index/index",
				"iconPath":"static/tabs/home.png",
				"selectedIconPath":"static/tabs/home-active.png"
			},
			{
				"text":"信息",
				"pagePath":"pages/message/message",
				"iconPath":"static/tabs/message.png",
				"selectedIconPath":"static/tabs/message-active.png"
			},
			{
				"text":"信息",
				"pagePath":"pages/contact/contact",
				"iconPath":"static/tabs/contact.png",
				"selectedIconPath":"static/tabs/contact-active.png"
			}
		]
	}

condition启动模式配置

启动模式配置，仅开发期间生效，用于模拟直达页面的场景，如：小程序转发后，用户点击所打开的页面。
属性说明：

属性	类型	是否必填	描述
current	Number	是	当前激活的模式，list节点的索引值
list	Array	是	启动模式列表

list说明：

属性	类型	是否必填	描述
name	String	是	启动模式名称
path	String	是	启动页面路径
query	String	否	启动参数，可在页面的 onLoad 函数里获得

案例：

"condition":{
		"current":0,
		"list":[
			{
				"name":"详情页",
				"path":"pages/detail/detail",
				"query":"id=80"
			}
		]
	}

组件的基本使用

uni-app提供了丰富的基础组件给开发者，开发者可以像搭积木一样，组合各种组件拼接成自己的应用
uni-app中的组件，就像html中的div、p、span等标签的作用一样，用于搭建页面的基础结构

text文本组件的用法

text组件的属性

属性	类型	默认值	必填	说明
selectable	boolean	false	否	文本是否可选
space	string	.	否	显示连续空格，可选参数：ensp、emsp、nbsp
decode	boolean	false	否	是否解码

space值说明

值	说明
ensp	中文字符空格一半大小
emsp	中文字符空格大小
nbsp	根据字体设置的空格大小

• text组件相当于行内标签、在同一行显示
• 除了文本节点以外的其他节点都无法长按选中

Tips

• <text> 组件内只支持嵌套 <text>，不支持其它组件或自定义组件，否则会引发在不同平台的渲染差异。
• 在app-nvue下，只有<text>才能包裹文本内容。无法在<view>组件包裹文本。
• decode 可以解析的有   < > & '    。
  各个操作系统的空格标准并不一致。
• 除了文本节点以外的其他节点都无法长按选中。
• 支持 \n 方式换行。
• 如果使用 <span> 组件编译时会被转换为 <text>。

view视图容器组件的用法

View视图容器，类似于HTML中的div

组件的属性

button按钮组件的用法

组件的属性

官网链接

属性名	类型	默认值	说明
size	String	default	按钮的大小
type	String	default	按钮的样式类型
plain	Boolean	false	按钮是否镂空，背景色透明
disabled	Boolean	false	是否按钮
loading	Boolean	false	名称是否带loading图标

• button 组件默认独占一行，设置 size 为 mini 时可以在一行显示多个

size有效值

值	说明
default	默认大小
mini	小尺寸

type有效值

值	说明
primary	微信小程序、360小程序为绿色，App、H5、百度小程序、支付宝小程序、快应用为蓝色，字节跳动小程序为红色，QQ小程序为浅蓝色。如想在多端统一颜色，请改用default，然后自行写样式
default	白色
war n	红色

image组件的使用

组件的属性

官网链接
图片

Tips

• <image> 组件默认宽度 300px、高度 225px；app-nvue平台，暂时默认为屏幕宽度
• src 仅支持相对路径、绝对路径，支持 base64 码；
• 页面结构复杂，css样式太多的情况，使用 image 可能导致样式生效较慢，出现 “闪一下” 的情况，此时设置
  image{will-change: transform} ,可优化此问题。
• 自定义组件里面使用 <image>时，若 src 使用相对路径可能出现路径查找失败的情况，故建议使用绝对路径。
• webp格式的图片在Android上是内置支持的。iOS上不同平台不一样，具体如下：app-vue下，iOS不支持；app-nvue下，iOS支持；微信小程序2.9.0起，iOS支持。
• svg 格式的图片在不同的平台支持情况不同。具体为：app-nvue 不支持 svg 格式的图片，小程序上只支持网络地址。

mode有效值：
mode 有 13 种模式，其中 4 种是缩放模式，9 种是裁剪模式。最常用的有两种是aspectFit和aspectFill。

uni-app中的样式

• rpx 即响应式px，一种根据屏幕宽度自适应的动态单位。以750宽的屏幕为基准，750rpx恰好为屏幕宽度。屏幕变宽，rpx实际显示效果会等比放大。
• 使用@import语句可以导入外联样式表，@import后跟需要导入的外联样式表的相对路径，用;表示语句结束
• 支持基本常用的选择器class、id、element等
• 在 uni-app 中不能使用 * 选择器。
• page 相当于 body 节点
• 定义在 App.vue 中的样式为全局样式，作用于每一个页面。在 pages 目录下 的 vue文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖 App.vue 中相同的选择器。
• uni-app 支持使用字体图标，使用方式与普通 web 项目相同，需要注意以下几点：
  • 字体文件小于 40kb，uni-app 会自动将其转化为 base64 格式；
  • 字体文件大于等于 40kb， 需开发者自己转换，否则使用将不生效；
  • 字体文件的引用路径推荐使用以 ~@ 开头的绝对路径。

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

• 如何使用scss或者less

uni-app中的数据绑定

在页面中需要定义数据，和我们之前的vue一模一样，直接在data中定义数据即可

export default{
		data(){
			return{
				msg:'hello'
			}
		}
	}

插值表达式的使用

• 利用插值表达式渲染基本数据

<view>{{msg}}</view>

• 在插值表达式中使用三元运算

<view>{{flag?'我是真的':'我是假的'}}</view>

• 基本运算

<view>{{1+1}}</view>

v-bind动态绑定属性

在data中定义了一张图片，我们希望把这张图片渲染到页面上

export default {
		data() {
			return {
				img: 'https://img2.baidu.com/it/u=2937803703,3095540904&fm=11&fmt=auto&gp=0.jpg'
			}
		}
	}

利用v-bind进行渲染

<image v-bind:src="img"></image>

还可以缩写成：

<image :src="img"></image>

v-for的使用

data中定以一个数组，最终将数组渲染到页面上

data(){
	return{
		arr:[
			{name:'刘能',age:29},
			{name:'赵四',age:39},
			{name:'宋小宝',age:49},
			{name:'小沈阳',age:59}
		]
	}
}

利用v-for进行循环

<view v-for="(item,i) in arr" :key="i">名字：{{item.name}}---年龄:{{item.age}}</view>

uni中的事件

事件绑定
在uni中事件绑定和vue中是一样的，通过v-on进行事件的绑定，也可以简写为@

<button type="default" @:click="tapHandle">按钮</button>

事件函数定义在methods中

methods:{
	tapHandle(){
		console.log('真的点我了')
	}
}

事件传参

• 默认如果没有传递参数，事件函数第一个形参为事件对象

//template
<button type="default" @:click="tapHandle">点我啊</button>
//script
methods:{
	tapHandle(e){
		console.log(e)
	}
}

• 如果给事件函数传递参数了，则对应的事件函数形参接收的则是传递过来的数据

//template
<button type="default" @:click="tapHandle(20)">点我啊</button>
//script
methods:{
	tapHandle(num){
		console.log(num) //20
	}
}

如果既想传递参数又想拿到事件对象，在传递参数的时候使用$event可以把事件对象传递过去

//template
<button type="default" @:click="tapHandle(20,$event)">点我啊</button>
//script
methods:{
	tapHandle(num,e){
		console.log(num,e) 
	}
}

uni的生命周期

应用的生命周期

生命周期的概念：一个对象从创建、运行、销毁的整个过程被称为生命周期。
生命周期函数：在生命周期中每个阶段会伴随着每一个函数的触发，这些函数被称为生命周期函数。

uni-app支持如下应用生命周期函数：前四个是常用的

页面的生命周期

uni-app支持如下页面生命周期函数：第二个到第六个是常用的

下拉刷新

开启下拉刷新

在uni-app中有两种方式开启下拉刷新

• 需要在 pages.json 里，找到的当前页面的pages节点，并在 style 选项中开启enablePullDownRefresh。
• 通过调用uni.startPullDownRefresh()方法来开启下拉刷新

通过配置文件开启
创建list页面进行演示

//template
<template>
	<view>
		<view v-for="item in list" :key="item">
			{{item}}
		</view>
	</view>
</template>
//script
<script>
	export default{
		data(){
			return{
				list:['前端','JAVA','UI','测试']
			}
		}
	}
</script>

通过pages.json文件中找到当前页面的pages节点，并在style选项中开启enablePullDownRefresh

{
	"path":"pages/list/list",
	"style":{
		"enablePullDownRefresh":true
	}
}

监听下拉刷新

通过onPullDownRefresh可以监听到下拉刷新的动作

export default{
		data(){
			return{
				list:['前端','JAVA','UI','测试']
			}
		},
		onPullDownRefresh() {
			console.log('触发了下拉刷新')
		},
		methods:{
			pullDown(){
				uni.startPullDownRefresh()
			}
		}
	}

关闭下拉刷新

uni.stopPullDownRefresh()
停止当前页面下拉刷新
案例演示：

<template>
	<view>
		<view>
			这是列表页
		</view>
		<view v-for="item in list" :key="item">
			{{item}}
		</view>
		<button type="default" @click="pullDown">下拉刷新</button>
	</view>
</template>
<script>
	export default{
		data(){
			return{
				list:['前端','JAVA','UI','测试']
			}
		},
		onPullDownRefresh() {
			console.log('触发了下拉刷新')
			setTimeout(()=>{
				this.list=['UI','测试','前端','JAVA']
				uni.stopPullDownRefresh()
			},2000)
		},
		methods:{
			pullDown(){
				uni.startPullDownRefresh()
			}
		}
	}
</script>

上拉加载

onReachBottom页面滚动到底部的事件(不是scroll-view滚到底)，常用于下拉下一页数据

onReachBottom() {
	console.log('页面触底了')
}

在pages.json中的pages中的style配置项中的onReachBottomDistance是用来配置页面上拉触底事件触发时距页面底部距离，单位只支持px。
例如：

{
			"path":"pages/list/list",
			"style":{
				"enablePullDownRefresh":true,
				"onReachBottomDistance":200
			}
		}

上拉加载更多

onReachBottom() {
	console.log('页面触底了')
	this.list=[...this.list,...['测试','前端','JAVA','UI','测试']]
}

网络请求

在uni中可以调用uni.request方法进行请求网络请求
需要注意的是：在小程序中网络相关的API在使用前需要配置域名白名单

发送get请求

<template>
	<view>
		<button type="default" @click="get">发送get请求</button>
	<view>
</template>		
<script>
	export default{
		methods:{
			get(){
				uni.request({
					url:"https://api-hmugo-web.itheima.net/api/public/v1/home/swiperdata",
					method:"get", //默认为get，不写也可以
					success(res){
						console.log(res)
					}
				})
			}
		}
   	}

</script>

数据缓存

官方文档

uni.setStorage(OBJECT)

将数据存储在本地缓存中指定的key中，会覆盖掉原来该key对应的内容，这是一个异步接口。
OBJECT参数说明

代码演示

//template
<button type="primary" @click="setStorage">存储数据</button>
//script
setStorage(){
	uni.setStorage({
		key:'id',
		data:80,
		success() {
			console.log('存储成功')
		}
	})
}

uni.setStorageSync(KEY,DATA)

将 data 存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口。

参数说明

代码演示

//template
<button type="primary" @click="setStorageSync">存储数据</button>
//script
setStorageSync(){
	uni.setStorageSync('id',100)
}

uni.getStorage(OBJECT)

从本地缓存中异步获取指定 key 对应的内容。

OBJECT 参数说明

success 返回参数说明

代码演示

//template
<button type="primary" @click="getStorage">获取数据</button>
//script
getStorage(){
	uni.getStorage({
		key:'id',
		success(res){
			console.log('获取成功',res)
		}
	})
}

uni.getStorageSync(KEY)

从本地缓存中同步获取指定 key 对应的内容。
参数说明

代码演示

//template
<button type="primary" @click="getStorageSync">获取数据</button>
//script
getStorageSync(){
	const res=uni.getStorageSync('id')
	console.log(res)
}

uni.removeStorage(OBJECT)

从本地缓存中异步移除指定 key。
OBJECT 参数说明

代码演示

//template
<button type="primary" @click="removeId">移除id</button>
//script
removeId(){
	uni.removeStorage({
		key:'id',
		success() {
			console.log('删除成功')
		}
	})
}

uni.removeStorageSync(KEY)

从本地缓存中同步移除指定 key。
参数说明

代码演示

//template
<button type="primary" @click="removeId">移除id</button>
//script
removeId(){
	uni.removeStorageSync('id')
}

上传图片、预览图片

上传图片

uni.chooseImage(OBJECT)方法从本地相册选择图片或使用相机拍照。
OBJECT 参数说明

Tips

• count 值在 H5 平台的表现，基于浏览器本身的规范。目前测试的结果来看，只能限制单选/多选，并不能限制数量。并且，在实际的手机浏览器很少有能够支持多选的。
• sourceType 在H5端对应input的capture属性，设置为['album']无效，依然可以使用相机。
• 可以通过用户授权API来判断用户是否给应用授予相册或摄像头的访问权限https://uniapp.dcloud.io/api/other/authorize
• App端如需选择非媒体文件，可在插件市场搜索文件选择，其中Android端可以使用Native.js，无需原生插件，而iOS端需要原生插件。
• 选择照片大多为了上传，uni ui封装了更完善的uni-file-picker组件，文件选择、上传到uniCloud的免费存储和cdn中，一站式集成。强烈推荐使用。

注：文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 uni.saveFile，在应用下次启动时才能访问得到。

success返回参数说明

File 对象结构如下

案例：

<template>
	<view>
		<button type="primary" @click="chooseImg">上传图片</button>
		<image v-for="item in imgArr" :src="item"></image>
	</view>
</template>

<script>
	export default{
		data(){
			return{
				imgArr:[]
			}
		},
		methods:{
			chooseImg(){
				uni.chooseImage({
					count:5,
					success:res=> {
						this.imgArr=res.tempFilePaths
					}
				})
			}
		}
	}
</script>

预览图片

uni.previewImage(OBJECT)方法预览图片。
OBJECT 参数说明

current 参数说明

1.9.5+ 支持传图片在 urls 中的索引值

current 为当前显示图片的链接/索引值，不填或填写的值无效则为 urls 的第一张。App平台在 1.9.5至1.9.8之间，current为必填。不填会报错

注意，当 urls 中有重复的图片链接时：

• 传链接，预览结果始终显示该链接在 urls 中第一次出现的位置。
• 传索引值，在微信/百度/字节跳动小程序平台，会过滤掉传入的 urls 中该索引值之前与其对应图片链接重复的值。其它平台会保留原始的urls 不会做去重处理。

longPressActions 参数说明

success 返回参数说明

案例：

<template>
	<view>
		<button type="primary" @click="chooseImg">上传图片</button>
		<image v-for="item in imgArr" :src="item" @click="previewImg(item)"></image>
	</view>
</template>
<script>
	export default{
		data(){
			return{
				imgArr:[]
			}
		},
		methods:{
			chooseImg(){
				uni.chooseImage({
					count:5,
					success:res=> {
						this.imgArr=res.tempFilePaths
					}
				})
			},
			previewImg(current){
				uni.previewImage({
					current:current,
					urls:this.imgArr,
					loop:true,
					indicator:'default'
				})
			}
		}
	}
</script>

TIPS

• 在非H5端，previewImage是原生实现的，界面自定义灵活度较低。
• 插件市场有前端实现的previewImage，性能低于原生实现，但界面可随意定义；插件市场也有适于App端的previewImage原生插件，提供了更多功能。

条件注释实现跨端兼容

uni-app 已将常用的组件、JS API 封装到框架中，开发者按照 uni-app 规范开发即可保证多平台兼容，大部分业务均可直接满足。

但每个平台有自己的一些特性，因此会存在一些无法跨平台的情况。

• 大量写 if else，会造成代码执行性能低下和管理混乱。
• 编译到不同的工程后二次修改，会让后续升级变的很麻烦。

在 C 语言中，通过 #ifdef、#ifndef 的方式，为 windows、mac 等不同 os 编译不同的代码。 uni-app 参考这个思路，为 uni-app 提供了条件编译手段，在一个工程里优雅的完成了平台个性化实现。

条件编译是用特殊的注释作为标记，在编译时根据这些特殊的注释，将注释里面的代码编译到不同平台。

写法：以 #ifdef 或 #ifndef 加 %PLATFORM% 开头，以 #endif 结尾。

• #ifdef：if defined 仅在某平台存在
• #ifndef：if not defined 除了某平台均存在
• %PLATFORM%：平台名称

%PLATFORM% 可取值如下：

支持的文件

• .vue
• .js
• .css
• pages.json
• 各预编译语言文件，如：.scss、.less、.stylus、.ts、.pug

注意：

• 条件编译是利用注释实现的，在不同语法里注释写法不一样，js使用 // 注释、css 使用 /* 注释 */、vue/nvue 模板里使用 <!-- 注释 -->；
• 条件编译APP-PLUS包含APP-NVUE和APP-VUE，APP-PLUS-NVUE和APP-NVUE没什么区别，为了简写后面出了APP-NVUE；
• 使用条件编译请保证编译前和编译后文件的正确性，比如json文件中不能有多余的逗号；