创建路由

本页将介绍如何定义路由表、创建路由实例，并将其安装到 Vitarx 应用中。

定义路由表

使用 defineRoutes() 函数定义路由配置数组。每条路由规则包含 path（路径）和 component（组件）两个核心字段：

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

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

defineRoutes() 本质上是一个类型辅助函数，它不会对路由配置做任何转换，仅提供更好的 TypeScript 类型提示。各字段的详细说明请参阅基础路由。

创建路由实例

使用 createRouter() 创建路由实例，传入路由表和可选的配置项：

import { createRouter } from 'vitarx-router'

const router = createRouter({
  routes,
  mode: 'hash', // 路由模式，默认为 'hash'
  base: '/' // 基础路径，默认为 '/'
})

路由模式

mode 选项决定 URL 的表现形式：

'hash'（默认）— 使用 URL 的 hash 部分（#）模拟完整路径，如 http://example.com/#/user/123。无需服务端配置即可使用。
'path' — 使用 HTML5 History API，URL 更加美观，如 http://example.com/user/123。需要服务端配置伪静态规则，否则直接访问子路径会返回 404。

// Hash 模式（默认）
const router1 = createRouter({
  routes,
  mode: 'hash'
})

// History 模式
const router2 = createRouter({
  routes,
  mode: 'path'
})

使用 path 模式时，URL 中没有 # 号，浏览器会向服务器发送真实的路径请求。例如用户直接访问 http://example.com/user/123，服务器会尝试查找 /user/123 对应的文件，但该路径并不存在，导致 404 错误。

因此需要在服务端配置伪静态规则，将所有路径请求重写到应用的入口 HTML 文件，由前端路由接管导航。

Nginx：

nginx

location / {
  try_files $uri $uri/ /index.html;
}

Apache（.htaccess）：

apache

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

Vite 开发服务器已内置 History 回退，开发阶段无需额外配置。

基础路径

如果你的应用部署在子路径下（如 https://example.com/app/），需要通过 base 选项指定基础路径：

const router = createRouter({
  routes,
  base: '/app'
})

URL 后缀

suffix 选项可以为所有路由 URL 添加统一后缀，使地址看起来更像静态站点：

const router = createRouter({
  routes,
  suffix: '.html'
})
// 访问 /about 时，URL 显示为 /about.html

全局 Props 注入

props 选项控制路由参数是否自动注入为组件 props，默认为 true。详见 Props 注入。

滚动行为

scrollBehavior 选项用于自定义路由切换时的滚动位置。详见滚动行为。

导航守卫

beforeEach 和 afterEach 选项可以在创建路由时直接配置守卫，效果等同于创建后调用 router.beforeEach() 和 router.afterEach()。详见全局守卫。

路由未匹配

onNotFound 选项用于处理 404 场景，当用户访问的路径无法匹配任何已定义的路由时触发。详见 404 路由。

错误处理

onError 选项用于捕获导航过程中的错误，例如组件加载失败、守卫抛出异常等：

const router = createRouter({
  routes,
  onError(error, to, from) {
    console.error(`导航失败: #123;error.message}`)
    console.error(`目标路由: #123;to.path}`)
    console.error(`来源路由: #123;from.path}`)
    // 上报错误到监控系统
    reportError(error)
  }
})

安装到应用

创建路由实例后，通过 app.use(router) 将其安装到 Vitarx 应用中：

import { createApp } from 'vitarx'
import App from './App.jsx'
import { router } from './router/index.js'

const app = createApp(App)
app.use(router)
app.mount('#root')

安装后，路由器会在应用中注入全局依赖，组件内即可使用 useRouter() 和 useRoute() 等组合式函数。

完整示例

以下是一个完整的路由应用示例：

tsx

// main.ts
import { createApp } from 'vitarx'
import { createRouter, defineRoutes } from 'vitarx-router'
import App from './App.jsx'
import Home from './pages/Home.jsx'
import About from './pages/About.jsx'

// 1. 定义路由表
const routes = defineRoutes(
  { path: '/', component: Home, meta: { title: '首页' } },
  { path: '/about', component: About, meta: { title: '关于' } }
)

// 2. 创建路由实例
const router = createRouter({
  routes,
  afterEach(to) {
    document.title = to.meta.title || 'My App'
  }
})

// 3. 创建应用并安装路由
createApp(App).use(router).mount('#root')

tsx

// App.jsx
import { RouterView, RouterLink } from 'vitarx-router'

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