Router 路由

介绍

面向 uni-app 的路由用法示例：跳转、读取路由信息、异步导航守卫等。

安装与接入、类型提示、包名配置等完整说明见 Router 路由。

基础用法

页面内获取路由实例与路由信息：

const router = useRouter();
const route = useRoute();         // 全局当前路由（跟踪最新活跃页）
const pageRoute = usePageRoute(); // 本页路由快照（跳转后不变）

TIP

useRoute / usePageRoute 返回响应式对象；经 router.push 等进入的非首屏页，在 setup 内即可读到完整 query 与 pages.json 配置（meta / style / config），无需等待 onLoad。

跳转

// ① pack + path（推荐）
router.push({ pack: 'case', path: '/router/detail', query: { id: '1' } });

// ② pack + name
router.push({ pack: 'case', name: 'router-detail', query: { id: '1' } });

// ③ 完整路径
router.push('/pagesCase/router/detail?id=1');

// 其他方法
router.replace({ pack: 'case', path: '/router' });
router.back();

跳转均为 Promise，失败时可捕获：

try {
  await router.push({ pack: 'case', path: '/not-exists' });
} catch (err) {
  console.warn('跳转失败', err);
}

方法	说明
router.push	保留当前页跳转
router.pushTab	跳转 tabBar 页
router.replace	关闭当前页跳转
router.replaceAll	关闭所有页打开目标页
router.back	返回上 N 级，默认 1

获取路由信息

const route = useRoute();
const pageRoute = usePageRoute();

// 常用字段
pageRoute.name;
pageRoute.path;
pageRoute.pack;
pageRoute.fullPath;
pageRoute.query;
pageRoute.meta;
pageRoute.style;
pageRoute.config;

API	说明
useRoute()	全局当前路由，始终跟踪最新活跃页
usePageRoute()	本页快照，进入时写入，跳转后不被新页覆盖

导航守卫

常用于登录拦截等场景，按需使用

router.beforeEach(async (to, from) => {
  if (to.path === '/router/guard') {
    try {
      await showDialog({
        title: '提示',
        message: '确认进入吗？',
        showCancelButton: true,
      });

      // 确认
    } catch {
      return false; // 取消
    }
  }
});

router.afterEach((to, from) => {
  // 导航完成后上报、埋点等
});

返回值	行为
undefined / true / 无返回	放行
false	取消本次跳转
字符串或位置对象	重定向到该位置

更多

接入插件、类型互绑、包名派生、边界说明等详见 Router 路由。