vitarx-router 4.0.0-beta.20 → 4.0.0-beta.22

package/README.md

@@ -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 路由器有效。
+
 ## 路由配置
 
 ### 基本路由
@@ -468,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/core/common/utils.js

@@ -71,7 +71,7 @@ export function parseHashContent(hashContent) {
     // 同样限制分割数为 2，防止路径中包含 ?
     const [pathname, queryString] = pathAndQuery.split('?', 2);
     // 3. 格式化路径
-    path = normalizePath(pathname || '/');
+    path = pathname ? normalizePath(pathname) : '/';
     // 4. 解析查询参数
     if (queryString) {
         query = parseQuery(queryString);

package/dist/core/common/variable.js

@@ -97,7 +97,7 @@ export function mergePathVariable(path, params) {
         return String(value).replace(/\s+/g, '_');
     });
     // 使用 formatPath 处理可能出现的双斜杠 (如 /user//) 或首尾斜杠问题
-    return normalizePath(fullPath);
+    return normalizePath(fullPath, true);
 }
 /**
  * 合并两个路由模式对象

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

@@ -9,7 +9,9 @@ export interface RouteManagerOptions {
     /**
      * 是否启用严格模式
      *
-     * 启用后路径匹配将严格匹配，即路径末尾的斜杠会被视为重要字符
+     * 启用后路径匹配将严格匹配即 /user/ 结尾存在斜杠会匹配失败
+     *
+     * 禁用后路径匹配将宽匹配即 /user/ 会匹配 /user
      *
      * @default false
      */
