Fade away

Appearance

uni-app ​

一、uni-app介绍 ​

1.什么是uni-app ​

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

翻译翻译就是：写一套代码就可以在多端运行

DCloud公司拥有900万开发者、数百万应用、12亿手机端月活用户、数千款uni-app插件、70+微信/qq群。阿里小程序工具官方内置uni-app（详见 ），腾讯课堂官方为uni-app录制培训课程（详见 ），开发者可以放心选择。

uni-app在手，做啥都不愁。即使不跨端，uni-app也是更好的小程序开发框架（详见 ）、更好的App跨平台框架、更方便的H5开发框架。不管领导安排什么样的项目，你都可以快速交付，不需要转换开发思维、不需要更改开发习惯。

2.uni-app 环境搭建 ​

uni-app支持通过 可视化界面、vue-cli命令行 两种方式快速创建项目。

可视化的方式比较简单，HBuilderX内置相关环境，开箱即用，无需配置nodejs。

开始之前，开发者需先下载安装如下工具：

HBuilderX是通用的前端开发工具，但为uni-app做了特别强化。

2.1 创建uni-app ​

在点击工具栏里的文件 -> 新建 -> 项目（快捷键Ctrl+N）：

选择uni-app类型，输入工程名，选择模板，点击创建，即可成功创建。

uni-app自带的模板有 默认的空项目模板、Hello uni-app 官方组件和API示例，还有一个重要模板是 uni ui项目模板，日常开发推荐使用该模板，已内置大量常用组件。

开发者也可以使用cli方式创建项目，另见文档 。

差别是：HBuilderX创建的项目根目录就是源码，可直接编辑。uni-app的编译器在HBuilderX的插件目录下，跟随HBuilderX升级而一起升级。

如果开发者习惯于node模式的项目，对HBuilderX可视化方式感到困惑，可另行参考文档：## cli创建项目和HBuilderX可视化界面创建项目的区别

2.2 运行uni-app ​

1.浏览器运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到浏览器 -> 选择浏览器，即可体验 uni-app 的 web 版。

2.运行App到手机或模拟器：使用电压足够的usb端口连接手机，设置中开启USB调试，手机上允许电脑设备调试手机，进入hello-uniapp项目，点击工具栏的运行 -> 运行App到手机或模拟器，即可在该设备里面体验uni-app。

3.在微信开发者工具里运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到小程序模拟器 -> 微信开发者工具，即可在微信开发者工具里面体验uni-app。

注意：如果是第一次使用，需要先配置小程序ide的相关路径，才能运行成功。如下图，需在输入框输入微信开发者工具的安装路径。

注意：微信开发者工具需要开启服务端口 在微信工具的设置->安全中。

3.uni-app的开发目录结构 ​

3.1 官方 ​

一个uni-app工程，默认包含如下目录及文件：

json
┌─uniCloud              云空间目录，阿里云为uniCloud-aliyun,腾讯云为uniCloud-tcb（详见uniCloud）
│─components            符合vue组件规范的uni-app组件目录
│  └─comp-a.vue         可复用的a组件
├─utssdk                存放uts文件
├─pages                 业务页面文件存放的目录
│  ├─index
│  │  └─index.vue       index页面
│  └─list
│     └─list.vue        list页面
├─static                存放应用引用的本地静态资源（如图片、视频等）的目录，注意：静态资源只能存放于此
├─uni_modules           存放[uni_module](/uni_modules)。
├─platforms             存放各平台专用页面的目录，详见
├─nativeplugins         App原生语言插件 详见
├─nativeResources       App端原生资源目录
│  └─android            Android原生资源目录 详见
├─hybrid                App端存放本地html文件的目录，详见
├─wxcomponents          存放小程序组件的目录，详见
├─unpackage             非工程代码，一般存放运行或发行的编译结果
├─AndroidManifest.xml   Android原生应用清单文件 详见
├─main.js               Vue初始化入口文件
├─App.vue               应用配置，用来配置App全局样式以及监听 应用生命周期
├─manifest.json         配置应用名称、appid、logo、版本等打包信息，详见
├─pages.json            配置页面路由、导航条、选项卡等页面类信息，详见
└─uni.scss              这里是uni-app内置的常用样式变量

Tips

  • 编译到任意平台时，static 目录下的文件均会被完整打包进去，且不会编译。非 static 目录下的文件（vue、js、css 等）只有被引用到才会被打包编译进去。
  • static 目录下的 js 文件不会被编译，如果里面有 es6 的代码，不经过转换直接运行，在手机设备上会报错。
  • css、less/scss 等资源不要放在 static 目录下，建议这些公用的资源放在自建的 common 目录下。
  • HbuilderX 1.9.0+ 支持在根目录创建 ext.json、sitemap.json 等小程序需要的文件。

3.2 基础项目 ​

js
pages目录： 存放页面的。
static目录：存放静态资源的。
unpackage目录：存放最终打包的存放位置。
App.vue文件：项目根组件。
main.js文件：项目的入口文件，也就是项目加载时，先加载main.js文件。
manifest.json文件：负责管理打包的一些配置，指定应用名称，图标，权限等。
pages.json文件：页面路由，负责设置整个项目的页面(pages)存放路径以及窗口外观(globalStyle)的。
uni.scss文件：配置一些颜色什么的。

uni-app的开发规范：(看起来就是Vue和小程序混合起来了)

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

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

二、全局配置 ​

1.globalStyle 全局外观配置 ​

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

对应官方文档：https://uniapp.dcloud.io/collocation/pages.html#globalstyle

部分属性：

  • navigationBar开头的都是导航栏设置（小程序导航栏+手机导航栏）
  • navigationBarBackgroundColor 导航栏背景颜色
  • navigationBarTitleText 导航栏标题文字内容
  • navigationBarTextStyle 导航栏标题颜色，仅支持 black / white
  • enablePullDownRefresh 是否开启全局的下拉刷新。 （默认为false）
  • backgroundTextStyle 下拉 loading 的样式，仅支持 dark / light
  • backgroundColor 设置下拉 loading的背景颜色

1.1 导航栏样式配置 ​

导航栏属于下图红色框位置：

导航栏配置需要注意的是：

  • 页面级的navigationBarTitleText会覆盖全局的navigationBarTitleText

1.2 上拉触底效果 ​

onReachBottomDistance 这个配置适用于页面快到下面的时候，触发下一页等情况。

2.pages页面配置 ​

uni-app 通过 pages 节点配置应用由哪些页面组成，pages 节点接收一个数组，数组每个项都是一个对象，其属性值如下：

