update
迁移文档 小爱为你推荐使用新版本哦~~

# Router 构建选项

# routes

  • 类型: Array<RouteConfig>

  • 必填:

  • 平台:全端

RouteConfig 的类型定义:

interface RouteConfig {
  path: string, //pages.json中的path 必须加上 '/' 开头
  component?: Component,    //H5端可用
  name?: string, // 命名路由    
  components?: { [name: string]: Component }, // 命名视图组件,H5端可用   
  redirect?: string | Location | Function,  // V2.0.6+ 所有端可用 之前的版本仅支持H5
  props?: boolean | Object | Function,  //H5端可用
  aliasPath?:string,    //h5端 设置一个别名路径来替换 uni-app的默认路径
  alias?: string | Array<string>,   //H5端可用
  children?: Array<RouteConfig>, // 嵌套路由,H5端可用
  beforeEnter?: (to: Route, from: Route, next: Function) => void,   //路由元守卫
  meta?: any,   //其他格外参数
  [propName: string]: any;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# APP

  • 类型: Object

  • 必填:

  • 平台:app

interface AppConfig {
    //用于控制是否注册加载页。如果关闭将不会执行 `loadingPageHook` `loadingPageStyle` 函数
    registerLoadingPage?:boolean; // 是否注册过渡加载页 默认`开启`  +v2.0.6 
	loadingPageStyle?: () => object; // 当前等待页面的样式 必须返回一个json
    loadingPageHook?: (view:any)=>void; // 刚刚打开页面处于等待状态,会触发此函数
    launchedHook?:()=>void; // 首次启动app完成
    animation?: startAnimationRule; // 页面切换动画
}
1
2
3
4
5
6
7
8

# h5

  • 类型: Object

  • 必填:

  • 平台:H5

interface H5Config {
	paramsToQuery?: boolean; // h5端上通过params传参时规则是vue-router 刷新会丢失 开启此开关将变成?连接的方式
	vueRouterDev?: boolean; // 完全使用采用vue-router的开发模式
	vueNext?: boolean; // 在next管道函数中是否获取vueRouter next的原本参数
	mode?: string;
	base?: string;
	linkActiveClass?: string;
	linkExactActiveClass?: string;
	scrollBehavior?: Function;      //滚动到指定位置
	fallback?: boolean;
}
1
2
3
4
5
6
7
8
9
10
11

目前你可以在这里设置一些常规的操作,后续应该能设置全部的 vue-router 配置

# applet V 2.0.6+

  • 类型: Object

  • 必填:

  • 平台:小程序

interface appletConfig {
    animationDuration?:number; // 页面切换时间,有助于路由锁精准解锁
}
1
2
3

# platform V 2.0.0+

  • 类型: 'h5'|'app-plus'|'app-lets'|'mp-weixin'|'mp-baidu'|'mp-alipay'|'mp-toutiao'|'mp-qq'|'mp-360'

  • 必填:

  • 默认值:

  • 平台:全端

    指定编译时当前为什么端,通过 process.env.VUE_APP_PLATFORM 传递即可。

# debugger

  • 类型: boolean

  • 必填:

  • 默认值:false

  • 平台:全端

    在开发阶段可以设置为 true 进行日常的日志捕捉,用于调试开发。开启后将会在控制台统一输出路由的所有日志。

# keepUniOriginNav V 2.0.0+

  • 类型: boolean

  • 必填:

  • 默认值:false

  • 平台:全端

    重写uni-app的跳转方法;关闭后使用uni-app的原始方法跳转和插件api跳转等同。

# routerBeforeEach

  • 类型: (to:navtoRule, from:navtoRule, next:(rule?: navtoRule|false)=>void) => void;

  • 必填:

  • 默认值:(to, from, next) => { next() }

  • 平台:全端

    uni-simple-router 前置路由函数 每次触发跳转前先会触发此函数,你可以在这里面做写什么。可能有、动画、记录等等操作。

# routerAfterEach

  • 类型: (to:navtoRule, from:navtoRule, next?: Function) => void

  • 必填:

  • 默认值:(to, from) => {}

  • 平台:全端

    uni-simple-router 后置路由函数 每次触发跳转后会触发此函数。

# routerErrorEach V 2.0.0+

  • 类型: (error: navErrorRule, router:Router) => void

  • 必填:

  • 默认值:(error, router) => { err(error, router, true) }

  • 平台:全端

    uni-simple-router 每次跳转失败时都会触发此方法并传递失败原因,详细信息如下:

    export type navRuleStatus=	0|1|2|3;
    interface navErrorRule {
        type: navRuleStatus;
        msg: string;
        to?:totalNextRoute;
        from?:totalNextRoute;
        nextTo?:any;
        [propName:string]:any;
    }
    0 表示 next(false)
    1 表示 next(unknownType)
    2 表示加锁状态,禁止跳转
    3 表示在获取页面栈的时候,页面栈不够level获取
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

# resolveQuery V 2.0.0+

  • 类型: (jsonQuery:objectAny)=>objectAny;

  • 必填:

  • 默认值:

  • 平台:全端

    每次跳转之前把参数传递给此函数、返回最终的参数!如果有此函数则不走默认方法。

# parseQuery V 2.0.0+

  • 类型: (jsonQuery:objectAny)=>objectAny;

  • 必填:

  • 默认值:

  • 平台:全端

    读取参数之前把参数传递给此函数,返回最终的数据!有此函数则不走默认方法。

# detectBeforeLock V 2.0.0+

  • 类型: (router:Router, to:string|number|totalNextRoute, navType:NAVTYPE)=>void;

  • 必填:

  • 默认值:(router, to, navType) => {}

  • 平台:全端

    每次在检测加锁状态前执行此函数,可以通过此函数来进行解锁。

# Router 实例方法

# router.beforeEach

# router.afterEach

函数签名:

router.beforeEach((to, from, next) => {
  /* 必须调用 `next` */
})

router.afterEach((to, from) => {})
1
2
3
4
5

全局守卫,你可以在里面做一些你想要 的事情。我可管不着!

# router.push

# router.replace

# router.replaceAll

# router.pushTab

# router.back

函数签名:

router.push({name:'tab1'})
router.replace({name:'tab1'})
router.replaceAll({name:'tab1'})
router.pushTab({name:'tab1'})
router.back(2,{
    success:(...arg)=>{
        console.log(arg)
    }
})
1
2
3
4
5
6
7
8
9

动态的导航到一个新 URL。参考 编程式导航

# router.forceGuardEach(navType, forceNav)

函数签名:

router.forceGuardEach('push',false)
1

H5端强制性触发路由守卫,navType所有可用的NAVTYPEforceNav 是否在执行守卫的同时开启跳转,默认为 false

# 路由元信息

一个 路由对象 (route object) 表示当前激活的路由的状态信息,包含了当前 URL 解析得到的信息,还有 URL 匹配到的 路由记录 (route records)。

路由对象是不可变 (immutable) 的,每次成功的导航后都会产生一个新的对象。

路由对象出现在多个地方:

  • 在组件内,即 this.$Route

  • 导航守卫的参数:

router.beforeEach((to, from, next) => {
  // `to` 和 `from` 都是路由对象
})

router.afterEach((to, from) => {
  // `to` 和 `from` 都是路由对象
})
1
2
3
4
5
6
7
  • 甚至在 H5scrollBehavior 方法的参数:
const router =createRouter({
    h5:{
        scrollBehavior(to, from, savedPosition) {
            // `to` 和 `from` 都是路由对象
        }
    }
})
1
2
3
4
5
6
7
  • H5$route 观察者回调内

  • H5router.match(location) 的返回值

# 路由对象属性

  • $Route.BACKTYPE V 2.0.5+

    • 类型: backbutton'|'navigateBack'|''

      APP 返回时会在守卫 to 参数下标明。其他端及非返回状态下都为字符串

  • $Route.NAVTYPE V 2.0.0+

    • 类型: push'|'replace'|'replaceAll'|'pushTab'|'back'

      当前跳转到本页面的跳转类型。

  • $Route.name

    • 类型: string|undefined

      当前路由的名称,如果有的话。

  • $Route.fullPath

    • 类型: string

      完成解析后的 URL,包含查询参数和 hash 的完整路径。

  • $Route.path

    • 类型: string

      字符串,对应当前路由的路径,总是解析为绝对路径,如 "/pages/tabbar/tabbar-1/tabbar-1"

  • $Route.params

    • 类型: Object

      一个 key/value 对象,包含了动态片段和全匹配片段,如果没有路由参数,就是一个空对象。目前非 完全使用vue-router开发 的模式下,此参数为保留参数。

  • $Route.query

    • 类型: Object

