Weapp-vite

Appearance

Wevu Router API ​

本页对应 wevu/router 的公开导出，以及 createRouter() 返回实例的公共契约。Wevu Router 对齐 Vue Router 的主要使用心智，但最终导航仍受小程序页面栈、tabBar 和宿主 API 约束。

ts
import { createRouter, useRoute, useRouter } from 'wevu/router'

Router 入口 ​

createRouter() ​

类型签名： typeof import('wevu/router')['createRouter']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 不选择 Web History 实现；配置重点是路由记录、tabBar、params 策略和宿主导航失败处理。

示例： 见 本组示例。

创建并注册默认 Router。选项支持路由记录、tabBar 路径、params 模式、重定向上限、query codec 和导航失败策略。

useRouter() ​

类型签名： typeof import('wevu/router')['useRouter']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

读取当前已创建的 Router；调用前必须先执行 createRouter()。

useRoute() ​

类型签名： typeof import('wevu/router')['useRoute']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 返回值随小程序页面生命周期和导航完成事件同步，不依赖浏览器 URL/history 监听。

示例： 见 本组示例。

在 setup() 同步阶段读取只读的当前路由状态，并随页面生命周期和导航完成事件更新。

本组示例 ​

App 初始化阶段只创建一个 Router，页面在同步 setup 中读取它。

ts
import { createRouter, useRoute, useRouter } from 'wevu/router'

createRouter({
  routes: [{ name: 'home', path: '/pages/home/index' }],
  tabBarEntries: ['/pages/home/index'],
})

const router = useRouter()
const route = useRoute()
console.log(router.currentRoute, route.fullPath)

原生 Router ​

useNativeRouter() ​

类型签名： typeof import('wevu/router')['useNativeRouter']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

示例： 见 本组示例。

获取当前组件路径语义的原生 Router，直接暴露小程序导航能力。

useNativePageRouter() ​

类型签名： typeof import('wevu/router')['useNativePageRouter']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

示例： 见 本组示例。

获取当前页面路径语义的原生 Router，适合页面级相对导航。

本组示例 ​

原生 Router 适合直接调用宿主能力；高层业务导航优先使用 wevu/router。

ts
import { useNativePageRouter, useNativeRouter } from 'wevu/router'

const componentRouter = useNativeRouter()
const pageRouter = useNativePageRouter()

componentRouter.navigateTo({ url: '../detail/index?id=42' })
pageRouter.redirectTo({ url: '/pages/home/index' })

解析与导航失败 ​

resolveRouteLocation() ​

类型签名： typeof import('wevu/router')['resolveRouteLocation']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

示例： 见 本组示例。

将字符串或位置对象解析为标准路由位置，可传入当前路径处理相对地址。

parseQuery() ​

类型签名： typeof import('wevu/router')['parseQuery']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

示例： 见 本组示例。

把 query 字符串解析为 LocationQuery。

stringifyQuery() ​

类型签名： typeof import('wevu/router')['stringifyQuery']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

示例： 见 本组示例。

把 LocationQueryRaw 序列化为 query 字符串。

createNavigationFailure() ​

类型签名： typeof import('wevu/router')['createNavigationFailure']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

示例： 见 本组示例。

创建带失败类型、目标位置、来源位置和原始原因的导航失败对象。

isNavigationFailure() ​

类型签名： typeof import('wevu/router')['isNavigationFailure']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

判断异常或导航结果是否为 Wevu 导航失败，也可按失败类型过滤。

类型签名： typeof import('wevu/router')['NavigationFailureType']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

运行时失败类型常量，包含 unknown、aborted、cancelled 和 duplicated。

本组示例 ​

解析与失败判断可以脱离实际跳转，用于日志、预览和统一错误处理。

ts
import { isNavigationFailure, parseQuery, resolveRouteLocation, stringifyQuery } from 'wevu/router'

const query = parseQuery('?tag=wevu&page=2')
const search = stringifyQuery({ tag: 'wevu', page: 2 })
const target = resolveRouteLocation({ path: '/pages/list/index', query })

try {
  await router.push(target)
}
catch (error) {
  if (isNavigationFailure(error)) {
    report(error.type)
  }
}
console.log(search)

Router 实例 ​

router.nativeRouter ​

类型签名： RouterNavigation['nativeRouter']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

Router 内部使用的原生 SetupContextRouter。

router.options ​

类型签名： RouterNavigation['options']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

创建 Router 时使用的只读、规范化选项快照。

router.currentRoute ​

类型签名： RouterNavigation['currentRoute']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

当前只读路由位置，包含 path、query、params、matched 和 redirectedFrom 等信息。

router.install() ​

类型签名： RouterNavigation['install']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： Vue Router 安装组件与全局属性；Wevu 只注册默认 Router，并在宿主对象支持时写入 $router。

示例： 见 本组示例。

注册当前 Router，并在 App 支持 globalProperties 时写入 $router。

router.resolve() ​

类型签名： RouterNavigation['resolve']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