属性类型默认值描述
pathString配置页面路径
styleObject配置页面窗口表现，配置项参考下方 pageStyle

Tips：

  • pages节点的第一项为应用入口页（即首页）
  • 应用中新增/减少页面，都需要对 pages 数组进行修改
  • 文件名不需要写后缀，框架会自动寻找路径下的页面资源

开发目录为：

js
┌─pages
│  ├─index
│  │  └─index.vue
│  └─message
│     └─message.vue
├─static
├─main.js
├─App.vue
├─manifest.json
└─pages.json

pages的页面配置：

js
"pages": [ //pages数组中第一项表示应用启动页，参考：https://uniapp.dcloud.io/collocation/pages
	{
		//新创建的message.vue，对应的添加上路径。
		"path": "pages/message/message",
		//可以配置style样式。
		"style":{
			"navigationBarTitleText":"信息页",
			"navigationBarBackgroundColor": "#2866f7",
			//根据官方可以专门设置h5内容。其他情况不受影响。
			"h5":{
				"pullToRefresh": {
					"color":"#333333"
				}
			}
		}
	},
	{
		"path": "pages/index/index"
	}
],

3.tabBar底部导航栏 ​

对应官方文档：https://uniapp.dcloud.io/collocation/pages.html#tabbar

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

在 pages.json 中提供 tabBar 配置，不仅仅是为了方便快速开发导航，更重要的是在App和小程序端提升性能。在这两个平台，底层原生引擎在启动时无需等待js引擎初始化，即可直接读取 pages.json 中配置的 tabBar 信息，渲染原生tab。

Tips

  • 当设置 position 为 top 时，将不会显示 icon
  • tabBar 中的 list 是一个数组，只能配置最少2个、最多5个 tab，tab 按数组的顺序排序。
  • tabbar 切换第一次加载时可能渲染不及时，可以在每个tabbar页面的onLoad生命周期里先弹出一个等待雪花（hello uni-app使用了此方式）
  • tabbar 的页面展现过一次后就保留在内存中，再次切换 tabbar 页面，只会触发每个页面的onShow，不会再触发onLoad。
  • 顶部的 tabbar 目前仅微信小程序上支持。需要用到顶部选项卡的话，建议不使用 tabbar 的顶部设置，而是自己做顶部选项卡，可参考 hello uni-app->模板->顶部选项卡。

tabbar就是如下图一样：

在pages.json配置如下：

json
//设置导航栏
"tabBar":{
    // tab 上的文字默认颜色	
    "color": "#ccc",
    // tab 上的文字选中时的颜色	
    "selectedColor": "#ff55ff",
	//声明多个导航栏
	"list":[
		{
			"text":"首页", //名称
			"pagePath":"pages/index/index", //路径
			"iconPath":"static/logo.png", //图片路径
			"selectedIconPath":"static/1.jpg" //选择后图片路径
		},
		{
			"text":"琴谱",
			"pagePath":"pages/message/message",
			"iconPath":"static/logo.png",
			"selectedIconPath":"static/1.jpg"
		},
		{
			"text":"个人中心",
			"pagePath":"pages/user/user",
			"iconPath":"static/logo.png",
			"selectedIconPath":"static/1.jpg"
		}
	]
}

4.condition 启动模式配置 ​

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

属性说明：

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

list说明：

属性类型是否必填描述
nameString是启动模式名称
pathString是启动页面路径
queryString否启动参数，可在页面的 onLoad 函数里获得
js
//condition启动模式配置
"condition":{
	//当前激活的模式，list节点的索引值
	"current":0,
	//启动模式列表
	"list":[
		{
			"name":"详情页",	//启动模式名称
			"path":"pages/detail/detail", //启动页面路径
			"query":"id=80"	//启动参数，进入页面时的onLoad 函数的参数就可以拿到该参数
		}
	]
}

页面参数如下图：

5.easycom模式 ​

HBuilderX 2.5.5起支持easycom组件模式。

传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。

easycom将其精简为一步。 只要组件安装在项目的components目录下，并符合components/组件名称/组件名称.vue目录结构。就可以不用引用、注册，直接在页面中使用。 如下：

vue
<template>
<view class="container">
    <ds-test></ds-test>
    </view>
</template>
<script>
    // 这里不用import引入，也不需要在components内注册uni-list组件。template里就可以直接用
    export default {
        data() {
            return {

            }
        }
    }
</script>

  • 不管components目录下安装了多少组件，easycom打包后会自动剔除没有使用的组件，对组件库的使用尤为友好。
  • 组件库批量安装，随意使用，自动按需打包。以官方的uni-ui为例，在HBuilderX新建项目界面选择uni-ui项目模板，只需在页面中敲u，拉出大量组件代码块，直接选择，即可使用。大幅提升开发效率，降低使用门槛。
  • 在uni-app插件市场 (opens new window)下载符合components/组件名称/组件名称.vue目录结构的组件，均可直接使用。
  • easycom是自动开启的，不需要手动开启，有需求时可以在pages.json的easycom节点进行个性化设置，如关闭自动扫描，或自定义扫描匹配组件的策略。设置参数如下：
属性类型默认值描述
autoscanBooleantrue是否开启自动扫描，开启后将会自动扫描符合components/组件名称/组件名称.vue目录结构的组件
customObject-以正则方式自定义组件匹配规则。如果autoscan不能满足需求，可以使用custom自定义匹配规则

自定义easycom配置的示例

如果需要匹配node_modules内的vue文件，需要使用packageName/path/to/vue-file-$1.vue形式的匹配规则，其中packageName为安装的包名，/path/to/vue-file-$1.vue为vue文件在包内的路径。

json
"easycom": {
    "autoscan": true,
    "custom": {
        "ds-(.*)": "@/components/ds-$1/ds-$1.vue" // 匹配components目录内的vue文件
    }
}

说明

  • easycom方式引入的组件无需在页面内import，也不需要在components内声明，即可在任意页面使用
  • easycom方式引入组件不是全局引入，而是局部引入。例如在H5端只有加载相应页面才会加载使用的组件
  • 在组件名完全一致的情况下，easycom引入的优先级低于手动引入（区分连字符形式与驼峰形式）
  • 考虑到编译速度，直接在pages.json内修改easycom不会触发重新编译，需要改动页面内容触发。
  • easycom只处理vue组件，不处理小程序专用组件（如微信的wxml格式组件）。不处理后缀为.nvue的组件。但vue组件也可以全端运行，包括小程序和app-nvue。可以参考uni ui，使用vue后缀，同时兼容nvue页面。

三、内置组件 ​

