【Uni-App】API笔记 P2

8、路由，跳转

一、保留当前页面并跳转到指定页面

使用uni.navigateBack可以返回到原页面。

uni.navigateTo(OBJECT)

OBJECT参数说明

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

成功回调

object.success 

参数

Object res

属性	类型	说明
eventChannel	EventChannel	和被打开页面进行通信

success : function (res) {
    res.eventChannel
}

跳转代码实例：

//在起始页面跳转到test.vue页面并传递参数
uni.navigateTo({
    url: 'test?id=1&name=uniapp'
});

目标页接参处理：

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

事件通道传递整页数据？

// 2.8.9+ 支持
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: 'test' })
  }
})

// uni.navigateTo 目标页面 pages/test.vue
onLoad: function(option) {
  console.log(option.query)
  const eventChannel = this.getOpenerEventChannel()
  eventChannel.emit('acceptDataFromOpenedPage', {data: 'test'});
  eventChannel.emit('someEvent', {data: 'test'});
  // 监听acceptDataFromOpenerPage事件，获取上一页面通过eventChannel传送到当前页面的数据
  eventChannel.on('acceptDataFromOpenerPage', function(data) {
    console.log(data)
  })
}

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 触发事件参数

参数长度限制

url有长度限制，太长的字符串会传递失败，可改用窗体通信、全局变量，另外参数中出现空格等特殊字符时需要对参数进行编码，如下为使用encodeURIComponent对参数进行编码的示例。

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

目标页面接参：

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

注意事项：

• 页面跳转路径有层级限制，不能无限制跳转新页面
• 跳转到 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已对多端进行封装，可参考

二、重定向

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

uni.redirectTo(OBJECT)

OBJECT参数说明

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

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

注意：tabBar页面只允许使用switchTab跳转

三、重开

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

uni.reLaunch(OBJECT)

OBJECT参数说明

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

原始页：

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

目标页：

export default {
    onLoad: function (option) {
        console.log(option.id);
    }
}

注意事项：

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

四、底部栏页面切换跳转

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

uni.switchTab(OBJECT)

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

OBJECT参数说明

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

全局底部栏配置

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

其他页的底部栏配置

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

五、回退页面

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

uni.navigateBack(OBJECT)

OBJECT参数说明

参数	类型	必填	默认值	说明	平台差异说明
delta	Number	否	1	返回的页面数，如果 delta 大于现有页面数，则返回到首页。
animationType	String	否	pop-out	窗口关闭的动画效果，详见：窗口动画	App
animationDuration	Number	否	300	窗口关闭动画的持续时间，单位为 ms	App

代码实例：

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

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

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

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

Tips：

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

参考事项

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

窗口动画

本API仅App支持。小程序自身不支持自定义动画。H5的窗体动画可使用常规单页动画处理方案，见H5下单页动画示例

窗口的显示/关闭动画效果，支持在 API、组件、pages.json 中配置，优先级为：API = 组件 > pages.json。

API

有效的路由 API

• navigateTo
• navigateBack

uni.navigateTo({
    url: '../test/test',
    animationType: 'pop-in',
    animationDuration: 200
});
uni.navigateBack({
    delta: 1,
    animationType: 'pop-out',
    animationDuration: 200
});

组件

open-type 有效值

• navigateTo
• navigateBack

<navigator animation-type="pop-in" animation-duration="300" url="../test/test">navigator</navigator>
<navigator animation-type="pop-out" animation-duration="300" open-type="navigateBack" >navigator</navigator>

pages.json

pages.json 中配置的是窗口显示的动画

"style": {
    "app-plus": {
        "animationType": "fade-in",
        "animationDuration": 300
    }
}

显示动画与关闭动画，会有默认的对应规则。但是如果通过 API 或组件配置了窗口关闭的动画类型，则不会使用默认的类型。

显示动画	关闭动画	显示动画描述（关闭动画与之相反）
slide-in-right	slide-out-right	新窗体从右侧进入
slide-in-left	slide-out-left	新窗体从左侧进入
slide-in-top	slide-out-top	新窗体从顶部进入
slide-in-bottom	slide-out-bottom	新窗体从底部进入
pop-in	pop-out	新窗体从左侧进入，且老窗体被挤压而出
fade-in	fade-out	新窗体从透明到不透明逐渐显示
zoom-out	zoom-in	新窗体从小到大缩放显示
zoom-fade-out	zoom-fade-in	新窗体从小到大逐渐放大并且从透明到不透明逐渐显示
none	none	无动画

详细的窗口动画说明，请参考：

• 窗口显示的动画：AnimationTypeShow
• 窗口关闭的动画：AnimationTypeClose

注意

• 纯nvue项目（render为native），窗体动画默认进入动画为popin，返回为pop-out。如果想修改动画类型，只能通过uni.navigateTo API修改，在组件或pages.json里配置动画类型无效
• 非纯nvue项目，App端窗体动画，默认进入动画为slider-in-right，默认返回动画为pop-out
• webview 中嵌入 uni-app H5时，使用 uni.webView.navigateTo... 跳转页面

六、提前加载

uni.preloadPage(OBJECT)

预加载页面，是一种性能优化技术。被预载的页面，在打开时速度更快。

平台差异说明

App-nvue	H5	微信小程序	支付宝小程序	百度小程序	字节跳动小程序	QQ小程序
√(2.7.12+)	√(2.7.12+)	x	x	x	x	x

