路由 Router

路由 API 管理小程序的页面导航栈。所有页面路径基于 app.json 中 pages 数组定义。

在线试用

navigateTonavigateBackredirectToreLaunch

路由 API 试用

点击按钮触发路由调用，控制台显示 SDK 日志

Vue

<script setup>
import woo from 'mini-sdk'

async function goDetail() {
  await woo.navigateTo({
    url: '/pages/detail/index',
    params: { id: 42 },
  })
}

async function goBack() {
  await woo.navigateBack({ delta: 1 })
}
</script>

<template>
  <button @click="goDetail">打开详情</button>
  <button @click="goBack">返回</button>
</template>

React

import woo from 'mini-sdk'

function MyPage() {
  async function goDetail() {
    await woo.navigateTo({
      url: '/pages/detail/index',
      params: { id: 42 },
    })
  }

  async function goBack() {
    await woo.navigateBack({ delta: 1 })
  }

  return (
    <>
      <button onClick={goDetail}>打开详情</button>
      <button onClick={goBack}>返回</button>
    </>
  )
}

导入

import woo from 'mini-sdk'
// 或
import { router } from 'mini-sdk'

API 列表

速查

页面底部有完整的 API 速查表，快速定位方法签名。

navigateTo

打开新页面，压入导航栈。

woo.navigateTo(options: string | NavigateToOptions): Promise<void>

参数：

字段	类型	必填	说明
url	string	是	页面路径，如 "/pages/detail/index"
params	Record<string, string | number>	否	URL 查询参数，自动拼接
onBack	(data: unknown) => void	否	子页面返回时携带数据的回调

示例：

// 简写模式
await woo.navigateTo('/pages/detail/index')

// 携带参数
await woo.navigateTo({
  url: '/pages/detail/index',
  params: { id: 123, type: 'article' },
})
// 实际跳转：/pages/detail/index?id=123&type=article

// 接收子页面返回数据
await woo.navigateTo({
  url: '/pages/edit/index',
  onBack(data) {
    console.log('子页面返回数据：', data)
  },
})

onBack 机制

onBack 通过 LIFO 栈管理，支持多次 navigateTo 到同一页面而互不干扰。当 reLaunch / navigateToTab 重置路由栈时，所有挂起的 onBack 回调自动清除。

---

navigateBack

返回上一页或多级页面。

woo.navigateBack(options?: NavigateBackOptions): Promise<void>

参数：

字段	类型	必填	默认值	说明
delta	number	否	1	返回层级数
data	unknown	否	—	携带给上一页的数据

示例：

// 返回上一页
await woo.navigateBack()

// 返回两级并携带数据
await woo.navigateBack({
  delta: 2,
  data: { result: 'success', value: 42 },
})

---

reLaunch

关闭所有页面，打开指定页面（重置导航栈）。

woo.reLaunch(options: string | ReLaunchOptions): Promise<void>

参数：

字段	类型	必填	说明
url	string	是	目标页面路径
params	Record<string, string | number>	否	URL 查询参数

await woo.reLaunch('/pages/index/index')

---

navigateToTab

切换到 TabBar 页面。

woo.navigateToTab(options: string | NavigateToTabOptions): Promise<void>

参数：

字段	类型	必填	说明
url	string	是	TabBar 页面路径
params	Record<string, string | number>	否	URL 查询参数
groupIndex	string	否	Tab 分组索引

await woo.navigateToTab({
  url: '/pages/profile/index',
  groupIndex: '2',
})

---

reLaunchTab

关闭所有页面，切换到指定 TabBar 页面。

woo.reLaunchTab(options: string | ReLaunchTabOptions): Promise<void>

参数与 navigateToTab 相同。

---

getCurrentPages

获取当前页面栈信息。

woo.getCurrentPages(): Promise<PageInfo[]>

返回值：

interface PageInfo {
  route: string  // 页面路径
}

const pages = await woo.getCurrentPages()
console.log('当前页面栈：', pages)
// [{ route: 'pages/index/index' }, { route: 'pages/detail/index' }]

---

getRoute

同步获取当前页面的路径和查询参数。

woo.getRoute(): RouteInfo

返回值：

interface RouteInfo {
  path: string                    // 页面路径（不含前导 /）
  query: Record<string, string>   // 查询参数
}

const { path, query } = woo.getRoute()
console.log(path)   // "pages/detail/index"
console.log(query)  // { id: "123" }

路由模式

• 模拟器：Hash 路由（http://localhost/#/pages/detail/index?id=1）
• Native：Pathname 路由（https://host/pages/detail/index?id=1）

getRoute() 自动兼容两种模式。

类型定义

interface NavigateToOptions {
  url: string
  params?: Record<string, string | number | undefined>
  onBack?: (data: unknown) => void
}

interface NavigateBackOptions {
  delta?: number
  data?: unknown
}

interface ReLaunchOptions {
  url: string
  params?: Record<string, string | number | undefined>
}

interface NavigateToTabOptions {
  url: string
  params?: Record<string, string | number | undefined>
  groupIndex?: string
}

interface ReLaunchTabOptions {
  url: string
  params?: Record<string, string | number | undefined>
  groupIndex?: string
}

interface PageInfo {
  route: string
}

interface RouteInfo {
  path: string
  query: Record<string, string>
}

type RouteParams = Record<string, string | number | undefined>

API 速查表

方法	说明	签名
navigateTo	打开新页面，压入栈	(url | NavigateToOptions) → Promise<void>
redirectTo	关闭当前页，打开新页面	(url | { url }) → Promise<void>
navigateBack	返回上一页	({ delta?, data? }) → Promise<void>
reLaunch	关闭所有页面，打开指定页面	({ url }) → Promise<void>
switchTab	切换到 tabBar 页面	({ url }) → Promise<void>
getCurrentPages	获取当前页面栈	() → PageInfo[]
getRouteParams	获取当前页面路由参数	() → RouteParams