      一个 key/value 对象,表示 URL 查询参数。例如,对于路径 /foo?user=1,则有 $Route.query.user == 1,如果没有查询参数,则是个空对象。

更多路由对象属性,你可以在实例化路由对象时 routes 中传递更多的自定义信息。在非 完全使用vue-router开发vueNext:true 的情况下都会带上匹配的所有参数。

当你使用 完全使用vue-router开发 的模式时,你可以访问 vue-router文档查看更多信息

# 组件注入

# 注入的属性

通过在 Vue 根实例的 router 配置传入 router 实例,下面这些属性成员会被注入到每个子组件。

  • this.$Router

    router 实例。

  • this.$Route

    当前激活的路由信息对象。

# 辅助API

# RouterMount(Vim, router, el) V 1.3.5+

  • 平台:H5

    用于替换 main.jsapp.$mount(); 功能,保证在 H5端 路由守卫能正常运行

# runtimeQuit(title) V v2.0.0-alpha.4+

  • 平台:APP

    app平台在首页时,多次按下返回按钮退出应用

# push

跳转到普通页面,新开保留历史记录

# replace

动态的导航到一个新 URL 关闭当前页面,跳转到的某个页面。

# replaceAll

动态的导航到一个新 URL 关闭所有页面,打开到应用内的某个页面

# pushTab

动态的导航到一个新 url 关闭所有页面,打开到应用内的某个tab

# back v 2.0.0+

动态调用 back 关闭当前页面,返回上一页。

# 完全使用vue-router开发时的API

当前你在路由配置中设置 vueRouterDev:true 时。这时的路由将会完全变成 vue-router 的模式,任何 vue-router 相关的API都可以使用。移步到这里查看API


示例

这里有完整的使用案例 routerlink

// main.js 地址换成自己的
import Mylink from './node_modules/uni-simple-router/dist/link.vue'     
Vue.component('my-link',Mylink)
1
2
3

# to

  • 类型: string | Location

  • required

表示目标路由的链接。当被点击后,内部会立刻把 to 的值传到 router.push(),所以这个值可以是字符串对象,也可以是一个绝对路径,也可以是一个相对路径

<my-link to="{name: 'tabbar-4',params: {name: '我只想去tab5的my-link'}}" navType="pushTab">
  <button type="primary">使用name对象跳转</button>
</my-link>

<my-link to="{path: '/pages/tabbar/tabbar-4/tabbar-4',query: {name: '我只想去tab5的my-link'}}" navType="pushTab">
  <button type="primary">使用path对象跳转</button>
</my-link>

<my-link to="{path: '/tabbar-4/tabbar-4',query: {name: '我只想去tab5的my-link'}}" navType="pushTab" :level="2" :append="true">
  <button type="primary">使用path对象继承父路径跳转</button>
</my-link>

<my-link to="/pages/tabbar/tabbar-4/tabbar-4" navType="pushTab">
  <button type="warn">通过路由path直接跳转</button>
</my-link>

<my-link to="/tabbar-4/tabbar-4" navType="pushTab" :level="2" :append="true">
  <button type="warn">通过路由path继承父路径跳转</button>
</my-link>

<my-link to="/tabbar-4/tabbar-4" navType="pushTab" :level="2" :append="true" :stopNavto="true">
  <button type="default">阻止组件事件,不会跳转</button>
</my-link>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# stopNavto

  • 类型: Boolean

  • 默认值: false

默认绑定事件为点击事件,不阻止。

<my-link to="/tabbar-4/tabbar-4"  :stopNavto="true">
  <button type="default">阻止组件事件,不会跳转</button>
</my-link>
1
2
3
  • 类型: String

  • 默认值: push

需要跳转的 NAVTYPE 类型

<my-link to="/tabbar-4/tabbar-4"  navType="pushTab">
  <button type="default">指定跳转到uni-app自带tab</button>
</my-link>
1
2
3

# level

  • 类型: Number

  • 默认值: 1

相对于当前页面路径,以 / 从后往前裁切的层级。append 为true时生效

<my-link to="{path: '/tabbar-4/tabbar-4'}" :level="2" :append="true">
  <button type="primary">使用path对象继承父路径跳转</button>
</my-link>
1
2
3

# append

  • 类型: Boolean

  • 默认值: false

是否相对于当前页面路径跳转。根据 level 层级截取的路径 拼接 to只针对使用path跳转的情况

<my-link to="{path: '/tabbar-4/tabbar-4'}" :level="2" :append="true">
  <button type="primary">使用path对象继承父路径跳转</button>
</my-link>
1
2
3