属性	类型	必填	说明
url	string	是	预加载页面url
complete	Function	否	预加载成功完成回调
fail	Function	否	预加载失败回调

H5 平台

预加载 /pages/test/test 对应的js文件，不执行页面预渲染逻辑

uni.preloadPage({url: "/pages/test/test"});

App-nvue 平台

预加载nvue页面 /pages/test/test

uni.preloadPage({url: "/pages/test/test"});

注意事项

1. App平台仅支持预加载 nvue 页面，执行页面预渲染，预载时触发生命周期 onLoad，onReady，不触发 onShow
2. 打开新页面时，url 完全相同（包含参数）时，优先使用预加载页面，触发生命周期 onShow
3. tabbar页面，仅支持预加载尚未显示过的页面，否者返回 fail，提示 already exists
4. 同一时间，相同 url 仅 preloadPage 一次
5. 当同一个预载页面已被打开(在路由栈)，再次打开相同url时，不再使用该预加载页面，而是打开新的非预载页面
6. uni.reLanuch, uni.switchTab, uni.navigateBack(含Android返回键) 切换页面时，预加载页面不会被销毁，仅触发生命周期 onHide
7. 在预载页面使用 uni.redirectTo 时，预加载页面会被销毁，触发生命周期 onUnload

示例

uni.preloadPage({url: "/pages/test/test"}); // 预加载 /pages/test/test 页面（仅触发onLoad，onReady)
uni.navigateTo({url: "/pages/test/test"}); // url匹配，跳转预加载页面（仅触发onShow)
uni.navigateTo({url: "/pages/test/test?a=b"}); // url不匹配，正常打开新页面

HBuilderX 2.7.12+的hello uni-app，在navigator示例和uni ui的日历示例中增加了页面预载示例。

uni.unPreloadPage(OBJECT)

取消预载页面。

1. 仅App-nvue支持
2. 当预载页面未被打开时，使用 unPreloadPage时会销毁该页面，触发生命周期 onUnload
3. 当预载页面已被打开时，使用 unPreloadPage时不销毁该页面，但该预加载页面不再继续存在，会随着路由变化而销毁

9、缓存

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

uni.setStorage(OBJECT)

OBJECT 参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key
data	Any	是	需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例

uni.setStorage({
    key: 'storage_key',
    data: 'hello',
    success: function () {
        console.log('success');
    }
});

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

uni.setStorageSync(KEY,DATA)

参数说明

参数	类型	必填	说明
key	String	是	本地缓存中的指定的 key
data	Any	是	需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象

try {
    uni.setStorageSync('storage_key', 'hello');
} catch (e) {
    // error
}

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

uni.getStorage(OBJECT)

OBJECT 参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key
success	Function	是	接口调用的回调函数，res = {data: key对应的内容}
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
data	Any	key 对应的内容

示例

uni.getStorage({
    key: 'storage_key',
    success: function (res) {
        console.log(res.data);
    }
});

 

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

uni.getStorageSync(KEY)

参数说明

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

示例

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

 

异步获取当前 storage 的相关信息。

uni.getStorageInfo(OBJECT)

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序
HBuilderX 2.0.3+	√	√	√	√

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	是	接口调用的回调函数，详见返回参数说明
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
keys	Array＜String＞	当前 storage 中所有的 key
currentSize	Number	当前占用的空间大小, 单位：kb
limitSize	Number	限制的空间大小, 单位：kb

示例

uni.getStorageInfo({
    success: function (res) {
        console.log(res.keys);
        console.log(res.currentSize);
        console.log(res.limitSize);
    }
});

 

同步获取当前 storage 的相关信息。

uni.getStorageInfoSync()

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序
HBuilderX 2.0.3+	√	√	√	√

示例

try {
    const res = uni.getStorageInfoSync();
    console.log(res.keys);
    console.log(res.currentSize);
    console.log(res.limitSize);
} catch (e) {
    // error
}

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

uni.removeStorage(OBJECT)

OBJECT 参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key
success	Function	是	接口调用的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例

uni.removeStorage({
    key: 'storage_key',
    success: function (res) {
        console.log('success');
    }
});

 

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

uni.removeStorageSync(KEY)

参数说明

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

示例

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

 

清理本地数据缓存。

uni.clearStorage()

同步清理本地数据缓存。

uni.clearStorageSync()

示例

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

注意

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

• H5端为localStorage，浏览器限制5M大小，是缓存概念，可能会被清理
• App端为原生的plus.storage，无大小限制，不是缓存，是持久化的
• 各个小程序端为其自带的storage api，数据存储生命周期跟小程序本身一致，即除用户主动删除或超过一定时间被自动清理，否则数据都一直可用。
• 微信小程序单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。
• 支付宝小程序单条数据转换成字符串后，字符串长度最大200*1024。同一个支付宝用户，同一个小程序缓存总上限为10MB。
• 百度、字节跳动小程序文档未说明大小限制
• 非App平台清空Storage会导致uni.getSystemInfo获取到的deviceId改变

除此之外，其他数据存储方案：

• H5端还支持websql、indexedDB、sessionStorage
• App端还支持SQLite、IO文件等本地存储方案。

从HBuilderX2.6.6+起，App-Android平台对本地storage数据存储进行了性能优化，它的具体优化方式和升级注意事项，详见：https://ask.dcloud.net.cn/article/37071

官方案例代码：

https://github.com/dcloudio/hello-uniapp