基于当前路由和 Router 配置解析目标位置，不执行实际跳转。

router.isReady() ​

类型签名： RouterNavigation['isReady']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

返回 Router 就绪 Promise；当前小程序实现创建后即可就绪。

本组示例 ​

先 resolve() 检查目标，再根据当前页面栈决定是否执行导航。

ts
import { useRouter } from 'wevu/router'

const router = useRouter()
await router.isReady()

const target = router.resolve({ name: 'detail', params: { id: 42 } })
console.log(router.options, router.currentRoute, target.href)
router.install()

导航方法 ​

router.push() ​

类型签名： RouterNavigation['push']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

执行前进导航，通常映射到 navigateTo，也会处理 tabBar、守卫、重定向和失败分类。

router.replace() ​

类型签名： RouterNavigation['replace']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

替换当前页面，通常映射到 redirectTo。

router.back() ​

类型签名： RouterNavigation['back']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 返回操作受当前小程序页面栈深度限制，不存在浏览器跨站 history。

示例： 见 本组示例。

按指定层数返回；默认返回一层。

router.go() ​

类型签名： RouterNavigation['go']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： Vue Router 可正向或反向移动 history；Wevu 只能把负数映射为 navigateBack，正数无法前进。

示例： 见 本组示例。

使用相对层数操作页面栈；小程序环境只支持可映射的返回语义。

router.forward() ​

类型签名： RouterNavigation['forward']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 浏览器可沿 history 前进；小程序没有 forward 栈，该方法会返回 aborted 导航失败。

示例： 见 本组示例。

保留 Vue Router 心智的前进入口；小程序没有浏览器 forward 栈，通常返回 aborted 失败。

本组示例 ​

小程序没有浏览器 forward 栈，正向导航和返回需要使用不同方法。

ts
import { useRouter } from 'wevu/router'

const router = useRouter()
await router.push({ name: 'detail', params: { id: 42 } })
await router.replace('/pages/detail/index?id=43')
await router.back()

// go(-2) 可映射为 navigateBack；forward() 会返回 aborted 失败。
await router.go(-2)

动态路由 ​

router.hasRoute() ​

类型签名： RouterNavigation['hasRoute']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

按名称判断路由记录是否存在。

router.getRoutes() ​

类型签名： RouterNavigation['getRoutes']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

返回当前规范化路由记录列表。

router.addRoute() ​

类型签名： RouterNavigation['addRoute']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

新增顶层或子路由记录，返回移除该记录的函数。

router.removeRoute() ​

类型签名： RouterNavigation['removeRoute']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

按名称移除路由记录。

router.clearRoutes() ​

类型签名： RouterNavigation['clearRoutes']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

清空动态路由注册表。

本组示例 ​

动态注册返回清理函数，组件卸载时应主动移除临时路由。

ts
import { onUnmounted } from 'wevu'
import { useRouter } from 'wevu/router'

const router = useRouter()
const remove = router.addRoute({ name: 'preview', path: '/pages/preview/index' })

console.log(router.hasRoute('preview'), router.getRoutes())
onUnmounted(remove)

导航守卫 ​

router.beforeEach() ​

类型签名： RouterNavigation['beforeEach']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

注册全局前置守卫，返回取消注册函数。

router.beforeResolve() ​

类型签名： RouterNavigation['beforeResolve']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

注册导航确认前守卫，运行在 beforeEach 和路由记录 beforeEnter 之后。

router.afterEach() ​

类型签名： RouterNavigation['afterEach']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

注册导航完成回调，可读取失败对象和小程序导航上下文。

router.onError() ​

类型签名： RouterNavigation['onError']

运行时说明： 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

Vue Router 差异： 调用形式接近 Vue Router，但导航最终映射到 navigateTo、redirectTo、switchTab、reLaunch 或 navigateBack，受页面栈和 tabBar 约束。

示例： 见 本组示例。

注册异常型导航失败处理器，返回取消注册函数。

本组示例 ​

守卫按 beforeEach、路由 beforeEnter、beforeResolve 的顺序运行。

ts
import { onUnmounted } from 'wevu'
import { useRouter } from 'wevu/router'

const router = useRouter()
const removeGuard = router.beforeEach((to) => {
  if (to?.meta?.requiresLogin) {
    return { name: 'login' }
  }
})
const removeAfter = router.afterEach((to, from, failure) => report({ to, from, failure }))
const removeError = router.onError((error, context) => report({ error, context }))

onUnmounted(() => {
  removeGuard()
  removeAfter()
  removeError()
})

兼容边界 ​

  • forward()、hash-only 导航和页面栈行为受小程序宿主限制。
  • useRoute() 必须在 setup() 同步阶段调用，不能放在 await 之后。
  • useNativeRouter() / useNativePageRouter() 直接面向宿主能力；高阶导航优先使用 createRouter() / useRouter()。
  • 所有公开类型见 Wevu Router 类型参考。
  • 详细示例和迁移建议见 wevu/router 使用指南。

Released under the MIT License.

Copyright © 2024-present sonofmagic