1.视图容器 ​

1.1 view ​

uni-app官网 (dcloud.net.cn)

它类似于传统html中的div，用于包裹各种元素内容。

如果使用nvue，则需注意，包裹文字应该使用<text>组件。

属性说明

属性名类型默认值说明
hover-classStringnone指定按下去的样式类。当 hover-class="none" 时，没有点击态效果
hover-stop-propagationBooleanfalse指定是否阻止本节点的祖先节点出现点击态，App、H5、支付宝小程序、百度小程序不支持（支付宝小程序、百度小程序文档中都有此属性，实测未支持）
hover-start-timeNumber50按住后多久出现点击态，单位毫秒
hover-stay-timeNumber400手指松开后点击态保留时间，单位毫秒
vue
<template>
<view class="box2" hover-class="box2-active">
    <view 
          class="box" 
          hover-class="box-active" 
          hover-stop-propagation
          :hover-start-time="2000"
          :hover-stay-time="2000"
          >我是一个大盒子</view>
    </view>
</template>

<script>
</script>

<style>
    .box{
        width: 100px;
        height: 100px;
        background: #4CD964;
    },
    .box-active{
        width: 100px;
        height: 100px;
        background: #007AFF;
    },
    .box2{
        width: 300px;
        height: 300px;
        background: #d9a319;
    },
    .box2-active{
        width: 300px;
        height: 300px;
        background: #ff0a22;
    }
</style>

Tips

  • 小程序平台如果使用 <div> ，编译时会被转换为 <view>。
  • App平台 Vue2 项目在节点非常多时可以尝试使用 <div> 替换 <view> 以提升渲染性能。

1.2 scroll-view ​

scroll-view | uni-app官网 (dcloud.net.cn)

可滚动视图区域。用于区域滚动。

需注意在webview渲染的页面中，区域滚动的性能不及页面滚动。

vue
<template>
<scroll-view class="container1" scroll-y>
    <view>1</view>
    <view>2</view>
    <view>3</view>
    </scroll-view>
</template>

<style>
    .container1 {
        border: 1px solid red;
        /* 给scroll-view设置固定高度 */
        height: 120px;
        width: 100px
    }
    .container1 view {
        width: 100px;
        height: 100px;
        line-height: 100px;
        text-align: center;
        color: #fff;
    }
    .container1 view:nth-child(1) {
        background-color: #12aa9c;
    }
    .container1 view:nth-child(2) {
        background-color: #2775b6;
    }
    .container1 view:nth-child(3) {
        background-color: #ee3f4d;
    }
</style>

1.3 swiper ​

swiper | uni-app官网 (dcloud.net.cn)

一般用于左右滑动或上下滑动，比如banner轮播图。

注意滑动切换和滚动的区别，滑动切换是一屏一屏的切换。swiper下的每个swiper-item是一个滑动切换区域，不能停留在2个滑动区域之间。

vue
<template>
<!-- 轮播图区域 -->
<!-- indicator-dots 显示面板指示点 -->
<swiper class="swiper-container" indicator-dots>
    <!-- 第一项 -->
    <swiper-item>
        <view class="item">A</view>
    </swiper-item>
    <!-- 第二项 -->
    <swiper-item>
        <view class="item">B</view>
    </swiper-item>
    <!-- 第三项 -->
    <swiper-item>
        <view class="item">C</view>
    </swiper-item>
    </swiper>
</template>

<style>
    .swiper-container {
        /* 轮播图容器的高度 */
        height: 150px;
    }
    .item {
        height: 100%;
        line-height: 150px;
        text-align: center;
    }
    swiper-item:nth-child(1) .item {
        background-color: lightgreen;
    }
    swiper-item:nth-child(2) .item {
        background-color: lightblue;
    }
    swiper-item:nth-child(3) .item {
        background-color: lightcoral;
    }
</style>

2.基础内容 ​

2.1 icon ​

icon | uni-app官网 (dcloud.net.cn)

图标。

Tips

  • 由于 icon 组件各端表现存在差异，可以通过使用 字体图标 的方式来弥补各端差异。

属性说明

属性名类型默认值说明
typeStringicon的类型
sizeNumber23icon的大小，单位px
colorColoricon的颜色，同css的color
vue
<template>
<view class="item" v-for="(value,index) in iconType" :key="index">
    <icon :type="value" size="26"/>
    <text>{{value}}</text>
    </view>
</template>

<script>
    export default {
        data() {
            return {
                iconType: ['success']
            }
        },
        onLoad() {
            // #ifdef APP-PLUS|| MP-WEIXIN
            this.iconType = ['success', 'success_no_circle', 'info', 'warn', 'waiting', 'cancel', 'download', 'search','clear']
            // #endif
            // #ifdef MP-ALIPAY
            this.iconType = ['info', 'warn', 'waiting', 'cancel', 'download', 'search', 'clear', 'success', 'success_no_circle', 'loading']
            // #endif
            // #ifdef MP-BAIDU
            this.iconType = ['success', 'info', 'warn', 'waiting', 'success_no_circle', 'clear', 'search', 'personal', 'setting', 'top', 'close', 'cancel', 'download', 'checkboxSelected', 'radioSelected', 'radioUnselect']
            // #endif
        }
    }
</script>

2.2 text ​

text | uni-app官网 (dcloud.net.cn)

文本组件。

用于包裹文本内容。

属性说明

属性名类型默认值说明平台差异说明
selectableBooleanfalse文本是否可选App、H5、快手小程序
user-selectBooleanfalse文本是否可选微信小程序
spaceString显示连续空格App、H5、微信小程序
decodeBooleanfalse是否解码App、H5、微信小程序

space 值说明

值说明
ensp中文字符空格一半大小
emsp中文字符空格大小
nbsp根据字体设置的空格大小
vue
<template>
<view>
    <view>
        <text>
            唱歌跳舞打篮球
    </text>
    </view>
    <view>
        <!-- selectable文本可选 -->
        <text selectable>
            唱歌跳舞打篮球
    </text>
    </view>
    <view>
        <!-- space有多个值,如果不设置那么都会默认一个空格。 -->
        <text selectable space="ensp">
            唱歌      跳舞打篮球
    </text>
    </view>
    <view>
        <!-- decode 可以解析的有 &nbsp; &lt; &gt; &amp; &apos; &ensp; &emsp;。 -->
        <text selectable>
            &nbsp; &lt; &gt; &amp; &apos; &ensp; &emsp;
    </text>
    </view>
    </view>
</template>

3.路由与页面跳转 ​

3.1 navigator ​

navigator | uni-app官网 (dcloud.net.cn)

