路由器工厂

路由器工厂函数用于创建和配置路由器实例。vitarx-router 提供了三种创建方式：自动检测环境的 createRouter()、显式创建 Web 路由的 createWebRouter() 以及用于 SSR/测试的 createMemoryRouter()。此外，defineRoutes() 作为类型辅助函数，帮助定义路由表时获得更好的代码提示。

createRouter()

自动检测运行环境并创建合适的路由器实例。在浏览器环境下创建 WebRouter，在非浏览器环境下（如 Node.js）创建 MemoryRouter。

类型定义

function createRouter(options: RouterOptions, skipEnvWarn?: boolean): Router

参数

参数	类型	说明
options	`RouterOptions`	路由配置选项
skipEnvWarn	`boolean`	是否跳过非浏览器环境警告，默认为 `false`

返回值

类型	说明
`Router`	浏览器环境返回 `WebRouter` 实例，非浏览器环境返回 `MemoryRouter` 实例

详情

当检测到非浏览器环境（window 不存在或 window.scrollTo 不可用）时，createRouter() 会自动降级为 MemoryRouter 并输出一条警告。如果希望抑制此警告（例如在 SSR 场景中已明确知道环境），可以设置 skipEnvWarn 为 true。

示例

import { createRouter } from 'vitarx-router'
import Home from './pages/Home'

const router = createRouter({
  routes: [{ path: '/', component: Home }]
})

// SSR 场景中抑制警告
// const router = createRouter({ routes: [...] }, true)

createWebRouter()

显式创建 Web 路由器实例，基于浏览器 History API 实现路由导航。

类型定义

function createWebRouter(options: RouterOptions, autoInit?: boolean): WebRouter

参数

参数	类型	说明
options	`RouterOptions`	路由配置选项
autoInit	`boolean`	是否自动初始化路由器，默认为 `true`

返回值

类型	说明
`WebRouter`	Web 路由器实例

详情

当 autoInit 为 true（默认）时，路由器会在创建后自动调用 init() 方法，执行初始导航并监听浏览器历史记录变化。

如果需要在路由初始化之前注册导航守卫，可以将 autoInit 设为 false，然后手动调用 router.init()：

const router = createWebRouter({ routes: [...] }, false)
router.beforeEach((to, from) => { /* 守卫逻辑 */ })
router.init() // 手动初始化

示例

import { createWebRouter } from 'vitarx-router'
import Home from './pages/Home'

// 自动初始化
const router = createWebRouter({
  routes: [{ path: '/', component: Home }],
  mode: 'hash'
})

// 手动初始化（先注册守卫）
const router = createWebRouter({ routes: [...] }, false)
router.beforeEach((to, from) => {
  if (to.path.startsWith('/admin')) return false
})
router.init()

createMemoryRouter()

创建内存模式路由器实例，不依赖浏览器 History API，路由历史记录完全保存在内存中。

类型定义

function createMemoryRouter(options: RouterOptions): MemoryRouter

参数

参数	类型	说明
options	`RouterOptions`	路由配置选项

返回值

类型	说明
`MemoryRouter`	内存模式路由器实例

详情

MemoryRouter 适用于以下场景：

SSR（服务端渲染）：服务端没有浏览器 History API
单元测试：隔离测试环境，不依赖浏览器行为

警告：请勿在浏览器端使用 MemoryRouter，因为它与浏览器原生的 History 对象冲突，会导致路由异常。浏览器端请使用 createWebRouter() 或 createRouter()。

示例

import { createMemoryRouter } from 'vitarx-router'
import Home from './pages/Home'

// 用于 SSR 或测试
const router = createMemoryRouter({
  routes: [{ path: '/', component: Home }]
})

defineRoutes()

类型辅助函数，用于定义路由数组时获得完整的 TypeScript 代码提示。

类型定义

function defineRoutes(...routes: Route[]): Route[]

参数

参数	类型	说明
…routes	`Route[]`	路由配置对象列表

返回值

类型	说明
`Route[]`	原样返回传入的路由数组

详情

defineRoutes() 是一个纯类型辅助函数，没有任何运行时效果。它仅用于在编写路由配置时获得 Route 类型的代码补全和类型检查。

示例

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

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

RouteManager

路由注册表管理器，负责路由的注册、查找、匹配和增删操作。它是路由系统的核心数据层，独立于导航逻辑，可单独使用。

构造函数

/**
 * 创建路由注册表管理器
 * @param routes - 原始路由配置数组
 * @param options - 解析选项
 */
new RouteManager(routes: Route[], options?: RouteManagerOptions)

参数	类型	说明
routes	`Route[]`	路由配置数组
options	`RouteManagerOptions`	解析选项（可选）

RouteManagerOptions

interface RouteManagerOptions {
  pattern?: RegExp
  strict?: boolean
  ignoreCase?: boolean
}

属性	类型	默认值	说明
pattern	`RegExp`	`/[^/]+/`	路径动态参数的默认匹配模式
strict	`boolean`	`false`	严格模式。启用后路径末尾的 `/` 会导致匹配失败
ignoreCase	`boolean`	`false`	忽略路径大小写

实例属性

属性	类型	说明
config	`Required<RouteManagerOptions>`	解析后的配置对象（只读）
routes	`Set<RouteRecord>`	所有已注册的路由记录集合
staticRoutes	`Map<string, RouteRecord>`	静态路由映射（路径 → 路由记录）
namedRoutes	`Map<RouteName, RouteRecord>`	命名路由映射（名称 → 路由记录）
dynamicRoutes	`Map<number, DynamicRouteRecord[]>`	动态路由映射（按路径段长度分组）
aliasRoutes	`Map<string, RouteRecord>`	别名路由映射（别名路径 → 路由记录）

请勿直接操作以上属性，以免造成路由状态不一致。请通过实例方法进行操作。

实例方法

routeManager.findByPath()

根据路径精确查找路由，不支持动态匹配。

routeManager.findByPath(path: RoutePath): RouteRecord | null

routeManager.findByName()

根据名称查找路由。

routeManager.findByName(name: RouteName): RouteRecord | null

routeManager.find()

统一查找路由。以 / 开头按路径查找，否则按名称查找。

routeManager.find(target: RouteIndex): RouteRecord | null

routeManager.matchByPath()

根据路径匹配路由，支持动态参数解析。匹配流程：静态路由精确匹配 → 别名路由精确匹配 → 动态路由正则匹配。

routeManager.matchByPath(path: RoutePath): RouteMatchResult | null

routeManager.matchByName()

根据名称匹配路由并校验参数。必填参数缺失或格式不匹配时返回 null。

routeManager.matchByName(name: RouteName, params?: Record<string, string | number>): RouteMatchResult | null

routeManager.match()

统一匹配路由。以 / 开头按路径匹配，否则按名称匹配。

routeManager.match(index: RouteIndex, params?: Record<string, string | number>): RouteMatchResult | null

routeManager.addRoute()

添加路由。支持指定父路由，将新路由注册为其子路由。

routeManager.addRoute(route: Route, parent?: RouteIndex): void

routeManager.removeRoute()

删除指定路由。仅删除单条路由记录，不会级联删除子路由。

routeManager.removeRoute(index: RouteIndex): boolean

routeManager.clearRoutes()

清空所有路由映射。谨慎使用，清空后所有路由信息将丢失。

routeManager.clearRoutes(): void

RouteMatchResult

路由匹配结果。

interface RouteMatchResult {
  path: RoutePath
  route: RouteRecord
  params: URLParams
}

属性	类型	说明
path	`RoutePath`	匹配的原始路径
route	`RouteRecord`	匹配的路由记录
params	`URLParams`	解析后的路径参数键值对

作为 routes 选项使用

createRouter 的 routes 选项支持直接传入 RouteManager 实例，适用于需要共享路由注册表或自定义路由解析配置的场景：

import { createRouter, RouteManager } from 'vitarx-router'

// 创建自定义配置的路由注册表
const manager = new RouteManager(
  [
    { path: '/', component: Home },
    { path: '/user/{id}', component: User }
  ],
  {
    strict: true, // 严格匹配末尾斜杠
    ignoreCase: true // 忽略路径大小写
  }
)

// 直接传入 RouteManager 实例
const router = createRouter({ routes: manager })

当 routes 传入 RouteManager 实例时，路由器不会重新解析路由配置，而是直接使用该实例的注册表。这允许你在创建路由器之前对路由注册表进行精细控制。

RouterOptions

路由器配置选项接口，所有路由器工厂函数共享此配置类型。

类型定义

interface RouterOptions {
  routes: Route[] | RouteManager
  mode?: 'hash' | 'path'
  base?: `/#123;string}`
  suffix?: `.#123;string}`
  props?: boolean | InjectPropsHandler
  scrollBehavior?: BeforeScrollCallback
  beforeEach?: NavigationGuard | NavigationGuard[]
  afterEach?: AfterCallback | AfterCallback[]
  onNotFound?: NotFoundHandler | NotFoundHandler[]
  onError?: NavErrorListener | NavErrorListener[]
}

属性说明

属性	类型	默认值	说明
routes	`Route[] \| RouteManager`	—	必填。路由规则数组或路由管理器实例
mode	`'hash' \| 'path'`	`'hash'`	URL 模式。`hash` 使用 URL hash 模式，`path` 使用 HTML5 History 模式
base	`/${string}`	`'/'`	路由基础路径，通常用于部署到子目录时指定
suffix	`.${string}`	—	强制 URL 后缀，例如 `'.html'`，使 URL 看起来更像静态站点
props	`boolean \| InjectPropsHandler`	`true`	全局 props 注入配置，控制路由参数是否自动注入为组件 props
scrollBehavior	`BeforeScrollCallback`	—	自定义路由切换时的滚动行为
beforeEach	`NavigationGuard \| NavigationGuard[]`	—	全局前置守卫，在路由匹配成功后、导航确认前执行
afterEach	`AfterCallback \| AfterCallback[]`	—	全局后置钩子，在导航成功结束后执行
onNotFound	`NotFoundHandler \| NotFoundHandler[]`	—	路由未匹配（404）时触发的回调
onError	`NavErrorListener \| NavErrorListener[]`	—	导航过程中发生错误时触发的回调

参考：创建路由

WARNING

INFO