vitarx-router 4.0.0-beta.2 → 4.0.0-beta.21

package/README.md

@@ -10,7 +10,7 @@ Vitarx 前端框架官方路由解决方案，提供声明式路由配置、导
 ## 特性
 
 - 🚀 **多种路由模式** - 支持 Hash、History、Memory 三种路由模式
-- 📁 **文件路由** - 基于 Vite 插件的文件系统路由自动生成
+- 📁 **文件路由** - 基于 Vite 插件的文件系统路由自动生成，HMR 热更新支持
 - 🔒 **导航守卫** - 完整的路由守卫机制，支持权限控制
 - 🔄 **动态路由** - 支持动态参数、正则约束、可选参数
 - 📦 **懒加载** - 内置组件懒加载支持
@@ -112,6 +112,25 @@ import { createMemoryRouter } from 'vitarx-router'
 createMemoryRouter({ routes })
 ```
 
+### 手动初始化
+
+默认情况下，`createRouter` / `createWebRouter` 会在创建实例后自动初始化路由器（执行初始导航并注册浏览器事件监听）。如果需要延迟初始化，可以使用 `createWebRouter` 并将第二个参数 `autoInit` 设为 `false`，然后手动调用 `init()` 方法。
+
+```typescript
+const router = createWebRouter({ routes }, false)
+
+// 在合适的时机手动初始化
+router.init()
+```
+
+**适用场景：**
+
+- 需要在初始化前注册导航守卫
+- 需要在初始化前完成异步配置加载
+- 需要精确控制初始化时机
+
+> **注意：** `autoInit` 仅对 Web 路由器有效。
+
 ## 路由配置
 
 ### 基本路由
@@ -403,7 +422,10 @@ import VitarxRouter from 'vitarx-router/vite'
 export default defineConfig({
   plugins: [
     VitarxRouter({
-      pagesDir: 'src/pages'
+      pages: 'src/pages',
+      pathStrategy: 'kebab',
+      importMode: 'lazy',
+      dts: 'router.d.ts'
     })
   ]
 })
@@ -418,7 +440,9 @@ import { createRouter } from 'vitarx-router'
 export const router = createRouter({ routes })
 ```
 
-详细配置请参考 [Vite 插件文档](src/plugin-vite/README.md)。
+### 文件路由配置选项
+
+请参考 [File Router 文档](src/file-router/README.md)。
 
 ## TypeScript 支持
 
