vitarx-router 4.0.0-beta.0 → 4.0.0-beta.1

package/README.md

@@ -7,6 +7,24 @@ Vitarx 前端框架官方路由解决方案，提供声明式路由配置、导
 [![GitHub](https://img.shields.io/badge/fork-999999?style=social&logo=github)](https://github.com/vitarx-lib/router)
 [![Documentation](https://img.shields.io/badge/docs-vitarx--router-blue)](https://router.vitarx.cn)
 
+## 目录
+
+- [特性](#特性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [路由模式](#路由模式)
+- [路由配置](#路由配置)
+- [导航方法](#导航方法)
+- [导航守卫](#导航守卫)
+- [组件](#组件)
+- [组合式 API](#组合式-api)
+- [路由对象](#路由对象)
+- [路由选项](#路由选项)
+- [TypeScript 支持](#typescript-支持)
+- [文件路由](#文件路由)
+- [API 参考](#api-参考)
+- [License](#license)
+
 ## 特性
 
 - 🚀 **多种路由模式** - 支持 Hash、History、Memory 三种路由模式
@@ -15,7 +33,9 @@ Vitarx 前端框架官方路由解决方案，提供声明式路由配置、导
 - 🔄 **动态路由** - 支持动态参数、正则约束、可选参数
 - 📦 **懒加载** - 内置组件懒加载支持
 - 🎯 **TypeScript** - 完整的类型支持
-- � **滚动行为** - 可自定义路由切换时的滚动行为
+- 📜 **滚动行为** - 可自定义路由切换时的滚动行为
+- 🔄 **路由别名** - 支持多路径映射到同一路由
+- 🎨 **命名视图** - 支持多视图布局
 
 ## 安装
 
@@ -117,9 +137,10 @@ location / {
 不修改 URL，适用于非浏览器环境或测试场景。
 
 ```typescript
-createRouter({
-  routes,
-  mode: 'memory'
+import { createMemoryRouter } from 'vitarx-router'
+
+createMemoryRouter({
+  routes
 })
 ```
 
@@ -141,6 +162,8 @@ const routes = defineRoutes(
 
 ### 动态路由
 
+支持动态参数、可选参数和正则约束：
+
 ```typescript
 const routes = defineRoutes(
   // 基本动态参数
@@ -158,6 +181,11 @@ const routes = defineRoutes(
 )
 ```
 
+**参数说明：**
+- `{id}` - 必填参数
+- `{id?}` - 可选参数
+- `pattern` - 正则约束，用于精确匹配
+
 ### 嵌套路由
 
 ```typescript
@@ -184,8 +212,27 @@ const routes = defineRoutes({
 router.push({ index: 'user-detail', params: { id: '123' } })
 ```
 
+### 路由别名
+
+支持单个或多个别名：
+
+```typescript
+const routes = defineRoutes(
+  // 单个别名
+  { path: '/home', component: Home, alias: '/main' },
+  
+  // 多个别名
+  { path: '/users', component: Users, alias: ['/members', '/people'] },
+  
+  // 动态路由别名
+  { path: '/users/{id}', component: User, alias: '/members/{id}' }
+)
+```
+
 ### 重定向
 
+支持字符串、对象和函数形式的重定向：
+
 ```typescript
 const routes = defineRoutes(
   // 字符串重定向
@@ -219,6 +266,8 @@ const routes = defineRoutes({
 
 ### 命名视图
 
+支持多个命名视图：
+
 ```jsx
 const routes = defineRoutes({
   path: '/settings',
@@ -229,12 +278,14 @@ const routes = defineRoutes({
 });
 
 // 模板中使用
-<RouterView />;
+<RouterView />
 <RouterView name="sidebar" />
 ```
 
 ### 路由参数注入
 
+支持多种方式向组件注入参数：
+
 ```typescript
 const routes = defineRoutes(
   // 注入动态参数到组件 props
@@ -275,8 +326,16 @@ router.push({ index: '/search', query: { q: 'keyword' } })
 
 // 带 hash
 router.push({ index: '/about', hash: '#section' })
+
+// 也支持直接传入路径字符串
+router.push('/user/123')
+
+// 或传入 RouteLocation 对象
+router.push(routeLocation)
 ```
 
+**返回值：** `Promise<NavigateResult>`
+
 ### replace
 
 替换当前路由，不添加历史记录。
@@ -285,6 +344,8 @@ router.push({ index: '/about', hash: '#section' })
 router.replace({ index: '/login' })
 ```
 
+**返回值：** `Promise<NavigateResult>`
+
 ### go
 
 前进/后退指定步数。
@@ -305,6 +366,48 @@ router.back()    // 等同于 router.go(-1)
 router.forward() // 等同于 router.go(1)
 ```
 
+### 导航结果
+
+所有导航方法返回 `NavigateResult` 对象：
+
+```typescript
+interface NavigateResult {
+  state: NavState      // 导航状态
+  message: string      // 状态描述
+  to: RouteLocation | null   // 目标路由
+  from: RouteLocation        // 来源路由
+  redirectFrom?: RouteLocation  // 重定向来源
+}
+```
+
+**导航状态枚举：**
+
+| 状态           | 值  | 说明       |
+|--------------|----|----------|
+| `success`    | 1  | 导航成功     |
+| `aborted`    | 2  | 导航被守卫阻止  |
+| `cancelled`  | 4  | 导航被新导航取消 |
+| `duplicated` | 8  | 重复导航     |
+| `notfound`   | 16 | 路由未匹配    |
+
+**检查导航状态：**
+
+```typescript
+import { hasSuccess, hasState, NavState } from 'vitarx-router'
+
+const result = await router.push({ index: '/home' })
+
+// 检查是否成功
+if (hasSuccess(result)) {
+  console.log('导航成功')
+}
+
+// 检查特定状态
+if (hasState(result, NavState.aborted)) {
+  console.log('导航被阻止')
+}
+```
+
 ---
 
 ## 导航守卫
@@ -329,6 +432,15 @@ router.beforeEach((to, from) => {
 })
 ```
 
+**守卫返回值：**
+
+| 返回值              | 说明       |
+|------------------|----------|
+| `true` / `void`  | 继续导航     |
+| `false`          | 取消导航     |
+| `string`         | 重定向到指定路径 |
+| `NavigateTarget` | 重定向到目标路由 |
+
 ### 全局后置守卫
 
 在路由跳转后执行，可用于更新页面标题等。
@@ -350,21 +462,72 @@ const routes = defineRoutes({
     if (!isAdmin()) {
       return { index: '/' }
     }
-  },
-  afterEnter: (to, from) => {
-    console.log('进入管理页面')
   }
 })
 ```
 
-### 守卫返回值
+支持数组形式的多个守卫：
 
-| 返回值              | 说明       |
-|------------------|----------|
-| `true` / `void`  | 继续导航     |
-| `false`          | 取消导航     |
-| `string`         | 重定向到指定路径 |
-| `NavigateTarget` | 重定向到目标路由 |
+```typescript
+const routes = defineRoutes({
+  path: '/admin',
+  component: Admin,
+  beforeEnter: [guard1, guard2]
+})
+```
+
+### 组件内守卫
+
+在组件内注册离开守卫和更新钩子：
+
+```typescript
+import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vitarx-router'
+
+export default function UserComponent() {
+  // 离开守卫
+  onBeforeRouteLeave((to, from) => {
+    const answer = window.confirm('确定要离开吗？')
+    if (!answer) return false
+  })
+  
+  // 更新钩子
+  onBeforeRouteUpdate((to, from) => {
+    console.log('路由参数更新', to.params)
+  })
+}
+```
+
+### 错误处理
+
+```typescript
+const router = createRouter({
+  routes,
+  onError: (error, to, from) => {
+    console.error('路由错误:', error)
+  }
+})
+```
+
+### 404 处理
+
+```typescript
+const router = createRouter({
+  routes,
+  onNotFound: (target) => {
+    console.log('未找到路由:', target)
+    return { index: '/404' }  // 重定向到 404 页面
+  }
+})
+```
+
+或使用 `missing` 组件：
+
+```typescript
+const router = createRouter({
+  routes,
+  missing: NotFoundComponent
+})
+```
 
 ---
 
@@ -381,16 +544,23 @@ const routes = defineRoutes({
 // 命名视图
 <RouterView name="sidebar" />
 
-// 带过渡效果
+// 自定义渲染
 <RouterView>
-  {(Component) => (
+  {(component, props, route) => (
     <Transition name="fade">
-      <Component />
+      <Dynamic is={component} {...props} memo />
     </Transition>
   )}
 </RouterView>
 ```
 
+**Props：**
+
+| 属性         | 类型         | 默认值         | 说明      |
+|------------|------------|-------------|---------|
+| `name`     | `string`   | `'default'` | 命名视图名称  |
+| `children` | `function` | -           | 自定义渲染函数 |
+
 ### RouterLink
 
 声明式导航链接。
@@ -412,10 +582,37 @@ const routes = defineRoutes({
 // 替换模式
 <RouterLink to="/about" replace>关于</RouterLink>
 
-// 激活匹配
-<RouterLink to="/" active="strict">首页</RouterLink>
+// 激活类名
+<RouterLink 
+  to="/" 
+  activeClass="active"
+  exactActiveClass="exact-active"
+>
+  首页
+</RouterLink>
+
+// 禁用状态
+<RouterLink to="/about" disabled>禁用链接</RouterLink>
+
+// 外部链接
+<RouterLink to="https://example.com" target="_blank">
+  外部链接
+</RouterLink>
 ```
 
+**Props：**
+
+| 属性                 | 类型                 | 默认值      | 说明                       |
+|--------------------|--------------------|----------|--------------------------|
+| `to`               | `string \| object` | -        | 目标路由                     |
+| `replace`          | `boolean`          | `false`  | 是否替换历史记录                 |
+| `disabled`         | `boolean`          | `false`  | 是否禁用                     |
+| `activeClass`      | `string`           | -        | 激活时应用的类名                 |
+| `exactActiveClass` | `string`           | -        | 精确匹配时应用的类名               |
+| `ariaCurrentValue` | `string`           | `'page'` | aria-current 属性值         |
+| `callback`         | `function`         | -        | 导航完成回调                   |
+| `viewTransition`   | `boolean`          | `false`  | 是否使用 View Transition API |
+
 ---
 
 ## 组合式 API
@@ -461,6 +658,41 @@ export default function UserDetail() {
 }
 ```
 
+**参数：**
+- `global` - 是否返回全局路由对象，默认 `false`
+
+### useLink
+
+创建链接助手，用于自定义导航逻辑。
+
+```jsx
+import { useLink } from 'vitarx-router'
+
+export default function CustomLink({ to }) {
+  const { href, route, isActive, isExactActive, navigate } = useLink({ to })
+  
+  return (
+    <a 
+      href={href.value} 
+      onClick={navigate}
+      class={{ active: isActive.value, 'exact-active': isExactActive.value }}
+    >
+      <slot />
+    </a>
+  )
+}
+```
+
+**返回值：**
+
+| 属性              | 类型                                | 说明          |
+|-----------------|-----------------------------------|-------------|
+| `href`          | `Computed<string>`                | 链接 href 属性值 |
+| `route`         | `Computed<RouteLocation \| null>` | 匹配的路由信息     |
+| `isActive`      | `Computed<boolean>`               | 是否部分匹配当前路由  |
+| `isExactActive` | `Computed<boolean>`               | 是否精确匹配当前路由  |
+| `navigate`      | `function`                        | 执行导航        |
+
 ---
 
 ## 路由对象
@@ -469,28 +701,40 @@ export default function UserDetail() {
 
 当前路由信息对象。
 
-| 属性         | 类型                       | 说明                |
-|------------|--------------------------|-------------------|
-| `path`     | `string`                 | 路由路径              |
-| `fullPath` | `string`                 | 完整路径（含查询参数和 hash） |
-| `params`   | `Record<string, any>`    | 路由参数              |
-| `query`    | `Record<string, string>` | 查询参数              |
-| `hash`     | `string`                 | URL hash          |
-| `name`     | `string`                 | 路由名称              |
-| `meta`     | `RouteMetaData`          | 路由元数据             |
-| `matched`  | `RouteNormalized[]`      | 匹配的路由记录           |
-
-### NavigateResult
-
-导航结果对象。
-
-| 属性             | 类型                      | 说明    |
-|----------------|-------------------------|-------|
-| `status`       | `NavigateStatus`        | 导航状态  |
-| `message`      | `string`                | 状态描述  |
-| `to`           | `ReadonlyRouteLocation` | 目标路由  |
-| `from`         | `ReadonlyRouteLocation` | 来源路由  |
-| `redirectFrom` | `NavigateTarget`        | 重定向来源 |
+```typescript
+interface RouteLocation {
+  href: string                           // 完整 href
+  path: RoutePath                        // 路由路径
+  hash: URLHash | ''                     // URL hash
+  params: URLParams                      // 路由参数
+  query: URLQuery                        // 查询参数
+  meta: RouteMetaData                    // 路由元数据
+  matched: RouteRecord[]                 // 匹配的路由记录
+  redirectFrom?: RouteLocation           // 重定向来源
+}
+```
+
+### RouteRecord
+
+解析后的路由记录。
+
+```typescript
+interface RouteRecord {
+  isGroup: boolean                       // 是否为分组路由
+  parent?: RouteRecord                   // 父级路由记录
+  path: RoutePath                        // 路由路径
+  aliases?: RoutePath[]                  // 别名路径列表
+  name?: RouteName                       // 路由名称
+  meta?: RouteMetaData                   // 路由元数据
+  props?: NamedInjectProps               // 参数注入配置
+  redirect?: Route['redirect']           // 重定向配置
+  component?: NamedRouteComponent        // 视图组件
+  beforeEnter?: NavigationGuard[]        // 路由守卫
+  pattern?: ResolvedPattern[]            // 动态参数匹配模式
+  params?: URLParams                     // 路由参数
+  query?: URLQuery                       // 查询参数
+}
+```
 
 ---
 
@@ -498,19 +742,32 @@ export default function UserDetail() {
 
 ### RouterOptions
 
-| 选项               | 类型                                   | 默认值        | 说明         |
-|------------------|--------------------------------------|------------|------------|
-| `routes`         | `Route[]`                            | -          | 路由配置数组（必填） |
-| `mode`           | `'hash' \| 'path' \| 'memory'`       | `'hash'`   | 路由模式       |
-| `base`           | `string`                             | `'/'`      | 基础路径       |
-| `strict`         | `boolean`                            | `false`    | 是否区分大小写    |
-| `suffix`         | `string \| string[] \| '*' \| false` | `'*'`      | URL 后缀匹配   |
-| `defaultSuffix`  | `string`                             | `''`       | 默认后缀       |
-| `pattern`        | `RegExp`                             | `/[\w.]+/` | 动态参数默认匹配模式 |
-| `scrollBehavior` | `ScrollBehavior \| Function`         | `'auto'`   | 滚动行为       |
-| `beforeEach`     | `BeforeEnterCallback`                | -          | 全局前置守卫     |
-| `afterEach`      | `AfterEnterCallback`                 | -          | 全局后置守卫     |
-| `missing`        | `RouteComponent`                     | -          | 未匹配时渲染的组件  |
+```typescript
+interface RouterOptions {
+  routes: Route[] | RouteManager         // 路由配置（必填）
+  mode?: 'hash' | 'path'                 // 路由模式，默认 'hash'
+  base?: `/${string}`                    // 基础路径，默认 '/'
+  suffix?: `.${string}`                  // URL 后缀
+  props?: boolean | InjectPropsHandler   // 全局 props 注入
+  scrollBehavior?: BeforeScrollCallback  // 滚动行为
+  beforeEach?: NavigationGuard | NavigationGuard[]   // 全局前置守卫
+  afterEach?: AfterCallback | AfterCallback[]        // 全局后置守卫
+  onNotFound?: NotFoundHandler | NotFoundHandler[]   // 404 处理
+  onError?: NavErrorListener | NavErrorListener[]    // 错误处理
+  missing?: RouteViewComponent           // 未匹配时渲染的组件
+}
+```
+
+### RouteManagerOptions
+
+```typescript
+interface RouteManagerOptions {
+  pattern?: RegExp           // 动态参数默认匹配模式，默认 /[^/]+/
+  strict?: boolean           // 是否严格匹配尾部斜杠，默认 false
+  ignoreCase?: boolean       // 是否忽略大小写，默认 false
+  fallbackIndex?: boolean    // 是否启用索引回退匹配，默认 false
+}
+```
 
 ---
 
@@ -535,12 +792,13 @@ declare module 'vitarx-router' {
 declare module 'vitarx-router' {
   interface RouteIndexMap {
     'user-detail': { params: { id: string } }
-    'search': { query: { q: string } }
+    '/search': { query: { q: string } }
   }
 }
 
 // 使用时会有类型提示
 router.push({ index: 'user-detail', params: { id: '123' } })
+router.push({ index: '/search', query: { q: 'keyword' } })
 ```
 
 ---
@@ -567,7 +825,7 @@ export default defineConfig({
 ### 使用生成的路由
 
 ```typescript
-import { routes } from 'vitarx-router/auto-routes'
+import routes from 'virtual:vitarx-router:routes'
 import { createRouter } from 'vitarx-router'
 
 export const router = createRouter({ routes })
@@ -581,36 +839,64 @@ export const router = createRouter({ routes })
 
 ### 助手函数
 
-| 函数                                    | 说明       |
-|---------------------------------------|----------|
-| `createRouter(options)`               | 创建路由器实例  |
-| `defineRoutes(...routes)`             | 定义路由表    |
-| `defineRoute(route)`                  | 定义单个路由   |
-| `useRouter()`                         | 获取路由器实例  |
-| `useRoute()`                          | 获取当前路由信息 |
-| `hasNavigationStatus(result, status)` | 检查导航状态   |
+| 函数                                     | 说明              |
+|----------------------------------------|-----------------|
+| `createRouter(options)`                | 创建路由器实例         |
+| `createWebRouter(options)`             | 创建 Web 模式路由器    |
+| `createMemoryRouter(options)`          | 创建 Memory 模式路由器 |
+| `createRouteManager(routes, options?)` | 创建路由管理器         |
+| `defineRoutes(...routes)`              | 定义路由表           |
+| `useRouter()`                          | 获取路由器实例         |
+| `useRoute(global?)`                    | 获取当前路由信息        |
+| `useLink(options)`                     | 创建链接助手          |
+| `onBeforeRouteLeave(guard)`            | 注册离开守卫          |
+| `onBeforeRouteUpdate(callback)`        | 注册更新钩子          |
+| `hasSuccess(result)`                   | 检查导航是否成功        |
+| `hasState(result, status)`             | 检查导航状态          |
 
 ### Router 实例方法
 
-| 方法                 | 说明        |
-|--------------------|-----------|
-| `push(options)`    | 跳转到新路由    |
-| `replace(options)` | 替换当前路由    |
-| `go(delta)`        | 前进/后退指定步数 |
-| `back()`           | 后退一步      |
-| `forward()`        | 前进一步      |
-| `scrollTo(target)` | 滚动到指定位置   |
-| `initialize()`     | 初始化路由器    |
+| 方法                              | 说明        |
+|---------------------------------|-----------|
+| `push(target)`                  | 跳转到新路由    |
+| `replace(target)`               | 替换当前路由    |
+| `go(delta)`                     | 前进/后退指定步数 |
+| `back()`                        | 后退一步      |
+| `forward()`                     | 前进一步      |
+| `addRoute(route, parent?)`      | 添加路由      |
+| `removeRoute(index)`            | 移除路由      |
+| `hasRoute(index)`               | 检查路由是否存在  |
+| `matchRoute(target)`            | 匹配路由      |
+| `buildUrl(path, query?, hash?)` | 构建 URL    |
+| `resolveComponents(route?)`     | 解析异步组件    |
+| `waitViewRender(navResult?)`    | 等待视图渲染    |
+| `isReady()`                     | 等待路由器就绪   |
+| `beforeEach(guard)`             | 添加前置守卫    |
+| `afterEach(callback)`           | 添加后置回调    |
+| `destroy()`                     | 销毁路由器     |
 
 ### Router 实例属性
 
-| 属性               | 说明            |
-|------------------|---------------|
-| `route`          | 当前路由信息（只读响应式） |
-| `options`        | 路由器配置选项       |
-| `mode`           | 路由模式          |
-| `isBrowser`      | 是否浏览器环境       |
-| `scrollBehavior` | 滚动行为          |
+| 属性        | 类型                              | 说明            |
+|-----------|---------------------------------|---------------|
+| `route`   | `ReadonlyObject<RouteLocation>` | 当前路由信息（只读响应式） |
+| `routes`  | `RouteRecord[]`                 | 所有注册的路由记录     |
+| `config`  | `ResolvedRouterConfig`          | 路由器配置         |
+| `manager` | `RouteManager`                  | 路由管理器实例       |
+
+### RouteManager 实例方法
+
+| 方法                           | 说明      |
+|------------------------------|---------|
+| `findByPath(path)`           | 按路径查找路由 |
+| `findByName(name)`           | 按名称查找路由 |
+| `find(index)`                | 统一查找方法  |
+| `matchByPath(path)`          | 按路径匹配路由 |
+| `matchByName(name, params?)` | 按名称匹配路由 |
+| `match(index, params?)`      | 统一匹配方法  |
+| `addRoute(route, parent?)`   | 添加路由    |
+| `removeRoute(index)`         | 移除路由    |
+| `clearRoutes()`              | 清空所有路由  |
 
 ---