RouterLink

导航组件，点击时触发路由跳转。H5 端渲染为原生 <a> 标签（带 href），恢复链接的语义化、右键新标签页、无障碍识别等原生能力；其他平台渲染为 <navigator>，通过 hover-class 等属性提供点击态反馈。

引入

import RouterLink from '@meng-xi/uni-router/components/router-link/router-link.vue'

直接引入 .vue 文件

RouterLink 是一个独立的 Vue 组件文件，需要直接引入 .vue 文件路径，而非从包入口导入。建议在 pages.json 的 easycom 中配置自动引入，或在 main.ts 中全局注册。

全局注册（推荐）

// src/main.ts
import { createSSRApp } from 'vue'
import App from './App.vue'
import router from './router'
import RouterLink from '@meng-xi/uni-router/components/router-link/router-link.vue'

export function createApp() {
  const app = createSSRApp(App)
  app.use(router)
  app.component('RouterLink', RouterLink) // 全局注册
  return { app }
}

注册后可在任何组件中直接使用 <RouterLink>，无需每次导入。

Props

to

类型: RouteLocationRaw
必填: 是
说明: 目标路由位置，支持以下形式：
- 路径字符串：'pages/about/about'
- 路径对象：{ path: 'pages/about/about', query: { id: '1' } }
- 命名对象：{ name: 'about', query: { id: '1' } }

vue

<!-- 路径字符串 -->
<RouterLink to="pages/about/about">关于</RouterLink>

<!-- 路径对象（需用 :to 绑定） -->
<RouterLink :to="{ path: 'pages/about/about', query: { id: '1' } }">详情</RouterLink>

<!-- 命名路由（推荐） -->
<RouterLink :to="{ name: 'about', query: { id: '1' } }">详情</RouterLink>

对象形式必须用 :to 绑定

to 属性传入对象时需使用 :to 绑定（v-bind:to），而非字符串属性 to。字符串形式 to="pages/about/about" 可直接使用。

插件依赖字段

params、animation、events 等插件依赖字段通过 to 对象传入，不再作为独立 Props。使用时需注册对应插件：

vue

<!-- 传递 params（需 ParamsPlugin） -->
<RouterLink :to="{ path: 'pages/detail/detail', params: { id: 123 } }">
  <text>查看详情</text>
</RouterLink>

<!-- 传递 animation（需 AnimationPlugin） -->
<RouterLink :to="{ path: 'pages/about/about', animation: { type: 'slide-in-bottom' } }">
  <text>底部滑入</text>
</RouterLink>

详见插件系统。

replace

类型: boolean
默认值: false
说明: 是否使用替换模式导航
- false → 调用 router.push(to)
- true → 调用 router.replace(to)

vue

<!-- 登录页跳转，避免登录页留在栈中 -->
<RouterLink to="pages/home/home" replace>
  <text>登录</text>
</RouterLink>

relaunch

类型: boolean
默认值: false
说明: 是否使用 relaunch 模式导航（关闭所有页面并打开目标页面）
- true → 调用 router.relaunch(to)
- 优先级高于 replace，同时设置 relaunch 和 replace 时使用 relaunch

vue

<!-- 退出登录，清空栈 -->
<RouterLink to="pages/login/login" relaunch>
  <text>退出登录</text>
</RouterLink>

<!-- 从深层页面回首页 -->
<RouterLink to="pages/index/index" relaunch>
  <text>返回首页</text>
</RouterLink>

hoverClass

类型: string
默认值: 'navigator-hover'
说明: 按下时的样式类（仅非 H5 平台生效），对应 <navigator> 的 hover-class 属性；H5 端渲染为 <a>，使用原生 CSS :hover 提供反馈。设置为 'none' 可禁用点击态

hoverStopPropagation

类型: boolean
默认值: false
说明: 是否阻止祖先节点的点击态

hoverStartTime

类型: number
默认值: 50
说明: 按住后多久出现点击态，单位 ms

hoverStayTime

类型: number
默认值: 600
说明: 手指松开后点击态保留时间，单位 ms

事件

error

参数: (error: NavigationFailure)
说明: 导航失败时触发，如守卫中止、重复导航等。不监听时静默处理，不会产生 Unhandled Promise Rejection。

vue

<RouterLink to="pages/about/about" @error="onNavError">
  <text>关于我们</text>
</RouterLink>

import { NavigationFailure, RouterErrorCode } from '@meng-xi/uni-router'

function onNavError(error: NavigationFailure) {
  switch (error.code) {
    case RouterErrorCode.NAVIGATION_ABORTED:
      console.log('导航被守卫中止')
      break
    case RouterErrorCode.NAVIGATION_DUPLICATED:
      console.log('已在当前页面')
      break
    case RouterErrorCode.NAVIGATION_API_ERROR:
      uni.showToast({ title: '导航失败', icon: 'none' })
      console.error('原始错误:', error.cause)
      break
  }
}

建议监听 error 事件

不监听 error 事件时，导航失败会静默处理（不会抛出未捕获的 Promise 拒绝）。但建议在生产环境监听并处理错误，提升用户体验。

navigated

参数: (eventChannel: EventChannel | undefined)
说明: 导航成功后触发，返回 eventChannel 用于页面间通信。默认仅 push 模式下 eventChannel 有值；启用 useUniEventChannel 后 replace / relaunch 也可获取 eventChannel。

vue

<RouterLink
  :to="{ path: 'pages/detail/detail', query: { id: '1' } }"
  @navigated="onNavigated"
>
  <text>查看详情</text>
</RouterLink>

function onNavigated(eventChannel) {
  // 向目标页面发送事件
  eventChannel?.emit('init', { message: '来自发起页面的数据' })
}

插槽

default

默认插槽，用于放置导航链接的内容：

vue

<RouterLink to="pages/about/about">
  <text>前往关于页</text>
</RouterLink>

<!-- 复杂内容 -->
<RouterLink :to="{ name: 'detail', query: { id: item.id } }">
  <view class="card">
    <image :src="item.cover" />
    <text>{{ item.title }}</text>
    <text>{{ item.desc }}</text>
  </view>
</RouterLink>

示例

基本用法

vue

<template>
  <RouterLink to="pages/about/about">
    <text>关于我们</text>
  </RouterLink>
</template>

<script setup lang="ts">
import RouterLink from '@meng-xi/uni-router/components/router-link/router-link.vue'
</script>

替换模式

vue

<!-- 登录成功后跳首页，避免登录页留在栈中 -->
<RouterLink to="pages/home/home" replace>
  <text>登录</text>
</RouterLink>

重置模式

vue

<!-- 退出登录，清空所有页面 -->
<RouterLink to="pages/login/login" relaunch>
  <text>退出登录</text>
</RouterLink>

带查询参数

vue

<!-- 字符串形式 -->
<RouterLink to="pages/about/about?id=1&tab=info">
  <text>文章详情</text>
</RouterLink>

<!-- 对象形式（推荐） -->
<RouterLink :to="{ name: 'about', query: { id: '1', tab: 'info' } }">
  <text>文章详情</text>
</RouterLink>

处理导航错误

vue

<RouterLink :to="{ name: 'admin' }" @error="onNavError">
  <text>管理后台</text>
</RouterLink>

列表场景

vue

<template>
  <view class="list">
    <RouterLink
      v-for="item in list"
      :key="item.id"
      :to="{ name: 'detail', query: { id: item.id } }"
    >
      <view class="card">
        <text>{{ item.title }}</text>
      </view>
    </RouterLink>
  </view>
</template>

H5 原生链接能力

H5 端 RouterLink 通过 #ifdef H5 条件编译渲染为原生 <a> 标签（带真实 href），恢复浏览器链接的原生能力：

能力	说明
链接语义	页面中存在真实 `<a>` 标签，语义化结构完整
右键新标签页打开	右键菜单可正常弹出，"在新标签页打开"直接打开目标路由
浏览器地址识别	悬停时状态栏显示目标地址，浏览器识别为超链接
无障碍支持	屏幕阅读器等无障碍工具可正确识别为链接
href 原生行为	修饰键（Ctrl/Cmd/Shift/Alt）或中键点击保留浏览器默认行为

普通左键点击仍会阻止默认跳转并交由路由器导航，因此守卫链（beforeEach 等）照常生效：

// 组件内部（H5 分支）
async function handleClick(event: unknown) {
	// #ifdef H5
	const e = event as MouseEvent
	// 修饰键或中键点击 → 保留浏览器原生行为（新标签页打开等）
	if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey || e.button !== 0) {
		return
	}
	e.preventDefault()
	// #endif
	// 走路由器导航（守卫链生效）
	await navigate()
}

平台差异（条件编译）

H5：渲染为 <a>（带 href），href 自动适配 hash 路由（# 前缀），确保右键"在新标签页打开"能正确路由
App / 小程序：渲染为 <navigator>（uni-app 原生导航组件）

与 vue-router RouterLink 的差异

特性	vue-router	Uni Router
宿主元素	`<a>`	H5：`<a>`；其他平台：`<navigator>`
`to` 类型	`string \| object`	`string \| object`
`replace`	✅	✅
`relaunch`	❌	✅
`custom`	✅	❌
`active-class`	✅	❌
`exact-active-class`	✅	❌
`v-slot` 作用域插槽	✅	❌
`hover-class`	❌	✅
`error` 事件	❌	✅
`navigated` 事件	❌	✅

不支持 active-class 的原因

vue-router 的 active-class 依赖浏览器 URL 实时匹配，而 uni-app 的导航由原生页面栈管理，组件无法感知当前页面状态。如需高亮当前页面对应的链接，可通过 useRoute() 手动判断：

vue

<script setup lang="ts">
import { useRoute } from '@meng-xi/uni-router'

const route = useRoute()
const isActive = (name: string) => route.value.name === name
</script>

<template>
  <RouterLink to="pages/home/home">
    <text :class="{ active: isActive('home') }">首页</text>
  </RouterLink>
</template>

不支持 custom 的原因

vue-router 的 custom 允许完全自定义渲染逻辑，依赖 <a> 标签和浏览器导航。uni-app 中导航由路由器 API 驱动而非原生组件，无法完全自定义渲染行为。如需自定义导航触发，使用 useLink() 组合式 API 封装自定义导航组件（可自行渲染任意元素，H5 端可渲染原生 <a> 恢复链接能力）：

下一步

Router 实例 — 编程式导航 API
路由导航 — 四种导航方式的深入讲解
RouteLocationRaw 类型 — to 属性的类型定义
插件系统 — 了解插件注册机制

RouterLink ​

引入 ​

全局注册（推荐） ​

Props ​

to ​

replace ​

relaunch ​

hoverClass ​

hoverStopPropagation ​

hoverStartTime ​

hoverStayTime ​

事件 ​

error ​

navigated ​

插槽 ​

default ​

示例 ​

基本用法 ​

替换模式 ​

重置模式 ​

带查询参数 ​

处理导航错误 ​

列表场景 ​

H5 原生链接能力 ​

与 vue-router RouterLink 的差异 ​

不支持 active-class 的原因 ​

不支持 custom 的原因 ​

下一步 ​