应用实例

createRouter()

创建一个路由程序实例。

类型

function createRouter(options: InitRouterOptionsRule): RouterRule

详细
options 为创建路由程序时的配置信息，你可以在此处找到 InitRouterOptionsRule 签名，或查看完整的配置参数说明构建实例 Option。

示例

import {
  createRouter,
  __dynamicImportComponent__,
  type platformRule,
} from '@/uni-simple-router'

const router = createRouter({
  platform: process.env.VUE_APP_PLATFORM as platformRule,
  routes:[
    {
      path: `/`,
      component: __dynamicImportComponent__(`@/pages/index.vue`, {
          pageType: `top`
      }),
    }
  ]
})

参考指南 - 从显示 Hello Word 开始

router.currentRoute

提供当前的路由信息，该对象为 shallowRef 响应数据，如需访问真实数据可通过 unref 或者 .value获取。

类型

interface RouteRecordRow {
    fullPath: string;
    path: string;
    params: Record<string, any>;
    query: Record<string, any>;
    meta: Exclude<RouteRecordBaseRule['meta'], void>;
    name: RouteRecordBaseRule['name'] | undefined;
    matched: RouteRecordMatched[];
    navType: NavTypeRule;
}

type currentRoute = ShallowRef<RouteRecordRow>

详细
如果你需要在非 Vue 组件内部访问当前路由信息，可以通过使用 router.currentRoute 来获取。此属性提供了当前路由的详细信息，包括路径、参数、查询参数等。你还可以通过对该对象进行 watch 监听，以便在导航发生变化时执行相应的逻辑处理。

示例

import {watch}  from 'vue'
const router = createRouter({
  // 其他路由配置信息
})

const route = router.currentRoute
// 访问路由信息数据
console.log(route.value)

// 监听路由变化
watch(route,(value)=>{
  console.log(value)
})

参考指南 - 当前路由信息

router.$lockStatus

路由导航锁是一个用于控制导航行为的标识，在当前导航正在进行时，该值为 false，表示导航被锁住，无法进行其他导航操作。相反，如果该值为 true，表示导航已经接受，可以进行导航操作。

需要注意的是，该配置仅适用于非 H5 端。

类型
ts
```
type $lockStatus = boolean
```
- 参考指南 - 导航路由锁

router.beforeEach

用于创建一个全局前置守卫的函数。通过该函数，你可以多次注册前置守卫，这些守卫将按照它们的注册顺序执行。

类型

interface NavigationGuardWithThis {
  (to: RouteRecordRow, from: RouteRecordRow): void;
}

function beforeEach(guard: NavigationGuardWithThis): () => void;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.beforeEach((to,from)=>{
  console.log(to)
})

参考指南 - 全局前置守卫

router.afterEach

用于创建一个全局后置钩子函数。通过该函数，你可以多次注册全局后置钩子，这些钩子将按照它们的注册顺序执行。

类型

interface NavigationHookAfter {
    (to: RouteRecordRow, from: RouteRecordRow): any;
}

function beforeEach(guard: NavigationHookAfter): () => void;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.afterEach((to,from)=>{
  console.log(to)
})

参考指南 - 全局后置钩子

router.beforeResolve

用于创建一个全局解析守卫。通过该函数，你可以多次注册解析守卫，这些守卫将按照它们的注册顺序执行。

类型

interface NavigationGuardWithThis {
  (to: RouteRecordRow, from: RouteRecordRow): void;
}

function beforeResolve(guard: NavigationGuardWithThis): () => void;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.beforeResolve((to,from)=>{
  console.log(to)
})

参考指南 - 全局解析守卫

router.isReady() ^v1.1.6+

返回一个 Promise，它会在路由器完成初始导航之后被解析，也就是说这时所有和初始路由有关联的异步入口钩子和异步组件都已经被解析。如果初始导航已经发生，则该 Promise 会被立刻解析。

类型
ts
```
type IsReadyRule = ()=>Promise<void>
```

示例

const router = createRouter({
  // 其他路由配置信息
})

router.isReady().then(()=>{
  console.log(`路由准备就绪`)
})

router.push()

打开一个新的页面，这个方法会向 history 栈添加一个新的记录，并保留当前页面。