页面跳转。

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

该组件的功能有API方式，另见：https://uniapp.dcloud.io/api/router?id=navigateto

属性说明

属性名类型默认值说明平台差异说明
urlString应用内的跳转链接，值为相对路径或绝对路径，如："../first/first"，"/pages/first/first"，注意不能加 .vue 后缀
open-typeStringnavigate跳转方式

open-type 有效值

值说明平台差异说明
navigate对应 uni.navigateTo 的功能保留 当前页面，跳转到应用内的某个页面，使用uni.navigateBack可以返回到原页面。
redirect对应 uni.redirectTo 的功能 关闭当前页面，跳转到应用内的某个页面。
switchTab对应 uni.switchTab 的功能 跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。 可以携带参数
reLaunch对应 uni.reLaunch 的功能 关闭所有页面，打开到应用内的某个页面。 如果跳转的页面路径是 tabBar 页面则不能带参数字节跳动小程序与飞书小程序不支持
navigateBack对应 uni.navigateBack 的功能 关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层。
exit退出小程序，target="miniProgram"时生效微信2.1.0+、百度2.5.2+、QQ1.4.7+
vue
<template>
<view>
    navigator组件 导航跳转的学习
    <!-- 跳转普通页 -->
    <navigator url="/pages/list/list">跳转至信息页</navigator>
    <!-- 跳转tabbar页面，需要添加open-type="switchTab" -->
    <navigator url="/pages/index/index" open-type="switchTab">跳转至主页</navigator>
    <!-- redirect跳转后，会关闭之前页面。也就是没有了" < " 回退了。   -->
    <navigator url="/pages/list/list" open-type="redirect">跳转至信息页</navigator>
    </view>
</template>

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

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

vue
<navigator :url="'/pages/navigate/navigate?item='+ encodeURIComponent(JSON.stringify(item))"></navigator>
// navigate.vue页面接受参数
onLoad: function (option) {
	const item = JSON.parse(decodeURIComponent(option.item));
}

4.媒体组件 ​

4.1 image ​

image | uni-app官网 (dcloud.net.cn)

图片。

属性名类型默认值说明平台差异说明
srcString图片资源地址
modeString'scaleToFill'图片裁剪、缩放的模式
lazy-loadBooleanfalse图片懒加载。只针对page与scroll-view下的image有效微信小程序、百度小程序、字节跳动小程序、飞书小程序

Tips

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

mode 有效值：

mode 有 14 种模式，其中 5 种是缩放模式，9 种是裁剪模式。

模式值说明
缩放scaleToFill不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素
缩放aspectFit保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。
缩放aspectFill保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。
缩放widthFix宽度不变，高度自动变化，保持原图宽高比不变
缩放heightFix高度不变，宽度自动变化，保持原图宽高比不变 App 和 H5 平台 HBuilderX 2.9.3+ 支持、微信小程序需要基础库 2.10.3

常用aspectFill

四、网络请求 ​

1. uni.request() ​

uni.request(OBJECT) | uni-app官网 (dcloud.net.cn)

发起网络请求。

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。

success等等函数最好都要用箭头函数，不然拿不到this指定的data数据！

OBJECT 参数说明

参数名类型必填默认值说明平台差异说明
urlString是开发者服务器接口地址
dataObject/String/ArrayBuffer否请求的参数App 3.3.7 以下不支持 ArrayBuffer 类型
headerObject否设置请求的 header，header 中不能设置 Referer。App、H5端会自动带上cookie，且H5端不可手动修改
methodString否GET有效值详见下方说明
timeoutNumber否60000超时时间，单位 msH5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序（2.10.0）、支付宝小程序
successFunction否收到开发者服务器成功返回的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数类型说明
dataObject/String/ArrayBuffer开发者服务器返回的数据
statusCodeNumber开发者服务器返回的 HTTP 状态码
headerObject开发者服务器返回的 HTTP Response Header
cookiesArray.<string>开发者服务器返回的 cookies，格式为字符串数组

data 数据说明

最终发送给服务器的数据是 String 类型，如果传入的 data 不是 String 类型，会被转换成 String。转换规则如下：

  • 对于 GET 方法，会将数据转换为 query string。例如 { name: 'name', age: 18 } 转换后的结果是 name=name&age=18。
  • 对于 POST 方法且 header['content-type'] 为 application/json 的数据，会进行 JSON 序列化。
  • 对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据，会将数据转换为 query string。

示例

js
uni.request({
    url: 'https://www.example.com/request', //仅为示例，并非真实接口地址。
    data: {
        text: 'uni.request'
    },
    header: {
        'custom-header': 'hello' //自定义请求头信息
    },
    success: (res) => {
        console.log(res.data);
        this.text = 'request success';
    }
});

在页面刚加载的时候就请求数据 需要在页面的onLoad事件中调用获取数据的函数

js
/**
* 生命周期函数--监听页面加载
*/
onLoad(options) {
    this.getInfo()
},

返回值

如果希望返回一个 requestTask 对象，需要至少传入 success / fail / complete 参数中的一个。例如：

var requestTask = uni.request({
	url: 'https://www.example.com/request', //仅为示例，并非真实接口地址。
	complete: ()=> {}
});
requestTask.abort();

如果没有传入 success / fail / complete 参数，则会返回封装后的 Promise 对象：Promise 封装

通过 requestTask，可中断请求任务。

requestTask 对象的方法列表

方法参数说明
abort中断请求任务
offHeadersReceived取消监听 HTTP Response Header 事件，仅微信小程序平台支持，文档详情
onHeadersReceived监听 HTTP Response Header 事件。会比请求完成事件更早，仅微信小程序平台支持，文档详情

示例

const requestTask = uni.request({
	url: 'https://www.example.com/request', //仅为示例，并非真实接口地址。
	data: {
        name: 'name',
        age: 18
	},
	success: function(res) {
		console.log(res.data);
	}
});

// 中断请求任务
requestTask.abort();

Tips

  • 请求的 header 中 content-type 默认为 application/json。
  • 避免在 header 中使用中文，或者使用 encodeURIComponent 进行编码，否则在百度小程序报错。（来自：快狗打车前端团队 ）
  • 网络请求的 超时时间 可以统一在 manifest.json 中配置 networkTimeout。
  • H5 端本地调试需注意跨域问题，参考：调试跨域问题解决方案
  • 注意小程序端不支持自动保持 cookie，服务器应避免验证 cookie。如果服务器无法修改，也可以使用一些模拟手段，比如这样的工具https://github.com/charleslo1/weapp-cookie可以请求时带上 cookie 并将响应的 cookie 保存在本地。
  • H5端 cookie 受跨域限制（和平时开发网站时一样），旧版的 uni.request 未支持 withCredentials 配置，可以直接使用 xhr 对象或者其他类库。

