# uni-app 使用

# install

npm install -g @vue/cli

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

# 运行、发布uni-app
npm run dev:%PLATFORM%
npm run build:%PLATFORM%

%PLATFORM% 可取值  mp-weixin

npm run dev:mp-weixin
1
2
3
4
5
6
7
8
9
10
11
  • dev 模式编译出的各平台代码存放于根目录下的 /dist/dev/目录,打开各平台开发工具选择对应平台目录即可进行预览(h5 平台不会在此目录,存在于缓存中);
  • build 模式编译出的各平台代码存放于根目录下的 /dist/build/ 目录,发布时选择此目录进行发布;

# uni-app 约定了如下开发规范:

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

虽然不推荐使用HTML标签,但实际上如果开发者写了div等标签,在编译到非H5平台时也会被编译器转换为view标签,类似的还有span转text、a转navigator等,包括css里的元素选择器也会转。
但为了管理方便、策略统一,新写代码时仍然建议使用view等组件。

# 目录结构

┌─cloudfunctions        云函数目录(阿里云为aliyun,腾讯云为tcb,详见uniCloud)
│─components            符合vue组件规范的uni-app组件目录
│  └─comp-a.vue         可复用的a组件
├─hybrid                存放本地网页的目录,详见
├─platforms             存放各平台专用页面的目录,详见
├─pages                 业务页面文件存放的目录
│  ├─index
│  │  └─index.vue       index页面
│  └─list
│     └─list.vue        list页面
├─static                存放应用引用静态资源(如图片、视频等)的目录,注意:静态资源只能存放于此
├─wxcomponents          存放小程序组件的目录,详见
├─main.js               Vue初始化入口文件
├─App.vue               应用配置,用来配置App全局样式以及监听 应用生命周期
├─manifest.json         配置应用名称、appid、logo、版本等打包信息,详见
└─pages.json            配置页面路由、导航条、选项卡等页面类信息,详见
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 静态资源

# 模板内引入静态资源

template内引入静态资源,如image、video等标签的src属性时,可以使用相对路径或者绝对路径,形式如下

<!-- 绝对路径,/static指根目录下的static目录,在cli项目中/static指src目录下的static目录 -->
<image class="logo" src="/static/logo.png"></image>
<image class="logo" src="@/static/logo.png"></image>
<!-- 相对路径 -->
<image class="logo" src="../../static/logo.png"></image>
1
2
3
4
5

注意:
@开头的绝对路径以及相对路径会经过base64转换规则校验
引入的静态资源在非h5平台,均不转为base64。
H5平台,小于4kb的资源会被转换成base64,其余不转。
自HBuilderX 2.6.6-alpha起template内支持@开头路径引入静态资源,旧版本不支持此方式
App平台自HBuilderX 2.6.9-alpha起template节点中引用静态资源文件时(如:图片),调整查找策略为【基于当前文件的路径搜索】,与其他平台保持一致
支付宝小程序组件内 image 标签不可使用相对路径

# js文件引入

js文件或script标签内(包括renderjs等)引入js文件时,可以使用相对路径和绝对路径,形式如下

// 绝对路径,@指向项目根目录,在cli项目中@指向src目录
import add from '@/common/add.js'
// 相对路径
import add from '../../common/add.js'
1
2
3
4
5
6

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

# css引入静态资源

css文件或style标签内引入css文件时(scss、less文件同理),可以使用相对路径或绝对路径(HBuilderX 2.6.6-alpha)

/* 绝对路径 */
@import url('/common/uni.css');
@import url('@/common/uni.css');
/* 相对路径 */
@import url('../../common/uni.css');
1
2
3
4
5
6
7

css文件或style标签内引用的图片路径可以使用相对路径也可以使用绝对路径,需要注意的是,有些小程序端css文件不允许引用本地文件(请看注意事项)。

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

在 uni-app 中不能使用 * 选择器。
微信小程序自定义组件中仅支持 class 选择器
page 相当于 body 节点
1
2
3
4
5
6
7
8
9

Tips:

  • 引入字体图标请参考,字体图标
  • @开头的绝对路径以及相对路径会经过base64转换规则校验
  • 不支持本地图片的平台,小于40kb,一定会转base64。(共四个平台mp-weixin, mp-qq, mp-toutiao, app v2)
  • h5平台,小于4kb会转base64,超出4kb时不转。
  • 其余平台不会转base64

# CSS变量

uni-app 提供内置 CSS 变量

CSS变量	描述	App	小程序	H5
--status-bar-height	系统状态栏高度	系统状态栏高度、nvue注意见下	25px	0
--window-top	内容区域距离顶部的距离	0	0	NavigationBar 的高度
--window-bottom	内容区域距离底部的距离	0	0	TabBar 的高度
注意:

var(--status-bar-height) 此变量在微信小程序环境为固定 25px,在 App 里为手机实际状态栏高度。  
当设置 "navigationStyle":"custom" 取消原生导航栏后,由于窗体为沉浸式,占据了状态栏位置。此时可以使用一个高度为 var(--status-bar-height) 的 view 放在页面顶部,避免页面内容出现在状态栏。  
由于在H5端,不存在原生导航栏和tabbar,也是前端div模拟。如果设置了一个固定位置的居底view,在小程序和App端是在tabbar上方,但在H5端会与tabbar重叠。此时可使用--window-bottom,不管在哪个端,都是固定在tabbar上方。
目前 nvue 在App端,还不支持 --status-bar-height变量,替代方案是在页面onLoad时通过uni.getSystemInfoSync().statusBarHeight获取状态栏高度,然后通过style绑定方式给占位view设定高度。


onLoad() {
    this.iStatusBarHeight = uni.getSystemInfoSync().statusBarHeight
}

ni-app 中以下组件的高度是固定的,不可修改:

组件	描述	App	H5
NavigationBar	导航栏	44px	44px
TabBar	底部选项卡	HBuilderX 2.3.4之前为56px,2.3.4起和H5调为一致,统一为 50px。但可以自主更改高度)	50px
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 生命周期

  • 应用生命周期

uni-app 支持 onLaunch、onShow、onHide 等应用生命周期函数,详情请参考应用生命周期

  • 页面生命周期

uni-app 支持 onLoad、onShow、onReady 等生命周期函数

# 路由跳转

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

# 开发环境和生产环境

uni-app 可通过 process.env.NODE_ENV 判断当前环境是开发环境还是生产环境

  • 判断平台: uni.getSystemInfoSync().platform

# 小程序组件支持

uni-app 支持在 App 和 小程序 中使用小程序自定义组件,从HBuilderX2.4.7起,H5端也可以运行微信小程序组件。

平台差异说明

平台 支持情况 小程序组件存放目录
H5 支持微信小程序组件(2.4.7+) wxcomponents
App(不含nvue) 支持微信小程序组件 wxcomponents
微信小程序 支持微信小程序组件 wxcomponents
支付宝小程序 支持支付宝小程序组件 mycomponents
百度小程序 支持百度小程序组件 swancomponents
字节跳动小程序 支持字节跳动小程序组件 ttcomponents
QQ小程序 支持QQ小程序组件 wxcomponents

# 引入 vantUI

npm i @vant/weapp -S --production

在项目根目录下新建 wxcomponents 目录

将vant/weapp中dist目录拷贝到新建的wxcomponents目录下,并重命名dist为vant

# 单个页面引入
page.json:

"pages": [ //pages数组中第一项表示应用启动页,参考:https://uniapp.dcloud.io/collocation/pages
		{
			"path": "pages/index/index",
			"style": {
				"navigationBarTitleText": "uni-app",
				"usingComponents": {
					      "van-button": "/wxcomponents/vant/button/index",
				}
			}
		}
	],
  
  
# 全局引入

"globalStyle": {
		"navigationBarTextStyle": "black",
		"navigationBarTitleText": "uni-app",
		"navigationBarBackgroundColor": "#F8F8F8",
		"backgroundColor": "#F8F8F8",
		"usingComponents": {
		    "van-button": "/wxcomponents/vant/button/index",
		    "van-image": "/wxcomponents/vant/image/index",
		    "van-field": "/wxcomponents/vant/field/index",
		    "van-search": "/wxcomponents/vant/search/index",
		    "van-cell": "/wxcomponents/vant/cell/index",
		    "van-cell-group": "/wxcomponents/vant/cell-group/index",
		    "van-notice-bar": "/wxcomponents/vant/notice-bar/index"
		}
	}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

#

  • 使用 vue-cli 安装,一直报错

  • 修改hosts:

    • https://github.com.ipaddress.com/ 查看 ip
    • https://fastly.net.ipaddress.com/github.global.ssl.fastly.net
    # github
    140.82.114.3 www.github.com
    140.82.114.3 github.com
    
    # 192.30.253.112 www.github.com
    # 192.30.253.112 github.com
    
    199.232.69.194 github.global.ssl.fastly.net
    # 151.101.13.194 github.global.ssl.fastly.net
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
 ERROR  Failed fetching remote preset dcloudio/uni-preset-vue:
 ERROR  Error: end of central directory record signature not found
 
 手动下载 uni-preset-vue
 
 vue create --preset ./uni-preset-vue my-project
 
 再选择模板 默认模板快 ,  hello很慢
1
2
3
4
5
6
7
8

# getApp()

函数用于获取当前应用实例,一般用于获取globalData

const app = getApp()
console.log(app.globalData)


1
2
3
4

# getCurrentPages()

getCurrentPages() 函数用于获取当前页面栈的实例,以数组形式按栈的顺序给出,第一个元素为首页,最后一个元素为当前页面。

注意: getCurrentPages()仅用于展示页面栈的情况,请勿修改页面栈,以免造成页面状态错误。

# 参考