@kinngyo/wx-navigate

微信小程序路由封装。业务侧可以统一调用 to、replace、back 等方法，不需要手动判断目标页面是不是 tabBar 页面。

特性

• 自动识别 tabBar 页面，普通跳转和 tabBar 跳转统一入口
• 支持字符串路径，也支持微信小程序原生路由参数对象
• 支持按页面路径返回历史页面
• 自动处理路径参数、开头 /、.html 后缀
• 提供 TypeScript 类型导出

安装

npm i @kinngyo/wx-navigate

小程序项目安装后，需要在微信开发者工具中执行“工具 -> 构建 npm”。

基础使用

import Navigate from '@kinngyo/wx-navigate'

const navigate = new Navigate()

navigate.to('/pages/index/index')

默认情况下，Navigate 会从小程序运行时的 __wxConfig.tabBar.list 中读取 tabBar 页面配置。

也可以手动传入 tabBar 页面路径：

import Navigate from '@kinngyo/wx-navigate'

const navigate = new Navigate([
    '/pages/index/index',
    '/pages/user/index',
])

跳转页面

to 用于跳转到应用内页面。目标是普通页面时使用 wx.navigateTo，目标是 tabBar 页面时自动改用 wx.switchTab。

navigate.to('/pages/detail/index?id=1')

navigate.to({
    url: '/pages/detail/index?id=1',
    success() {
        console.log('跳转成功')
    },
})

跳转 tabBar 页面时无需手动调用 switchTab：

navigate.to('/pages/index/index')

替换页面

replace 用于关闭当前页面并跳转。目标是普通页面时使用 wx.redirectTo，目标是 tabBar 页面时自动改用 wx.switchTab。

navigate.replace('/pages/login/index')

navigate.replace({
    url: '/pages/login/index',
})

返回页面

back 默认返回上一页：

navigate.back()

传入数字时，按层级返回：

navigate.back(2)

传入页面路径时，会根据 getCurrentPages() 计算返回层级：

navigate.back('/pages/index/index')
navigate.back('/pages/index/index?id=1')
navigate.back('pages/index/index?id=1')

找不到目标页面时，会保持默认行为返回上一页。

也可以直接传微信原生参数对象：

navigate.back({
    delta: 2,
})

重新打开页面

reLaunch 会关闭所有页面并打开目标页面，对应 wx.reLaunch。

navigate.reLaunch('/pages/index/index')

navigate.reLaunch({
    url: '/pages/index/index',
})

直接切换 tabBar

switchTab 对应 wx.switchTab。

navigate.switchTab('/pages/user/index')

navigate.switchTab({
    url: '/pages/user/index',
})

判断 tabBar 页面

isTabbar 用于判断页面路径是否属于 tabBar。

navigate.isTabbar('/pages/index/index')
navigate.isTabbar('/pages/index/index?id=1')
navigate.isTabbar('pages/index/index.html?id=1')

路径判断会忽略 query 参数，兼容不带开头 / 的路径，并移除 .html 后缀。

API

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | to | NavigateToOption \| NavigateSwitchTabOption | Promise<WechatMiniprogram.GeneralCallbackResult> | 跳转页面，自动兼容 tabBar | | replace | NavigateReplaceToOption | Promise<WechatMiniprogram.GeneralCallbackResult> | 关闭当前页并跳转，自动兼容 tabBar | | back | NavigateBackOption | Promise<WechatMiniprogram.GeneralCallbackResult> | 返回上一页、多级页面或指定历史页面 | | reLaunch | NavigateReLaunchOption | Promise<WechatMiniprogram.GeneralCallbackResult> | 关闭所有页面并打开目标页面 | | switchTab | NavigateSwitchTabOption | Promise<WechatMiniprogram.GeneralCallbackResult> | 切换到 tabBar 页面 | | isTabbar | string | boolean | 判断是否是 tabBar 页面 |

类型

import type {
    NavigateBackOption,
    NavigateReLaunchOption,
    NavigateReplaceToOption,
    NavigateSwitchTabOption,
    NavigateToOption,
} from '@kinngyo/wx-navigate'

type NavigateToOption = WechatMiniprogram.NavigateToOption | string

type NavigateSwitchTabOption = WechatMiniprogram.SwitchTabOption | string

type NavigateBackOption =
    | WechatMiniprogram.NavigateBackOption
    | string
    | number

type NavigateReplaceToOption = WechatMiniprogram.RedirectToOption | string

type NavigateReLaunchOption = WechatMiniprogram.ReLaunchOption | string

注意事项

• 本库用于微信小程序运行环境，依赖 wx、getCurrentPages 和小程序运行时配置。
• to 和 replace 会自动处理 tabBar 页面限制。
• back('/pages/index/index') 只能返回页面栈中已经存在的页面。
• 页面路径推荐使用 /pages/xxx/xxx，库内部也兼容 pages/xxx/xxx。