基础路由

基础路由是 vitarx-router 中最简单的路由形式，它将一个 URL 路径映射到一个组件。掌握基础路由是理解更高级路由功能的前提。

定义路由

使用 defineRoutes() 函数定义路由表，每条路由至少需要 path 和 component 两个核心字段：

import { defineRoutes } from 'vitarx-router'
import Home from './pages/Home.jsx'
import About from './pages/About.jsx'

const routes = defineRoutes({ path: '/', component: Home }, { path: '/about', component: About })

path 字段

path 是路由的 URL 匹配路径，必须以 / 开头：

// ✅ 正确：以 / 开头
{ path: '/home', component: Home }
{ path: '/user/profile', component: Profile }

// ❌ 错误：不以 / 开头
{ path: 'home', component: Home }

根路径 / 是一个特殊路径，它匹配应用的首页。

component 字段

component 指定路由匹配时要渲染的组件，支持直接引入和懒加载两种方式：

import { lazy } from 'vitarx'
// 方式一：直接引入组件
import Home from './pages/Home.jsx'
{ path: '/', component: Home }

// 方式二：懒加载——按需加载，优化首屏性能
{ path: '/about', component: lazy(() => import('./pages/About.jsx')) }

懒加载使用 lazy() 函数包裹动态 import()，路由仅在首次访问时加载对应组件，有助于减小应用初始包体积。

路由组件

定义好路由后，需要在应用中使用 RouterView 组件来渲染当前路由匹配到的组件：

tsx

import { RouterView, RouterLink } from 'vitarx-router'

function App() {
  return (
    <div>
      <nav>
        <RouterLink to="/">首页</RouterLink>
        <RouterLink to="/about">关于</RouterLink>
      </nav>
      <main>
        <RouterView />
      </main>
    </div>
  )
}

RouterView 的工作流程：

监听当前路由的变化
根据当前路径在路由表中查找匹配的路由记录
渲染匹配路由的 component 字段所指定的组件

默认路由

当子路由使用空字符串 '' 作为路径时，它会在父路径匹配时默认渲染，适合用作索引页面：

const routes = defineRoutes({
  path: '/admin',
  component: AdminLayout,
  children: [
    // 空路径——访问 /admin 时默认渲染
    { path: '', component: AdminDashboard },
    { path: 'users', component: AdminUsers }
  ]
})

访问 /admin 时，AdminLayout 内的 RouterView 会渲染 AdminDashboard 组件；访问 /admin/users 时则渲染 AdminUsers 组件。

404 路由

当用户访问的路径无法匹配任何已定义的路由时，可以通过 onNotFound 钩子统一处理。最常见的做法是在路由表中定义一个 404 页面路由，然后在 onNotFound 中重定向到该路由：

import { createRouter, defineRoutes } from 'vitarx-router'
import Home from './pages/Home.jsx'
import About from './pages/About.jsx'
import NotFound from './pages/NotFound.jsx'

const routes = defineRoutes(
  { path: '/', component: Home },
  { path: '/about', component: About },
  { path: '/not-found', component: NotFound } // 定义 404 页面路由
)

const router = createRouter({
  routes,
  // 路由未匹配时重定向到 404 页面
  onNotFound(target) {
    return '/not-found'
  }
})

onNotFound 钩子接收用户的原始导航意图 target 参数，返回值可以是：

路由路径或名称：重定向到指定路由，如 '/not-found'
NavTarget 对象：携带参数重定向，如 { index: '/not-found', query: { from: target.index } }
RouteLocation 对象：作为未匹配路由的位置对象继续导航流程
void：不处理，导航结果为 notfound 状态

onNotFound 返回的重定向目标必须是已定义的路由，否则会再次触发 onNotFound，导致无限循环直至超出最大重定向次数（16 次）抛出错误。

onNotFound 仅在路由匹配失败时触发。如果路由匹配成功但组件加载失败，不会触发此钩子。

完整示例

下面是一个包含基础路由、默认路由和 404 处理的完整示例：

tsx

import { createRouter, defineRoutes, RouterView, RouterLink } from 'vitarx-router'
import { createApp, lazy } from 'vitarx'

import Home from './pages/Home.jsx'
import About from './pages/About.jsx'
import NotFound from './pages/NotFound.jsx'
import AdminLayout from './pages/admin/Layout.jsx'
import AdminDashboard from './pages/admin/Dashboard.jsx'
import AdminUsers from './pages/admin/Users.jsx'

const routes = defineRoutes(
  { path: '/', component: Home },
  { path: '/about', component: About },
  {
    path: '/admin',
    component: AdminLayout,
    children: [
      { path: '', component: AdminDashboard },
      { path: 'users', component: AdminUsers }
    ]
  },
  { path: '/not-found', component: NotFound }
)

const router = createRouter({
  routes,
  onNotFound() {
    return '/not-found'
  }
})

function App() {
  return (
    <div>
      <nav>
        <RouterLink to="/">首页</RouterLink>
        <RouterLink to="/about">关于</RouterLink>
        <RouterLink to="/admin">管理后台</RouterLink>
      </nav>
      <main>
        <RouterView />
      </main>
    </div>
  )
}

createApp(App).use(router).mount('#app')