组件

vitarx-router 提供了两个内置组件：RouterView 用于渲染匹配的路由组件，RouterLink 用于声明式导航链接。

RouterView

路由视图组件，用于渲染当前路由匹配到的组件。RouterView 会根据路由匹配结果自动选择并渲染对应的组件。

类型定义

interface RouterViewOptions {
  name?: string
  children?: (
    component: Computed<Component | null>,
    props: Computed<AnyProps | null>,
    route: Computed<RouteRecord | null>
  ) => View
}

function RouterView(props: RouterViewOptions): View

参数

参数	类型	默认值	说明
name	`string`	`'default'`	命名视图名称，对应路由配置中 `component` 对象的键名
children	`Function`	—	自定义渲染函数，接收组件、属性和路由记录三个计算属性

详情

RouterView 通过依赖注入自动感知当前渲染深度，嵌套的 RouterView 会依次渲染 matched 数组中对应层级的组件。

命名视图：当路由配置了命名组件时，通过 name 属性指定渲染哪个视图：

// 路由配置
{ path: '/dashboard', component: { default: Dashboard, sidebar: Sidebar } }

// 模板中使用
<RouterView />              {/* 渲染 Dashboard */}
<RouterView name="sidebar" /> {/* 渲染 Sidebar */}

自定义渲染函数：children 函数接收三个 Computed 参数，可以实现与 Transition、Freeze 等组件的组合使用。

示例

tsx

// 基本用法
<RouterView />

// 命名视图
<RouterView name="sidebar" />

// 搭配 Freeze 使用（保持组件状态）
<RouterView>
  {(component, props) => <Freeze is={component} props={props} />}
</RouterView>

// 搭配 Transition 使用
<Transition>
  <RouterView />
</Transition>

// Freeze & Transition 组合使用
<Transition>
  <RouterView>
    {(component, props) => <Freeze is={component} props={props} />}
  </RouterView>
</Transition>

// 等效的另类写法
<RouterView>
  {(component, props) => (
    <Transition>
      <Freeze is={component} props={props} />
    </Transition>
  )}
</RouterView>

RouterLink

路由链接组件，渲染为 <a> 标签，用于在应用内进行声明式导航。基于 useLink() 实现，自动处理点击事件、激活状态类名和无障碍属性。

类型定义

interface RouterLinkProps extends UseLinkOptions, Omit<WithProps<'a'>, 'href' | 'onClick'> {
  children?: RenderChildren
  disabled?: boolean
  callback?: (result: NavigateResult) => void
  activeClass?: string
  exactActiveClass?: string
  disabledClass?: string
  ariaCurrentValue?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'
}

function RouterLink(props: RouterLinkProps, location?: CodeLocation): ElementView<'a'>

UseLinkOptions

参数

参数	类型	默认值	说明
to	`NavTarget \| RouteIndex \| string`	—	必填。导航目标，可以是路由路径、名称、`NavTarget` 对象或完整 URL
replace	`boolean`	`false`	是否使用 `router.replace()` 代替 `router.push()`
viewTransition	`boolean`	`false`	是否使用 `document.startViewTransition()` 进行视图过渡
exactMatchMode	`'path' \| 'href' \| 'hash' \| 'query'`	`'path'`	精确匹配模式，影响 `isExactActive` 的判断逻辑
children	`RenderChildren`	—	子节点插槽
disabled	`boolean`	`false`	是否禁用链接。禁用后点击无效果
callback	`(result: NavigateResult) => void`	—	导航完成后的回调函数
activeClass	`string`	—	当链接部分匹配当前路由时应用的 CSS 类名
exactActiveClass	`string`	—	当链接精确匹配当前路由时应用的 CSS 类名
disabledClass	`string`	—	当链接禁用时应用的 CSS 类名
ariaCurrentValue	`string`	—	精确匹配时 `aria-current` 属性的值

详情

激活状态判断：

部分匹配（isActive）：当前路由路径以目标路径为前缀（路径段级别）。例如，to="/users" 在 /users/123 页面下也会被视为激活
精确匹配（isExactActive）：当前路由与目标路由完全匹配，匹配维度由 exactMatchMode 控制：
- 'path'：仅比较路径
- 'href'：比较完整 URL
- 'hash'：比较路径和 hash
- 'query'：比较路径和查询参数

外部链接：当 to 为 http:// 或 https:// 开头的外部链接时，RouterLink 会渲染为普通 <a> 标签，不触发路由导航。

透传属性：RouterLink 继承了 <a> 标签的所有属性（如 target、class、style 等），会自动透传到渲染的 <a> 元素上。

示例

tsx

// 基本用法
<RouterLink to="/about">关于我们</RouterLink>

// 激活类名
<RouterLink to="/about" activeClass="active">关于我们</RouterLink>

// 精确匹配类名
<RouterLink to="/" exactActiveClass="exact-active">首页</RouterLink>

// 外站链接（渲染为普通 <a> 标签）
<RouterLink to="https://www.example.com" target="_blank">访问示例站</RouterLink>

// 禁用状态
<RouterLink to="/about" disabled>关于我们</RouterLink>

// 替换模式
<RouterLink to="/login" replace>登录</RouterLink>

// 带参数的导航
<RouterLink to={{ index: '/user', query: { id: '123' } }}>用户信息</RouterLink>

// 导航回调
<RouterLink to="/dashboard" callback={(result) => {
  if (result.state !== NavState.success) {
    console.warn('导航失败:', result.message)
  }
}}>仪表盘</RouterLink>

// 透传属性
<RouterLink to="/about" class="nav-link" target="_blank">关于我们</RouterLink>

参考：RouterLink 组件