@@ -23,8 +25,8 @@ export interface RouteManagerOptions {
     /**
      * 是否启用索引回退匹配。
      *
-     * 开启后，当访问深层路径（如 /user/index）未匹配时，
-     * 会尝试移除最后一段路径（/user）再次进行匹配。
+     * 开启后，当访问深层index路径（如 /user/index）未匹配时，
+     * 会尝试移除index路径（/user）再次进行匹配。
      * 匹配成功则渲染组件，且保持 URL 不变。
      *
      * 仅支持匹配静态路径，不做动态路径匹配！
@@ -126,7 +128,7 @@ export declare class RouteManager {
      * @returns 规范化后的路径（根据 ignoreCase 配置转换为小写）
      * @private
      */
-    private normalizePath;
+    private toLookupPath;
     /**
      * 根据路径查找路由
      *

package/dist/core/router/manager.js

@@ -127,7 +127,7 @@ export class RouteManager {
      * @returns 规范化后的路径（根据 ignoreCase 配置转换为小写）
      * @private
      */
-    normalizePath(path) {
+    toLookupPath(path) {
         return this.config.ignoreCase ? path.toLowerCase() : path;
     }
     /**
@@ -137,7 +137,7 @@ export class RouteManager {
      * @returns 路由记录对象，如果未找到则返回 undefined
      */
     findByPath(path) {
-        const normalizedPath = this.normalizePath(path);
+        const normalizedPath = this.toLookupPath(path);
         return this.staticRoutes.get(normalizedPath) ?? this.aliasRoutes.get(normalizedPath) ?? null;
     }
     /**
@@ -176,55 +176,56 @@ 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;
+        const lookupPath = this.toLookupPath(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 = path.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(path);
+                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: {} };
+        // 4. 结尾斜杠索引回退匹配
+        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;
@@ -352,14 +353,14 @@ export class RouteManager {
         // 删除当前路由
         this.routes.delete(route);
         // 删除静态路由映射
-        this.staticRoutes.delete(this.normalizePath(route.path));
+        this.staticRoutes.delete(this.toLookupPath(route.path));
         // 删除命名路由映射
         if (route.name)
             this.namedRoutes.delete(route.name);
         // 删除别名映射
         if (route.aliases) {
             for (const alias of route.aliases) {
-                this.aliasRoutes.delete(this.normalizePath(alias));
+                this.aliasRoutes.delete(this.toLookupPath(alias));
                 // 如果别名是动态路由，也需要从 dynamicRoutes 中移除
                 if (isVariablePath(alias)) {
                     this.removeAliasDynamicRoute(alias, route);
@@ -460,7 +461,7 @@ export class RouteManager {
             record.parent = parent;
         }
         const rawPath = route.path.trim();
-        record.path = normalizePath(parent ? `${parent.path}/${rawPath}` : `/${rawPath}`);
+        record.path = normalizePath(parent ? `${parent.path}/${rawPath}` : `/${rawPath}`, true);
         if (route.name) {
             record.name = route.name;
         }
@@ -511,13 +512,13 @@ export class RouteManager {
                     aliasPath = parent.path;
                 }
                 else if (rawAlias.startsWith('/')) {
-                    aliasPath = normalizePath(rawAlias);
+                    aliasPath = normalizePath(rawAlias, true);
                 }
                 else if (!parent) {
-                    aliasPath = normalizePath(`/${rawAlias}`);
+                    aliasPath = normalizePath(`/${rawAlias}`, true);
                 }
                 else {
-                    aliasPath = normalizePath(`${parent.path}/${rawAlias}`);
+                    aliasPath = normalizePath(`${parent.path}/${rawAlias}`, true);
                 }
                 record.aliases.push(aliasPath);
             }
@@ -550,7 +551,7 @@ export class RouteManager {
             this.registerDynamicRoute(route, route.fullPattern);
         }
         else {
-            const path = this.normalizePath(route.path);
+            const path = this.toLookupPath(route.path);
             // 检查是否已存在相同路径的路由
             if (this.staticRoutes.has(path)) {
                 // 抛出错误：检测到重复的路由路径
@@ -562,7 +563,6 @@ export class RouteManager {
         // 注册别名
         if (route.aliases && route.aliases.length > 0) {
             for (const alias of route.aliases) {
-                const aliasPath = this.normalizePath(alias);
                 if (isVariablePath(alias)) {
                     if (!validateAliasVariables(route.pattern, alias)) {
                         throw new Error(`[Router] Alias "${alias}" variables do not match route "${route.path}" pattern`);
@@ -571,6 +571,7 @@ export class RouteManager {
                     this.registerDynamicRoute(route, regex, alias);
                 }
                 else {
+                    const aliasPath = this.toLookupPath(alias);
                     if (route.pattern && route.pattern.length > 0) {
                         throw new Error(`[Router] Alias "${alias}" for dynamic route "${route.path}" must contain variables`);
                     }

package/dist/core/router/router.js

@@ -965,7 +965,7 @@ export class Router {
         const queryStr = stringifyQuery(query);
         const href = `${path}${queryStr}${hashStr}`;
         return this.config.mode === 'hash'
-            ? normalizePath(`${this.config.base}/#${href}`, true)
+            ? normalizePath(`${this.config.base}#${href}`)
             : normalizePath(`${this.config.base}${href}`);
     }
     /**

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

@@ -2,7 +2,20 @@ import type { RouteLocation, RouterOptions, ScrollPosition, ScrollTarget } from
 import { Router } from './router.js';
 export declare class WebRouter extends Router {
     private readonly history;
+    private initialized;
     constructor(options: RouterOptions);
+    /**
+     * 初始化路由器实例。
+     *
+     * 如果实例已经初始化，则直接返回当前实例以防止重复初始化。
+     * 初始化过程中会执行以下操作：
+     * 1. 根据目标 URL 执行初始路由替换；
+     * 2. 监听 `popstate` 事件，以处理浏览器历史记录返回时的路由恢复；
+     * 3. 监听 `hashchange` 事件，以处理浏览器 hash 值变化时的路由恢复。
+     *
+     * @returns {this} 返回当前路由器实例，支持链式调用。
+     */
+    init(): this;
     /**
      * @inheritDoc
      */

package/dist/core/router/web.js

@@ -12,6 +12,12 @@ export class WebRouter extends Router {
             writable: true,
             value: window.history
         });
+        Object.defineProperty(this, "initialized", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         /**
          * 处理浏览器历史记录的返回/前进事件
          */
@@ -49,14 +55,6 @@ export class WebRouter extends Router {
                 this.replace(this.urlToNavigateTarget()).then();
             }
         });