五、路由和页面跳转 ​

2.1 uni.navigateTo(OBJECT) ​

uni.navigateTo(OBJECT) | uni-app官网 (dcloud.net.cn)

保留当前页面，跳转到应用内的某个页面，使用uni.navigateBack可以返回到原页面。

参数类型必填默认值说明平台差异说明
urlString是需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，path为下一个页面的路径，下一个页面的onLoad函数可得到传递的参数
animationTypeString否pop-in窗口显示的动画效果，详见：窗口动画App
animationDurationNumber否300窗口动画持续时间，单位为 msApp
eventsObject否页面间通信接口，用于监听被打开页面发送到当前页面的数据。2.8.9+ 开始支持。
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

示例

js
//在起始页面跳转到test.vue页面并传递参数
uni.navigateTo({
	url: 'pages/test?id=1&name=uniapp'
});
// 在test.vue页面接受参数
export default {
	onLoad: function (option) { //option为object类型，会序列化上个页面传递的参数
		console.log(option.id); //打印出上个页面传递的参数。
		console.log(option.name); //打印出上个页面传递的参数。
	}
}

// 在起始页面跳转到test.vue页面，并监听test.vue发送过来的事件数据
uni.navigateTo({
  url: 'pages/test?id=1',
  events: {
      // 为指定事件添加一个监听器，获取被打开页面传送到当前页面的数据
    acceptDataFromOpenedPage: function(data) {
      console.log(data)
    },
    someEvent: function(data) {
      console.log(data)
    }
    ...
  },
  success: function(res) {
    // 通过eventChannel向被打开页面传送数据
    res.eventChannel.emit('acceptDataFromOpenerPage', { data: 'data from starter page' })
  }
})

// 在test.vue页面，向起始页通过事件传递数据
onLoad: function(option) {
  const eventChannel = this.getOpenerEventChannel();
  eventChannel.emit('acceptDataFromOpenedPage', {data: 'data from test page'});
  eventChannel.emit('someEvent', {data: 'data from test page for someEvent'});
  // 监听acceptDataFromOpenerPage事件，获取上一页面通过eventChannel传送到当前页面的数据
  eventChannel.on('acceptDataFromOpenerPage', function(data) {
    console.log(data)
  })
}

注意：

  • 页面跳转路径有层级限制，不能无限制跳转新页面
  • 跳转到 tabBar 页面只能使用 switchTab 跳转
  • 路由API的目标页面必须是在pages.json里注册的vue页面。如果想打开web url，在App平台可以使用 plus.runtime.openURL 或web-view组件；H5平台使用 window.open；小程序平台使用web-view组件（url需在小程序的联网白名单中）。在hello uni-app中有个组件ulink.vue已对多端进行封装，可参考。

2.2 uni.redirectTo(OBJECT) ​

关闭当前页面，跳转到应用内的某个页面。

OBJECT参数说明

参数类型必填说明
urlString是需要跳转的应用内非 tabBar 的页面的路径，路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

示例

js
uni.redirectTo({
    url: 'test?id=1'
});

注意：

  • 跳转到 tabBar 页面只能使用 switchTab 跳转

2.3 uni.reLaunch(OBJECT) ​

关闭所有页面，打开到应用内的某个页面。

注意： 如果调用了 uni.preloadPage(OBJECT) 不会关闭，仅触发生命周期 onHide

OBJECT参数说明

参数类型必填说明
urlString是需要跳转的应用内页面路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，如果跳转的页面路径是 tabBar 页面则不能带参数
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

示例

js
uni.reLaunch({
	url: 'test?id=1'
});
export default {
	onLoad: function (option) {
		console.log(option.id);
	}
}

Tips：

  • H5端调用uni.reLaunch之后之前页面栈会销毁，但是无法清空浏览器之前的历史记录，此时navigateBack不能返回，如果存在历史记录的话点击浏览器的返回按钮或者调用history.back()仍然可以导航到浏览器的其他历史记录。

2.4 uni.switchTab(OBJECT) ​

跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。

注意： 如果调用了 uni.preloadPage(OBJECT)不会关闭，仅触发生命周期 onHide

OBJECT参数说明

参数类型必填说明
urlString是需要跳转的 tabBar 页面的路径（需在 pages.json 的 tabBar 字段定义的页面），路径后不能带参数
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

示例

pages.json

json
{
  "tabBar": {
    "list": [{
      "pagePath": "pages/index/index",
      "text": "首页"
    },{
      "pagePath": "pages/other/other",
      "text": "其他"
    }]
  }
}

other.vue

js
uni.switchTab({
	url: '/pages/index/index'
});

2.5 uni.navigateBack(OBJECT) ​

关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层。

OBJECT参数说明

参数类型必填默认值说明平台差异说明
deltaNumber否1返回的页面数，如果 delta 大于现有页面数，则返回到首页。
animationTypeString否pop-out窗口关闭的动画效果，详见：窗口动画App
animationDurationNumber否300窗口关闭动画的持续时间，单位为 msApp
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

示例

js
// 注意：调用 navigateTo 跳转时，调用该方法的页面会被加入堆栈，而 redirectTo 方法则不会。见下方示例代码

// 此处是A页面
uni.navigateTo({
	url: 'B?id=1'
});

// 此处是B页面
uni.navigateTo({
	url: 'C?id=1'
});

// 在C页面内 navigateBack，将返回A页面
uni.navigateBack({
	delta: 2
});

2.6 EventChannel ​

2.8.9+ 支持 页面间事件通信通道

方法

EventChannel.emit(string eventName, any args) ​

  • 触发一个事件
  • string eventName 事件名称
  • any args 事件参数

EventChannel.off(string eventName, function fn) ​

  • 取消监听一个事件。给出第二个参数时，只取消给出的监听函数，否则取消所有监听函数
  • string eventName 事件名称
  • function fn 事件监听函数
  • 参数 any args 触发事件参数

EventChannel.on(string eventName, function fn) ​

  • 持续监听一个事件
  • string eventName 事件名称
  • function fn 事件监听函数
  • 参数 any args 触发事件参数

EventChannel.once(string eventName, function fn) ​

  • 监听一个事件一次，触发后失效
  • string eventName 事件名称
  • function fn 事件监听函数
  • 参数 any args 触发事件参数

