当前位置：首页 > news >正文

小程序——路由API

news 2026/3/26 20:02:23

路由API

- 1、wx.switchTab(Object object)
- 2、wx.rewriteRoute(Object object)
- 3、wx.reLaunch(Object object)
- 4、wx.redirectTo(Object object)
- 5、wx.navigateTo(Object object)
- 6、wx.navigateBack(Object object)
- 7、EventChannel
- 8、router.addRouteBuilder(string routeType, function routeBuilder)

1、wx.switchTab(Object object)

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

参数：Object object

属性	类型	默认值	必填
`url`	string	是	需要跳转的 tabBar 页面的路径 (代码包路径)（需在 app.json 的 tabBar 字段定义的页面），路径后不能带参数。
`success`	function	否	接口调用成功的回调函数
`fail`	function	否	接口调用失败的回调函数
`complete`	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

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

wx.switchTab({url:'/index'})

2、wx.rewriteRoute(Object object)

重写正在进行中的路由事件，详见路由重写。

参数：Object object

属性	类型	默认值	必填	说明
`url`	string	是	重写目标页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔，参数键与参数值用 = 相连，不同参数用 & 分隔；如 ‘path?key=value&key2=value2’
`preserveQuery`	boolean	false	否	是否直接保留当前路由事件的参数，默认为 false；开启时，url 里面传入的参数会被丢弃
`success`	function	否	接口调用成功的回调函数
`fail`	function	否	接口调用失败的回调函数
`complete`	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

wx.onBeforeAppRoute(res=>{if(res.path==='/pages/do/not/access/me'){wx.rewriteRoute({url:'/pages/index/index'})}})

3、wx.reLaunch(Object object)

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

参数：Object object

属性	类型	默认值	必填
`success`	function	否	接口调用成功的回调函数
`fail`	function	否	接口调用失败的回调函数
`complete`	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

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

4、wx.redirectTo(Object object)

关闭当前页面，跳转到应用内的某个页面。但是不允许跳转到 tabbar 页面。

参数：Object object

属性	类型	默认值	必填
`url`	string	是	需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔，参数键与参数值用 = 相连，不同参数用 & 分隔；如 ‘path?key=value&key2=value2’
`success`	function	否	接口调用成功的回调函数
`fail`	function	否	接口调用失败的回调函数
`complete`	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

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

5、wx.navigateTo(Object object)

保留当前页面，跳转到应用内的某个页面。但是不能跳到 tabbar 页面。使用 wx.navigateBack 可以返回到原页面。小程序中页面栈最多十层。

属性	类型	默认值	必填
`url`	string	是	需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔，参数键与参数值用 = 相连，不同参数用 & 分隔；如 ‘path?key=value&key2=value2’
`events`	Object	否	页面间通信接口，用于监听被打开页面发送到当前页面的数据。基础库 2.7.3 开始支持。
`routeType`	string	否	2.29.2 自定义路由类型，相关文档自定义路由
`routeConfig`	Object	否	3.4.0 自定义路由配置，相关文档自定义路由
`routeOptions`	Object	否	3.4.0 自定义路由参数，相关文档自定义路由
`withOpenContainer`	Object	是	3.12.2 skyline 下指定路由动画所用OpenContainerContext，相关文档 OpenContainerContext
`success`	function	否	接口调用成功的回调函数
`fail`	function	否	接口调用失败的回调函数
`complete`	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success回调函数：

参数：Object res

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

wx.navigateTo({url:'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'})}})

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

6、wx.navigateBack(Object object)

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

参数：Object object

属性	类型	默认值	必填	说明
`delta`	number	1	否	返回的页面数，如果 delta 大于现有页面数，则返回到页面栈中只剩一个页面为止。
`success`	function	否	接口调用成功的回调函数
`fail`	function	否	接口调用失败的回调函数
`complete`	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

// 注意：调用 navigateTo 跳转时，调用该方法的页面会被加入堆栈，而 redirectTo 方法则不会。见下方示例代码// 此处是A页面wx.navigateTo({url:'B?id=1'})// 此处是B页面wx.navigateTo({url:'C?id=1'})// 在C页面内 navigateBack，将返回A页面wx.navigateBack({delta:2})

7、EventChannel

页面间事件通信通道。

EventChannel.emit(string eventName, any args)
触发一个事件
EventChannel.on(string eventName, EventCallback fn)
持续监听一个事件
EventChannel.once(string eventName, EventCallback fn)
监听一个事件一次，触发后失效
EventChannel.off(string eventName, EventCallback fn)
取消监听一个事件。给出第二个参数时，只取消给出的监听函数，否则取消所有监听函数

8、router.addRouteBuilder(string routeType, function routeBuilder)

添加自定义路由配置。

string routeType：路由类型
function routeBuilder：路由动画定义函数

// 定义自定义效果，从右侧推入constslideRouteBuilder=(customRouteContext)=>{const{primaryAnimation}=customRouteContextconsthandlePrimaryAnimation=()=>{'worklet'consttransX=windowWidth*(1-primaryAnimation.value)return{transform:`translateX(${transX}px)`,}}return{handlePrimaryAnimation}}wx.router.addRouteBuilder('slide',slideRouteBuilder)// 使用自定义路由wx.navigateTo({url:'xxx',routeType:'slide'})