@@ -463,20 +487,21 @@ declare module 'vitarx-router' {
 
 ### Router 实例方法
 
-| 方法                         | 说明        |
-|----------------------------|-----------|
-| `push(target)`             | 跳转到新路由    |
-| `replace(target)`          | 替换当前路由    |
-| `go(delta)`                | 前进/后退指定步数 |
-| `back()`                   | 后退一步      |
-| `forward()`                | 前进一步      |
-| `addRoute(route, parent?)` | 添加路由      |
-| `removeRoute(index)`       | 移除路由      |
-| `hasRoute(index)`          | 检查路由是否存在  |
-| `matchRoute(target)`       | 匹配路由      |
-| `beforeEach(guard)`        | 添加前置守卫    |
-| `afterEach(callback)`      | 添加后置回调    |
-| `destroy()`                | 销毁路由器     |
+| 方法                         | 说明                    |
+|----------------------------|-----------------------|
+| `init()`                   | 手动初始化路由器（仅 WebRouter） |
+| `push(target)`             | 跳转到新路由                |
+| `replace(target)`          | 替换当前路由                |
+| `go(delta)`                | 前进/后退指定步数             |
+| `back()`                   | 后退一步                  |
+| `forward()`                | 前进一步                  |
+| `addRoute(route, parent?)` | 添加路由                  |
+| `removeRoute(index)`       | 移除路由                  |
+| `hasRoute(index)`          | 检查路由是否存在              |
+| `matchRoute(target)`       | 匹配路由                  |
+| `beforeEach(guard)`        | 添加前置守卫                |
+| `afterEach(callback)`      | 添加后置回调                |
+| `destroy()`                | 销毁路由器                 |
 
 ### Router 实例属性
 

package/dist/{plugin-vite/auto-routes → auto-routes}/handleHotUpdate.d.ts

@@ -1,4 +1,4 @@
-import type { Route, Router } from '../../core/index.js';
+import type { Route, Router } from '../core/index.js';
 /**
  * 处理路由热更新函数
  *

package/dist/components/RouterView.js

@@ -12,7 +12,7 @@ import { __ROUTER_VIEW_DEPTH_KEY__, useRouter } from '../core/index.js';
  * @returns {View} 返回渲染的视图
  */
 export function RouterView(props) {
-    const { children, name = 'default' } = props;
+    const { children } = props;
     // 获取路由实例
     const router = useRouter();
     // 获取父级 index
@@ -20,6 +20,7 @@ export function RouterView(props) {
     const index = parentIndex + 1; // 计算当前视图的索引
     provide(__ROUTER_VIEW_DEPTH_KEY__, index); // 向子组件提供当前索引
     // 匹配的路由线路
+    const viewName = computed(() => props.name || 'default');
     const matchedRoute = computed(() => {
         return router.route.matched[index] ?? null;
     });
@@ -28,8 +29,7 @@ export function RouterView(props) {
         const currentRoute = matchedRoute.value;
         if (!currentRoute)
             return null;
-        const name = props.name || 'default'; // 获取视图名称，默认为 'default'
-        let injectProps = currentRoute.props?.[name] ?? router.config.props ?? false;
+        let injectProps = currentRoute.props?.[viewName.value] ?? router.config.props ?? true;
         if (injectProps === false)
             return null; // 如果属性为 false，返回null
         if (injectProps === true && currentRoute.pattern) {
@@ -52,7 +52,7 @@ export function RouterView(props) {
         const route = matchedRoute.value; // 获取匹配的路由记录
         if (!route)
             return null;
-        return route.component?.[name] ?? null;
+        return route.component?.[viewName.value] ?? null;
     });
     // 如果传入了 children 函数，则调用并返回其结果
     if (isFunction(children)) {
@@ -61,6 +61,7 @@ export function RouterView(props) {
         }
         catch (e) {
             logger.error('[RouterView] Error occurred while executing children function', e);
+            return createCommentView(`router-view:error`);
         }
     }
     let lastView = null;

package/dist/core/common/constant.d.ts

@@ -2,12 +2,11 @@
  * 导航状态
  *
  * 枚举值：
- * 0. success: 导航成功
- * 1. aborted: 导航被阻止
- * 2. cancelled: 导航被取消
- * 3. duplicated: 重复导航
- * 4. notfound: 路由未匹配
- * 5. exception: 捕获到异常
+ * 1. success: 导航成功
+ * 2. aborted: 导航被阻止
+ * 4. cancelled: 导航被取消
+ * 8. duplicated: 重复导航
+ * 16. notfound: 路由未匹配
  */
 export declare enum NavState {
     /**

package/dist/core/common/constant.js

@@ -2,12 +2,11 @@
  * 导航状态
  *
  * 枚举值：
- * 0. success: 导航成功
- * 1. aborted: 导航被阻止
- * 2. cancelled: 导航被取消
- * 3. duplicated: 重复导航
- * 4. notfound: 路由未匹配
- * 5. exception: 捕获到异常
+ * 1. success: 导航成功
+ * 2. aborted: 导航被阻止
+ * 4. cancelled: 导航被取消
+ * 8. duplicated: 重复导航
+ * 16. notfound: 路由未匹配
  */
 export var NavState;
 (function (NavState) {

package/dist/core/common/utils.js

@@ -108,7 +108,8 @@ export function resolveNavTarget(index) {
         return {
             index: index.matched.at(-1)?.name || index.path, // 使用最后一个匹配的路由名称，如果没有则使用路径
             params: index.params, // 路由参数
-            query: index.query // 查询参数
+            query: index.query, // 查询参数
+            hash: index.hash // 哈希值
         };
     }
     throw new Error('Invalid navigation target');

package/dist/core/router/checkOptions.d.ts

@@ -0,0 +1,11 @@
+import type { RouterOptions } from '../types/index.js';
+/**
+ * 检查路由器配置选项的合法性
+ *
+ * 在开发环境下对用户传入的 RouterOptions 进行校验，
+ * 确保必填字段存在、类型正确、值合法。
+ *
+ * @param options - 用户传入的路由器配置对象
+ * @throws {Error} 当选项不合法时抛出错误
+ */
+export declare const checkRouterOptions: (options: RouterOptions) => void;

package/dist/core/router/checkOptions.js

@@ -0,0 +1,119 @@
+import { isComponent, isFunction } from 'vitarx';
+import { RouteManager } from './manager.js';
+/**
+ * 检查路由器配置选项的合法性
+ *
+ * 在开发环境下对用户传入的 RouterOptions 进行校验，
+ * 确保必填字段存在、类型正确、值合法。
+ *
+ * @param options - 用户传入的路由器配置对象
+ * @throws {Error} 当选项不合法时抛出错误
+ */
+export const checkRouterOptions = (options) => {
+    // 1. 检查 options 是否为对象
+    if (typeof options !== 'object' || options === null) {
+        throw new Error('[Router] Router options must be an object.');
+    }
+    // 2. 检查 routes 是否存在且为有效类型
+    if (!('routes' in options) || options.routes === undefined) {
+        throw new Error('[Router] "routes" is a required option.');
+    }
+    if (!Array.isArray(options.routes) && !(options.routes instanceof RouteManager)) {
+        throw new Error('[Router] "routes" must be an array or a RouteManager instance.');
+    }
+    // 3. 检查 mode 的值是否合法
+    if ('mode' in options && options.mode !== undefined) {
+        const validModes = ['hash', 'path'];
+        if (!validModes.includes(options.mode)) {
+            throw new Error(`[Router] "mode" must be one of: ${validModes.join(', ')}. Received "${options.mode}".`);
+        }
+    }
+    // 4. 检查 base 的格式
+    if ('base' in options && options.base !== undefined) {
+        if (typeof options.base !== 'string') {
+            throw new Error('[Router] "base" must be a string.');
+        }
+        if (!options.base.startsWith('/')) {
+            throw new Error('[Router] "base" must start with a slash (/).');
+        }
+    }
+    // 5. 检查 suffix 的格式
+    if ('suffix' in options && options.suffix !== undefined) {
+        if (typeof options.suffix !== 'string') {
+            throw new Error('[Router] "suffix" must be a string.');
+        }
+        if (!options.suffix.startsWith('.')) {
+            throw new Error('[Router] "suffix" must start with a dot (.).');
+        }
+        if (options.suffix === '.') {
+            throw new Error('[Router] "suffix" cannot be just a dot, please provide a valid extension like ".html".');
+        }
+    }
+    // 6. 检查 props 的类型
+    if ('props' in options && options.props !== undefined) {
+        if (typeof options.props !== 'boolean' && !isFunction(options.props)) {
+            throw new Error('[Router] "props" must be a boolean or function.');
+        }
+    }
+    // 7. 检查 scrollBehavior 的类型
+    if ('scrollBehavior' in options && options.scrollBehavior !== undefined) {
+        if (!isFunction(options.scrollBehavior)) {
+            throw new Error('[Router] "scrollBehavior" must be a function.');
+        }
+    }
+    // 8. 检查钩子函数的类型
+    if ('beforeEach' in options && options.beforeEach !== undefined) {
+        if (!isFunction(options.beforeEach) && !Array.isArray(options.beforeEach)) {
+            throw new Error('[Router] "beforeEach" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.beforeEach)) {
+            options.beforeEach.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "beforeEach" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    if ('afterEach' in options && options.afterEach !== undefined) {
+        if (!isFunction(options.afterEach) && !Array.isArray(options.afterEach)) {
+            throw new Error('[Router] "afterEach" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.afterEach)) {
+            options.afterEach.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "afterEach" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    if ('onNotFound' in options && options.onNotFound !== undefined) {
+        if (!isFunction(options.onNotFound) && !Array.isArray(options.onNotFound)) {
+            throw new Error('[Router] "onNotFound" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.onNotFound)) {
+            options.onNotFound.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "onNotFound" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    if ('onError' in options && options.onError !== undefined) {
+        if (!isFunction(options.onError) && !Array.isArray(options.onError)) {
+            throw new Error('[Router] "onError" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.onError)) {
+            options.onError.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "onError" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    // 9. 检查 missing 组件的类型
+    if ('missing' in options && options.missing !== undefined) {
+        if (!isComponent(options.missing)) {
+            throw new Error('[Router] "missing" must be a valid component.');
+        }
+    }
+};

package/dist/core/router/manager.js

@@ -176,54 +176,57 @@ export class RouteManager {
      * @returns 匹配结果对象，包含路由记录和解析后的参数；未匹配返回 null
      */
     matchByPath(path) {
-        if (this.config.strict && path.endsWith('/') && path !== '/') {
-            return null;
+        let normalizedPath = path;
+        if (normalizedPath.endsWith('/') && normalizedPath !== '/') {
+            if (this.config.strict)
+                return null;
+            normalizedPath = normalizedPath.slice(0, -1);
         }
         // 1. 标准化路径
-        const formattedPath = normalizePath(path);
         const lookupPath = this.config.ignoreCase
-            ? formattedPath.toLowerCase()
-            : formattedPath;
+            ? normalizedPath.toLowerCase()
+            : normalizedPath;
         // 2. 静态路由精确匹配
         const staticRoute = this.staticRoutes.get(lookupPath);
         if (staticRoute) {
-            return { path: formattedPath, route: staticRoute, params: {} };
+            return { path, route: staticRoute, params: {} };
         }
         // 2.5 别名路由精确匹配
         const aliasRoute = this.aliasRoutes.get(lookupPath);
         if (aliasRoute) {
-            return { path: formattedPath, route: aliasRoute, params: {} };
+            return { path, route: aliasRoute, params: {} };
         }
         // 3. 动态路由匹配
-        const segments = formattedPath.split('/').filter(Boolean);
-        const length = segments.length;
-        const candidates = this.dynamicRoutes.get(length);
-        if (candidates) {
-            for (const { regex, route } of candidates) {
+        const pathSegments = normalizedPath.split('/').filter(Boolean);
+        const segmentCount = pathSegments.length;
+        const dynamicCandidates = this.dynamicRoutes.get(segmentCount);
+        if (dynamicCandidates) {
+            for (const { regex, route } of dynamicCandidates) {
+                regex.lastIndex = 0;
                 // 执行正则匹配
-                const match = regex.exec(formattedPath);
-                if (match) {
+                const regexResult = regex.exec(normalizedPath);
+                if (regexResult) {
                     const params = {};
                     // 解析捕获组参数
                     if (route.pattern) {
                         for (let i = 0; i < route.pattern.length; i++) {
                             const paramDef = route.pattern[i];
-                            const value = match[i + 1];
+                            const capturedValue = regexResult[i + 1];
                             // 仅当捕获到值时写入 params
-                            if (value !== undefined) {
-                                params[paramDef.name] = value;
+                            if (capturedValue !== undefined) {
+                                params[paramDef.name] = capturedValue;
                             }
                         }
                     }
-                    return { path: formattedPath, route, params };
+                    return { path, route, params };
                 }
             }
         }
-        if (formattedPath.endsWith('/index') && this.config.fallbackIndex) {
-            const shortPath = formattedPath.slice(0, -6);
-            const staticRoute = this.staticRoutes.get(shortPath || '/');
-            if (staticRoute) {
-                return { path: formattedPath, route: staticRoute, params: {} };
+        if (lookupPath.endsWith('/index') && this.config.fallbackIndex) {
+            const fallbackPath = lookupPath.slice(0, -6);
+            const fallbackRoute = this.staticRoutes.get(fallbackPath || '/');
+            if (fallbackRoute) {
+                return { path, route: fallbackRoute, params: {} };
             }
         }
         return null;
@@ -248,6 +251,7 @@ export class RouteManager {
         // 3. 动态路由：参数校验与序列化
         const resolvedParams = {};
         for (const paramDef of route.pattern) {
+            paramDef.regex.lastIndex = 0;
             const value = params[paramDef.name];
             const rawValue = String(value ?? ''); // 统一转字符串处理
             // 3.1 必填参数校验

package/dist/core/router/router.d.ts

@@ -1,6 +1,47 @@
 import { App, type ReadonlyObject } from 'vitarx';
 import type { AfterCallback, NavigateResult, NavigationGuard, NavOptions, NavTarget, ResolvedRouterConfig, Route, RouteIndex, RouteLocation, RouteRecord, RouterOptions, ScrollPosition, ScrollTarget, URLHash, URLQuery } from '../types/index.js';
 import { RouteManager } from './manager.js';
+/**
+ * 导航上下文
+ *
+ * 在每次导航过程中创建，封装该次导航所需的所有状态和操作。
+ * 作为各导航阶段处理方法之间的共享数据载体，避免方法间传递大量独立参数。
+ *
+ * @internal
+ */
+export interface NavigationContext {
+    /** 当前导航任务的唯一标识，用于并发导航竞争检测 */
+    taskId: number;
+    /** 导航结果对象，各阶段处理方法可修改其 state 和 message */
+    result: NavigateResult;
+    /** 目标路由位置，匹配失败时为 null */
+    to: RouteLocation | null;
+    /** 来源路由位置 */
+    from: RouteLocation;
+    /** 重定向来源路由位置，仅在重定向链中存在 */
+    redirectFrom: RouteLocation | undefined;
+    /** 是否替换当前历史记录（而非推入新记录） */
+    replace: boolean;
+    /**
+     * 检测重定向循环
+     *
+     * 每次重定向时调用，递增重定向计数器。
+     * 当重定向次数超过最大限制时抛出错误，防止无限循环。
+     *
+     * @param path - 重定向目标路径，用于错误信息
+     * @throws {Error} 当重定向次数超过 MAX_REDIRECTS 时
+     */
+    checkRedirectLoop: (path: string) => void;
+    /**
+     * 检测并发导航竞争
+     *
+     * 判断当前导航任务是否已被更新的导航任务取代。
+     * 如果已被取代，则将结果状态标记为 cancelled。
+     *
+     * @returns true 表示当前导航已被新导航取代，应中止执行
+     */
+    hasChanged: () => boolean;
+}
 /**
  * 路由器抽象基类
  *
@@ -29,6 +70,11 @@ export declare abstract class Router {
      * @private
      */
     private readonly _routeLocation;
+    /**
+     * 只读路由位置对象
+     * @private
+     */
+    private readonly _readonlyLocation;
     /**
      * 存储就绪状态的 Promise（延迟创建）
      * @private
@@ -220,7 +266,7 @@ export declare abstract class Router {
      * await router.push('/foo')
      * await router.waitViewRender()
      *
-     * // 此时 DOM 已确保更新
+     * // 此时 DOM 已更新
      * console.log(document.querySelector('#app').innerHTML)
      */
     waitViewRender(navResult?: Promise<NavigateResult>): Promise<void>;
@@ -257,8 +303,115 @@ export declare abstract class Router {
      * @returns 返回标准的导航结果 Promise
      */
     private initialNavigation;
+    /**
+     * 创建导航上下文
+     *
+     * 在每次导航开始时构建上下文对象，封装该次导航所需的所有状态：
+     * - 生成唯一任务ID，用于并发导航竞争检测
+     * - 重置重定向计数器（非重定向场景下）
+     * - 执行路由匹配，确定目标路由位置
+     * - 构建 NavigateResult 基础对象
+     * - 提供 checkRedirectLoop 和 hasChanged 闭包方法
+     *
+     * @param target - 导航目标
+     * @param fromRoute - 来源路由，默认使用当前路由位置
+     * @param redirectFrom - 重定向来源路由
+     * @returns 导航上下文对象
+     */
+    private createNavigationContext;
+    /**
+     * 处理路由未匹配（404）场景
+     *
+     * 当目标路由无法匹配时执行：
+     * 1. 触发全局 onNotFound 钩子
+     * 2. 如果钩子返回了新的导航目标，进行重定向
+     * 3. 否则返回 notfound 状态
+     *
+     * @param context - 导航上下文
+     * @param target - 原始导航目标
+     * @returns 导航结果
+     */
+    private handleNotFound;
+    /**
+     * 处理重复路由场景
+     *
+     * 当目标路由与当前路由的 href 和最终匹配记录完全相同时，
+     * 视为重复导航，返回 duplicated 状态，不执行后续流程。
+     *
+     * @param context - 导航上下文
+     * @returns 重复路由结果，或 null 表示非重复路由
+     */
+    private handleDuplicatedRoute;
+    /**
+     * 处理仅 hash 变化场景
+     *
+     * 当路由路径和查询参数相同，仅 hash 部分发生变化时，
+     * 直接更新 hash 值并触发 hashUpdate 回调，不执行完整的导航流程。
+     *
+     * @param context - 导航上下文
+     * @returns hash 变化结果，或 null 表示非仅 hash 变化
+     */
+    private handleHashOnlyChange;
+    /**
+     * 处理路由重定向场景
+     *
+     * 当目标路由配置了 redirect 字段时，解析重定向目标并递归执行导航：
+     * 1. 支持 redirect 为函数（动态重定向）或静态值
+     * 2. 重定向目标可以是路由索引（RouteIndex）或导航目标（NavTarget）
+     * 3. 如果重定向配置无效且无组件定义，抛出错误
+     *
+     * @param context - 导航上下文
+     * @returns 重定向导航结果，或 null 表示无需重定向
+     */
+    private handleRedirect;
+    /**
+     * 执行守卫流程
+     *
+     * 按顺序执行路由离开守卫和全局前置守卫，
+     * 在每个异步守卫执行后进行并发竞争检测。
+     * 如果守卫拦截导航或触发重定向，返回对应结果；
+     * 如果守卫全部通过，返回 null 表示继续导航。
+     *
+     * @param context - 导航上下文
+     * @returns 守卫拦截/重定向结果，或 null 表示守卫全部通过
+     */
+    private executeGuards;
+    /**
+     * 处理前置守卫执行结果
+     *
+     * 根据守卫返回值决定导航走向：
+     * - false: 拦截导航，返回 aborted 状态
+     * - NavTarget: 重定向到新目标
+     * - 其他（true/void）: 放行，继续导航
+     *
+     * @param context - 导航上下文
+     * @param guardResult - 前置守卫的返回值
+     * @returns 拦截/重定向结果，或 null 表示守卫通过
+     */
+    private handleGuardResult;
+    /**
+     * 完成导航流程
+     *
+     * 守卫全部通过后执行最后的导航确认：
+     * 1. 根据替换标记更新历史记录（push 或 replace）
+     * 2. 调用 completeNavigation 更新路由状态、触发后置钩子和滚动行为
+     *
+     * @param context - 导航上下文
+     * @returns 导航成功结果
+     */
+    private finalizeNavigation;
     /**
      * 导航到指定位置
+     *
+     * 作为导航流程的编排器，按顺序协调各场景处理方法的执行：
+     * 1. 创建导航上下文（路由匹配、并发控制初始化）
+     * 2. 处理 404 场景（路由未匹配）
+     * 3. 处理重复路由场景
+     * 4. 处理仅 hash 变化场景
+     * 5. 处理路由重定向场景
+     * 6. 执行守卫流程（离开守卫 → 前置守卫）
+     * 7. 完成导航（更新历史记录、触发后置钩子）
+     *
      * @param target - 导航目标对象 | 路由位置对象
      * @param fromRoute - 来源路由对象
      * @param redirectFrom - 重定向来源对象