类型

type RoutePushLocationRaw = string 
                            | RouteLocationPushPathRaw 
                            | RouteLocationPushNameRaw;

function push(to: RoutePushLocationRaw): Promise<
    void 
    | NavigationFailure 
    | undefined
>;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.push(`/newPage?id=123456`)

参考指南 - 编程式导航

router.pushTab()

导航到一个新的原生Tabbar页面，然后关闭所有非原生Tabbar页面。

类型

type RouteLocationRaw = string 
                            | RouteLocationPathRaw 
                            | RouteLocationNameRaw;

function pushTab(to: RouteLocationRaw): Promise<
    void 
    | NavigationFailure 
    | undefined
>;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.pushTab(`/newTabbar`)

参考指南 - 编程式导航

router.replace()

关闭当前页面，跳转到应用内的某个页面。

类型

type RouteLocationRaw = string 
                          | RouteLocationPathRaw 
                          | RouteLocationNameRaw;

function replace(to: RouteLocationRaw): Promise<
    void 
    | NavigationFailure 
    | undefined
>;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.replace(`/newPage?id=999`)

参考指南 - 编程式导航

router.replaceAll()

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

类型

type RouteLocationRaw = string 
                          | RouteLocationPathRaw 
                          | RouteLocationNameRaw;

function replaceAll(to: RouteLocationRaw): Promise<
    void 
    | NavigationFailure 
    | undefined
>;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.replaceAll(`/newPage?id=999`)

参考指南 - 编程式导航

router.back()

关闭当前页面，返回上一页面或多级页面。

类型

interface RouteLocationObjectRaw {
    success?: Function;
    fail?: Function;
    complete?: Function;
    navType?: NavTypeRule;
}

interface NavigateBackRaw extends RouteLocationObjectRaw {
    delta?: number;
    animationType?: string;
    animationDuration?: number;
    backType?: backTypeRule;
    from?: `backbutton` | `navigateBack`;
}

function back( to: NavigateBackRaw | number | undefined): Promise<
    void 
    | NavigationFailure 
    | undefined
>;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.back(1)

参考指南 - 编程式导航

陷阱提示

在H5上该方法会立即进入 Promise.resolve , 即时你在路由守卫下中断了导航。所以你不能在该动作中判断页面是否返回成功！

router.onError()

用于为路由实例内抛出的未捕获错误指定一个全局处理函数。你可以多次注册该钩子函数，并且它们将按照注册顺序执行。

类型

type _ErrorHandler = (error: NavigationFailure) => any;

type NavigationFailureType = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;

interface NavigationFailure {
    type: NavigationFailureType;
    msg: string;
    from: RouteRecordRow;
    to?: RouteRecordRow | ToLocationRawRule;
}

function onError(handler: _ErrorHandler): () => void;

详细
如需查阅所有错误码，你可以在此处找到 NavigationFailureType

示例

const router = createRouter({
    // 其他路由配置信息
  })

  router.onError((e)=>{
    console.log(e)
  })

router.addRoute()

该方法用于动态添加路由表。你可以使用该方法为指定的路由表添加子集路由表，也可以创建整个路由表。

类型

function addRoute(
  parentOrRoute: RouteRecordName | RouteRecordBaseRule, 
  route?: RouteRecordBaseRule
):() => boolean;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.addRoute({ path: '/about', component: About })

参考指南 - 添加路由

router.removeRoute()

动态删除指定名称的路由表。

类型

function removeRoute(
  matcherRef: RouteRecordName | RouteRecordMatcher
): boolean;

示例

const router = createRouter({
  // 其他路由配置信息
})

router.addRoute({ path: '/about', name: 'about', component: About })
// 删除路由
router.removeRoute('about')

参考指南 - 删除路由

应用实例 ​

createRouter() ​

router.currentRoute ​

router.$lockStatus ​

router.beforeEach ​

router.afterEach ​

router.beforeResolve ​

router.isReady() v1.1.6+ ​

router.push() ​

router.pushTab() ​

router.replace() ​

router.replaceAll() ​

router.back() ​

router.onError() ​

router.addRoute() ​

router.removeRoute() ​