-        // 初始化路由
-        this.replace(this.urlToNavigateTarget()).then(res => {
-            if (__VITARX_DEV__ && res.state !== NavState.success && res.state !== NavState.cancelled) {
-                logger.error(`[Router] Initialization failed: ${res.message}`, res);
-            }
-        });
-        // 初始化时监听 popstate 事件，处理历史记录返回时的路由恢复
-        window.addEventListener('popstate', this.onPopState);
         if (this.config.mode === 'hash') {
             const { pathname, search, hash } = window.location;
             if (!hash) {
@@ -64,7 +62,35 @@ export class WebRouter extends Router {
                 window.location.replace(path);
             }
         }
+    }
+    /**
+     * 初始化路由器实例。
+     *
+     * 如果实例已经初始化，则直接返回当前实例以防止重复初始化。
+     * 初始化过程中会执行以下操作：
+     * 1. 根据目标 URL 执行初始路由替换；
+     * 2. 监听 `popstate` 事件，以处理浏览器历史记录返回时的路由恢复；
+     * 3. 监听 `hashchange` 事件，以处理浏览器 hash 值变化时的路由恢复。
+     *
+     * @returns {this} 返回当前路由器实例，支持链式调用。
+     */
+    init() {
+        if (this.initialized)
+            return this;
+        this.initialized = true;
+        // 初始化路由
+        this.replace(this.urlToNavigateTarget()).then(res => {
+            if (__VITARX_DEV__) {
+                if (res.state !== NavState.success && res.state !== NavState.cancelled) {
+                    logger.error(`[WebRouter] Initialization failed: ${res.message}`, res);
+                }
+            }
+        });
+        // 初始化时监听 popstate 事件，处理历史记录返回时的路由恢复
+        window.addEventListener('popstate', this.onPopState);
+        // 监听 hashchange 事件，处理 hash 值变化时的路由恢复
         window.addEventListener('hashchange', this.onHashChange);
+        return this;
     }
     /**
      * @inheritDoc

package/dist/core/shared/link.js

@@ -130,7 +130,7 @@ export function useLink(props) {
         const matchedRoute = route.value;
         if (!matchedRoute)
             return false;
-        return router.route.href === matchedRoute.href;
+        return router.route.path === matchedRoute.path;
     });
     /**
      * 导航处理函数

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

@@ -23,7 +23,6 @@ export declare function createRouteManager(routes: Route[], options?: RouteManag
  * 创建Web模式路由实例
  *
  * @param options - 路由配置选项
- * @param {RouterOptions} options - 路由配置选项
  * @param options.routes - 路由配置表或管理器
  * @param [options.base] - 基础路径
  * @param [options.mode] - URL模式
@@ -33,9 +32,10 @@ export declare function createRouteManager(routes: Route[], options?: RouteManag
  * @param [options.afterEach] - 全局后置钩子
  * @param [options.missing] - 未匹配时要渲染的组件
  * @param [options.onNotFound] - 导航不匹配时触发的回调函数
+ * @param [autoInit=true] - 是否自动初始化路由器
  * @returns {WebRouter} 返回Web模式路由实例
  */
-export declare function createWebRouter(options: RouterOptions): WebRouter;
+export declare function createWebRouter(options: RouterOptions, autoInit?: boolean): WebRouter;
 /**
  * 创建内存模式路由实例
  *
@@ -66,7 +66,7 @@ export declare function createMemoryRouter(options: RouterOptions): MemoryRouter
  * @param [options.afterEach] - 全局后置钩子
  * @param [options.missing] - 未匹配时要渲染的组件
  * @param [options.onNotFound] - 导航不匹配时触发的回调函数
- * @param {boolean} [skipEnvWarn=false] - 是否跳过浏览器检查
+ * @param [skipEnvWarn=false] - 是否跳过浏览器检查
  * @returns {Router} 返回路由实例，根据环境返回不同类型的路由
  *
  */

package/dist/core/shared/router.js