Tips：

  • navigateTo, redirectTo 只能打开非 tabBar 页面。
  • switchTab 只能打开 tabBar 页面。
  • reLaunch 可以打开任意页面。
  • 页面底部的 tabBar 由页面决定，即只要是定义为 tabBar 的页面，底部都有 tabBar。
  • 不能在 App.vue 里面进行页面跳转。
  • H5端页面刷新之后页面栈会消失，此时navigateBack不能返回，如果一定要返回可以使用history.back()导航到浏览器的其他历史记录。

参考事项

  • 页面路由拦截和管理，插件市场有很多封装好的工具类，搜索路由

六、数据缓存 ​

1. uni.setStorageSync(KEY,DATA) ​

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

参数说明

参数类型必填说明
keyString是本地缓存中的指定的 key
dataAny是需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象
js
try {
	uni.setStorageSync('storage_key', 'hello');
} catch (e) {
	// error
}

注意

  • uni-、uni_、dcloud-、dcloud_为前缀的key，为系统保留关键前缀。如uni_deviceId、uni_id_token，请开发者为key命名时避开这些前缀。

2. uni.getStorageSync(KEY) ​

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

参数说明

参数类型必填说明
keyString是本地缓存中的指定的 key

示例

js
try {
	const value = uni.getStorageSync('storage_key');
	if (value) {
		console.log(value);
	}
} catch (e) {
	// error
}

3. uni.removeStorageSync(KEY) ​

从本地缓存中同步移除指定 key。

参数说明

参数名类型必填说明
keyString是本地缓存中的指定的 key

示例

js
try {
	uni.removeStorageSync('storage_key');
} catch (e) {
	// error
}

4. uni.clearStorageSync() ​

同步清理本地数据缓存。

示例

js
try {
	uni.clearStorageSync();
} catch (e) {
	// error
}

注意

uni-app的Storage在不同端的实现不同：

  • H5端为localStorage，浏览器限制5M大小，是缓存概念，可能会被清理
  • App端为原生的plus.storage，无大小限制，不是缓存，是持久化的
  • 各个小程序端为其自带的storage api，数据存储生命周期跟小程序本身一致，即除用户主动删除或超过一定时间被自动清理，否则数据都一直可用。
  • 微信小程序单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。

七、界面 ​

1. 交互反馈 ​

1.1 uni.showToast(OBJECT) ​

uni.showToast(OBJECT) | uni-app官网 (dcloud.net.cn)

作用：显示消息提示框。

OBJECT参数说明

参数类型必填说明平台差异说明
titleString是提示的内容，长度与 icon 取值有关。
iconString否图标，有效值详见下方说明。
imageString否自定义图标的本地路径（app端暂不支持gif）App、H5、微信小程序、百度小程序
maskBoolean否是否显示透明蒙层，防止触摸穿透，默认：falseApp、微信小程序
durationNumber否提示的延迟时间，单位毫秒，默认：1500
positionString否纯文本轻提示显示位置，填写有效值后只有 title 属性生效，且不支持通过 uni.hideToast 隐藏。有效值详见下方说明。App
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

icon 值说明

值说明平台差异说明
success显示成功图标，此时 title 文本在小程序平台最多显示 7 个汉字长度。支付宝小程序无长度无限制
error显示错误图标，此时 title 文本在小程序平台最多显示 7 个汉字长度。支付宝小程序、快手小程序、字节小程序、百度小程序、京东小程序、QQ小程序不支持
fail显示错误图标，此时 title 文本无长度显示。支付宝小程序、字节小程序
exception显示异常图标。此时 title 文本无长度显示。支付宝小程序
loading显示加载图标，此时 title 文本在小程序平台最多显示 7 个汉字长度。支付宝小程序不支持
none不显示图标，此时 title 文本在小程序最多可显示两行，App仅支持单行显示。

示例

js
uni.showToast({
	title: '标题',
	duration: 2000
});

position 值说明（仅App生效）

值说明
top居上显示
center居中显示
bottom居底显示

1.2 uni.hideToast() ​

作用：隐藏消息提示框。

示例

js
uni.hideToast();

1.3 uni.showLoading(OBJECT) ​

作用：显示 loading 提示框, 需主动调用 uni.hideLoading 才能关闭提示框。

OBJECT参数说明

参数类型必填说明平台差异说明
titleString是提示的文字内容，显示在loading的下方
maskBoolean否是否显示透明蒙层，防止触摸穿透，默认：falseH5、App、微信小程序、百度小程序
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

示例

js
uni.showLoading({
	title: '加载中'
});

1.4 uni.hideLoading() ​

作用：隐藏 loading 提示框。

示例

js
uni.showLoading({
	title: '加载中'
});

setTimeout(function () {
	uni.hideLoading();
}, 2000);

1.5 uni.showModal(OBJECT) ​

uni.showToast(OBJECT) | uni-app官网 (dcloud.net.cn)

作用：显示模态弹窗，可以只有一个确定按钮，也可以同时有确定和取消按钮。类似于一个API整合了 html 中：alert、confirm。

OBJECT参数说明

参数类型必填说明平台差异说明
titleString否提示的标题
contentString否提示的内容
showCancelBoolean否是否显示取消按钮，默认为 true
cancelTextString否取消按钮的文字，默认为"取消"
cancelColorHexColor否取消按钮的文字颜色，默认为"#000000"H5、微信小程序、百度小程序、字节小程序（2.62.0+）
confirmTextString否确定按钮的文字，默认为"确定"
confirmColorHexColor否确定按钮的文字颜色，H5平台默认为"#007aff"，微信小程序平台默认为"#576B95"，百度小程序平台默认为"#3c76ff"H5、微信小程序、百度小程序、字节小程序（2.62.0+）
editableBoolean否是否显示输入框H5 (3.2.10+)、App (3.2.10+)、微信小程序 (2.17.1+)、字节小程序（2.62.0+）
placeholderTextString否显示输入框时的提示文本H5 (3.2.10+)、App (3.2.10+)、微信小程序 (2.17.1+)、字节小程序（2.62.0+）
successFunction否接口调用成功的回调函数
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数说明

参数类型说明平台差异说明
confirmBoolean为 true 时，表示用户点击了确定按钮
cancelBoolean为 true 时，表示用户点击了取消（用于 Android 系统区分点击蒙层关闭还是点击取消按钮关闭）
contentStringeditable 为 true 时，用户输入的文本H5 (3.2.10+)、App (3.2.10+)、微信小程序 (2.17.1+)、字节小程序（2.62.0+）

示例

js
uni.showModal({
	title: '提示',
	content: '这是一个模态弹窗',
	success: function (res) {
		if (res.confirm) {
			console.log('用户点击确定');
		} else if (res.cancel) {
			console.log('用户点击取消');
		}
	}
});

1.6 uni.showActionSheet(OBJECT) ​

uni.showToast(OBJECT) | uni-app官网 (dcloud.net.cn)

作用：从底部向上弹出操作菜单

OBJECT参数说明

参数类型必填说明平台差异说明
titleString否菜单标题App、H5、支付宝小程序、钉钉小程序、微信小程序 3.4.5+（仅真机有效）
alertTextString否警示文案（同菜单标题）微信小程序（仅真机有效）
itemListArray<String>是按钮的文字数组微信、百度、字节跳动小程序数组长度最大为6个
itemColorHexColor否按钮的文字颜色，字符串格式，默认为"#000000"App-iOS、飞书小程序不支持
popoverObject否大屏设备弹出原生选择按钮框的指示区域，默认居中显示App-iPad（2.6.6+）、H5（2.9.2）
successFunction否接口调用成功的回调函数，详见返回参数说明
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

popover 值说明（仅App生效）

值类型说明
topNumber指示区域坐标，使用原生 navigationBar 时一般需要加上 navigationBar 的高度
leftNumber指示区域坐标
widthNumber指示区域宽度
heightNumber指示区域高度

success返回参数说明

参数类型说明
tapIndexNumber用户点击的按钮，从上到下的顺序，从0开始

示例

js
uni.showActionSheet({
	itemList: ['A', 'B', 'C'],
	success: function (res) {
		console.log('选中了第' + (res.tapIndex + 1) + '个按钮');
	},
	fail: function (res) {
		console.log(res.errMsg);
	}
});

2. 下拉刷新 ​

2.1 基本配置 ​

属性类型默认值描述平台差异说明
backgroundColorHexColor#ffffff下拉显示出来的窗口的背景色微信小程序
backgroundTextStyleStringdark下拉 loading 的样式，仅支持 dark / light微信小程序
enablePullDownRefreshBooleanfalse是否开启下拉刷新，详见页面生命周期。

json
{
    "enablePullDownRefresh": true,
    "backgroundColor": "#bfa",
    "backgroundTextStyle": "dark"
}

网页页面显示如下：

小程序页面如下：

onPullDownRefresh

在 js 中定义 onPullDownRefresh 处理函数（和onLoad等生命周期函数同级），监听该页面用户下拉刷新事件。

  • 需要在 pages.json 里，找到的当前页面的pages节点，并在 style 选项中开启 enablePullDownRefresh。
  • 当处理完数据刷新后，uni.stopPullDownRefresh 可以停止当前页面的下拉刷新。

2.2 uni.startPullDownRefresh ​

开始下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。

OBJECT 参数说明

参数名类型必填说明
successFunction否接口调用成功的回调
failFunction否接口调用失败的回调函数
completeFunction否接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数类型说明
errMsgString接口调用结果

2.3 uni.stopPullDownRefresh ​

停止当前页面下拉刷新。

示例

第一步：开启下拉刷新。需要在 pages.json 里，找到的当前页面的pages节点，并在 style 选项中开启 enablePullDownRefresh。

第二步：onPullDownRefresh 处理函数（和onLoad等生命周期函数同级），该函数的作用就是用来监听该页面用户下拉刷新事件。

第三步：对应的停止uni.stopPullDownRefresh() 和 开始uni.startPullDownRefresh(OBJECT)下拉刷新的函数。

pages.json

json
{
    "pages": [
        {
        	"path": "pages/index/index",
        	"style": {
        		"navigationBarTitleText": "uni-app",
        		"enablePullDownRefresh": true
        	}
        }
    ],
    "globalStyle": {
    	"navigationBarTextStyle": "white",
    	"navigationBarBackgroundColor": "#0faeff",
    	"backgroundColor": "#fbf9fe"
    }
}

index.vue

vue
// 仅做示例，实际开发中延时根据需求来使用。
export default {
	data() {
		return {
			text: 'uni-app'
		}
	},
	onLoad: function (options) {
		setTimeout(function () {
			console.log('start pulldown');
		}, 1000);
		uni.startPullDownRefresh();
	},
    //一旦触发下拉刷新就会执行下面方法。
	onPullDownRefresh() {
		console.log('refresh');
		setTimeout(function () {
			uni.stopPullDownRefresh();
		}, 1000);
        //上面虽然睡眠了，但是依然会继续执行下面的代码。
		console.log('验证代码继续执行')
	}
}

注意

  • 支付宝小程序startPullDownRefresh在开发者工具里会提示暂未开放，请勿使用
  • 支付宝小程序startPullDownRefresh请使用真机调试（非真机预览）
  • 后续支付宝小程序开发工具更新可能会有所修改

八、页面和窗体 ​

1. 页面 ​

1.1 getCurrentPages() ​

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

注意：

  • getCurrentPages()仅用于展示页面栈的情况，请勿修改页面栈，以免造成页面状态错误。
  • 不要在 App.onLaunch 的时候调用 getCurrentPages()，此时page 还没有生成。(要在方法里或者onshow里写，将此页面存入栈空间)

每个页面实例的方法属性列表：

方法描述平台说明
page.$getAppWebview()获取当前页面的webview对象实例App
page.route获取当前页面的路由

熟悉页面栈后才能更好的使用getCurrentPages()，下面将列举几种常用的使用场景： 1.利用页面栈的长度 例如：进入小程序非默认首页时，需要提供返回首页的按钮或者执行其它事件

js
onShow() {
    let pages = getCurrentPages(); //当前页面栈
    if (pages.length == 1) {
        console.log(pages.$getAppWebview())
        //todo
    }
},

2、跨页面赋值

js
let pages = getCurrentPages();//当前页面栈
let prevPage = pages[pages.length - 2];//上一页面
//直接给上移页面赋值
prevPage.list = [...];

3、页面跳转后自动刷新

js
//举例
uni.switchTab({
    url: '../index/index',
    success: function (e) {
        var page = getCurrentPages().pop(); //当前页面
        if (page == undefined || page == null) return;
        page.onLoad(); //或者其它操作
    }
})

4、获取当前页面相关信息

js
let pages = getCurrentPages(); //当前页面栈
//当前页面为页面栈的最后一个元素
let prevPage = pages[pages.length - 1];//当前页面
// or
// pop() 方法用于删除并返回数组的最后一个元素
let prevPage = pages.pop();//当前页面

console.log( prevPage.route) //举例：输出为‘pages/index/index

1.2 getApp() ​

getApp() 函数用于获取当前应用实例，一般用于获取globalData 。

实例

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

注意：

  • 不要在定义于 App() 内的函数中，或调用 App 前调用 getApp() ，可以通过 this.$scope 获取对应的app实例
  • 通过 getApp() 获取实例之后，不要私自调用生命周期函数。
  • 当在首页nvue中使用getApp()不一定可以获取真正的App对象。对此提供了const app = getApp({allowDefault: true})用来获取原始的App对象，可以用来在首页对globalData等初始化

2. 页面通讯 ​

2.1 uni.$emit(eventName,OBJECT) ​

触发全局的自定义事件，附加参数都会传给监听器回调函数。

属性类型描述
eventNameString事件名
OBJECTObject触发事件携带的附加参数

代码示例

js
uni.$emit('update',{msg:'页面更新'})

复制代码

2.2 uni.$on(eventName,callback) ​

监听全局的自定义事件，事件由 uni.$emit 触发，回调函数会接收事件触发函数的传入参数。

属性类型描述
eventNameString事件名
callbackFunction事件的回调函数

代码示例

js
uni.$on('update',function(data){
    console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
})

复制代码

2.3 uni.$once(eventName,callback) ​

监听全局的自定义事件，事件由 uni.$emit 触发，但仅触发一次，在第一次触发之后移除该监听器。

属性类型描述
eventNameString事件名
callbackFunction事件的回调函数

代码示例

js
uni.$once('update',function(data){
    console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
})

复制代码

2.3 uni.$off([eventName, callback]) ​

移除全局自定义事件监听器。

属性类型描述
eventNameArray＜String＞事件名
callbackFunction事件的回调函数

Tips

  • 如果uni.$off没有传入参数，则移除App级别的所有事件监听器；
  • 如果只提供了事件名（eventName），则移除该事件名对应的所有监听器；
  • 如果同时提供了事件与回调，则只移除这个事件回调的监听器；
  • 提供的回调必须跟$on的回调为同一个才能移除这个回调的监听器；

代码示例

vue
list.vue
<template>
	<view>
		<button type="default" @click="goTestPage">uniApi跳转到测试</button>
	</view>
</template>

<script>
	export default {
		methods: {
			goTestPage() {
				uni.navigateTo({
					url: "/pages/test/test"
				}).then(res => {
					console.log(res);
					uni.$emit('cc', {
						a: "aa",
						b: "bb"
					})

				})
			}
		}
	}
</script>
test.vue
export default {
    onLoad() {
        uni.$on("cc", function(data) {
            console.log(data);
        });
    },
    onUnload() {
        // 移除监听事件  
        uni.$off('cc');
    }
}

注意事项

  • uni.emit、uni.on 、 uni.once、uni.off 触发的事件都是 App 全局级别的，跨任意组件，页面，nvue，vue 等
  • 使用时，注意及时销毁事件监听，比如，页面 onLoad 里边 uni.on注册监听，onUnload里边uni.off 移除，或者一次性的事件，直接使用 uni.$once 监听
  • 注意 uni.on定义完成后才能接收到uni.emit 传递的数据

九、uniapp生命周期 ​

生命周期的概念：一个对象从创建、运行、销毁的整个过程被成为生命周期。

生命周期函数：在生命周期中每个阶段会伴随着每一个函数的触发，这些函数被称为生命周期函数。

1.应用生命周期 ​

uni-app官网 (dcloud.net.cn)

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

函数名说明
onLaunch当uni-app 初始化完成时触发（全局只触发一次）
onShow当 uni-app 启动，或从后台进入前台显示
onHide当 uni-app 从前台进入后台
onError当 uni-app 报错时触发

示例代码

vue
<script>
	// 只能在App.vue里监听应用的生命周期
	export default {
		onLaunch: function() {
			console.log('App Launch')
		},
		onShow: function() {
			console.log('App Show')
		},
		onHide: function() {
			console.log('App Hide')
		},
        onError: function(err) {
        	console.log('App Err', err)
		}
	}
</script>

<style>
	/*每个页面公共css */
</style>

代码分析：

  • 第一次加载页面时会调用onLaunch ，onShow 打印App Launch，App Show
  • 当你在浏览器离开页面，去查看其它页面，或者其它应用会触发onHide，在回来查看该页面时触发onShow ，打印App Hide，App Show
  • 我们手动把onShow方法里面的console.log(‘App Show’) 改为consol.log(‘App Show’) 去掉一个e字母，这样会导致报错，这个时候我们onError方法就可以监听到错误

注意

2.页面生命周期 ​

页面简介 | uni-app官网 (dcloud.net.cn)

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

函数名说明平台差异说明最低版本
onLoad监听页面加载，其参数为上个页面传递的数据，参数类型为 Object（用于页面传参），参考示例
onShow监听页面显示。页面每次出现在屏幕上都触发，包括从下级页面点返回露出当前页面
onReady监听页面初次渲染完成。注意如果渲染速度快，会在页面进入动画完成前触发
onHide监听页面隐藏
onUnload监听页面卸载

index.vue页面里面定义的页面生命周期函数如下：

js
export default {
    data() {
        return {
            title: 'Hello'
        }
    },
    onLoad(option) {
        console.log('页面加载了', option);
    },
    onShow() {
        console.log('页面显示了');
    },
    onReady() {
        console.log('页面初次渲染完成了');
    },
    onHide() {
        console.log('页面隐藏了');
    },
    onUpload() {
        console.log('页面卸载了');
    },
    methods: {

    }
}

代码分析：

  • 第一次加载首页，触发onLoad，onShow，onReady方法，依次打印页面加载了，页面显示了，页面初次渲染完成了
  • 当你在浏览器离开页面，去查看其它页面，或者其它应用，会触发onHide方法，打印页面隐藏了，在回来查看该页面时触发onShow方法，打印页面显示了。可以发现印页面加载了，页面初次渲染完成了都不在打印，证明onLoad，onReady方法只触发一次，而onShow，onHide方法多次触发

当我们取tabbr底部栏从首页切换到其它页面，会触发onHide方法，打印页面隐藏了。再次会到首页，触发onShow方法，打印页面显示了

tabbar的提示：

tabbar 切换第一次加载时可能渲染不及时，可以在每个tabbar页面的onLoad生命周期里先弹出一个等待雪花（hello uni-app使用了此方式）
tabbar 的页面展现过一次后就保留在内存中，再次切换 tabbar 页面，只会触发每个页面的onShow，不会再触发onLoad

3.组件生命周期 ​

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

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

MIT Licensed

Copyright © 2024-present xarzhi