@@ -27,7 +27,6 @@ export function createRouteManager(routes, options) {
  * 创建Web模式路由实例
  *
  * @param options - 路由配置选项
- * @param {RouterOptions} options - 路由配置选项
  * @param options.routes - 路由配置表或管理器
  * @param [options.base] - 基础路径
  * @param [options.mode] - URL模式
@@ -37,10 +36,14 @@ export function createRouteManager(routes, options) {
  * @param [options.afterEach] - 全局后置钩子
  * @param [options.missing] - 未匹配时要渲染的组件
  * @param [options.onNotFound] - 导航不匹配时触发的回调函数
+ * @param [autoInit=true] - 是否自动初始化路由器
  * @returns {WebRouter} 返回Web模式路由实例
  */
-export function createWebRouter(options) {
-    return new WebRouter(options);
+export function createWebRouter(options, autoInit = true) {
+    const instance = new WebRouter(options);
+    if (autoInit)
+        instance.init();
+    return instance;
 }
 /**
  * 创建内存模式路由实例
@@ -74,7 +77,7 @@ export function createMemoryRouter(options) {
  * @param [options.afterEach] - 全局后置钩子
  * @param [options.missing] - 未匹配时要渲染的组件
  * @param [options.onNotFound] - 导航不匹配时触发的回调函数
- * @param {boolean} [skipEnvWarn=false] - 是否跳过浏览器检查
+ * @param [skipEnvWarn=false] - 是否跳过浏览器检查
  * @returns {Router} 返回路由实例，根据环境返回不同类型的路由
  *
  */

package/dist/core/shared/utils.d.ts

@@ -17,19 +17,20 @@ export declare function stringifyQuery(obj: Record<string, string>): `?${string}
 /**
  * 归一化path
  *
- * 去除所有空格、替换重复的斜杠、去除尾部的斜杠
+ * 去除所有空格、替换重复的斜杠
  *
  * @example
  * normalizePath('/  foo') // '/foo'
- * normalizePath('/foo/') // '/foo'
+ * normalizePath('/foo/') // '/foo/'
  * normalizePath('/foo/bar') // '/foo/bar'
  * normalizePath('foo/') // '/foo'
+ * normalizePath('/foo/',true) // '/foo'
  *
  * @param {string} path - 路径字符串
- * @param [hashMode = false] -  是否为hash模式，如果是则兼容`/#/`
+ * @param {boolean} removeEndSlash - 是否去除尾随斜杠
  * @return {string} - 格式化后的路径字符串
  */
-export declare function normalizePath(path: string, hashMode?: boolean): `/${string}`;
+export declare function normalizePath(path: string, removeEndSlash?: boolean): `/${string}`;
 /**
  * 克隆路由位置对象
  *

package/dist/core/shared/utils.js

@@ -28,24 +28,27 @@ export function stringifyQuery(obj) {
 /**
  * 归一化path
  *
- * 去除所有空格、替换重复的斜杠、去除尾部的斜杠
+ * 去除所有空格、替换重复的斜杠
  *
  * @example
  * normalizePath('/  foo') // '/foo'
- * normalizePath('/foo/') // '/foo'
+ * normalizePath('/foo/') // '/foo/'
  * normalizePath('/foo/bar') // '/foo/bar'
  * normalizePath('foo/') // '/foo'
+ * normalizePath('/foo/',true) // '/foo'
  *
  * @param {string} path - 路径字符串
- * @param [hashMode = false] -  是否为hash模式，如果是则兼容`/#/`
+ * @param {boolean} removeEndSlash - 是否去除尾随斜杠
  * @return {string} - 格式化后的路径字符串
  */
-export function normalizePath(path, hashMode = false) {
+export function normalizePath(path, removeEndSlash = false) {
     // 去除所有空格 处理重复//
-    const formated = `/${path.trim()}`.replace(/\s+/g, '').replace(/\/+/g, '/');
-    if (formated === '/' || (hashMode && formated === '/#/'))
-        return formated;
-    return formated.replace(/\/$/, '');
+    let normalizedPath = `/${path.trim()}`.replace(/\s+/g, '').replace(/\/+/g, '/');
+    if (removeEndSlash && normalizedPath.endsWith('/') && normalizedPath !== '/') {
+        normalizedPath = normalizedPath.replace(/\/$/, '');
+    }
+    // 去除尾随斜杠
+    return normalizedPath;
 }
 /**
  * 克隆路由位置对象

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.0-beta.20",
+  "version": "4.0.0-beta.22",
   "description": "Official routing solution for Vitarx framework with declarative routing, navigation guards, dynamic routes, file-based routing with HMR, and full TypeScript support.",
   "author": "ZhuChonglin <8210856@qq.com>",
   "license": "MIT",
@@ -80,7 +80,7 @@
     "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "check:circular": "madge --extensions js --circular dist --warning --exclude '.*\\.d\\.ts$'",
     "test": "vitest run",
-    "test:core": "vitest run --project jsdom",
+    "test:core": "vitest run --project core",
     "test:plugin-vite": "vitest run --project plugin-vite",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage",