vitarx-router 4.0.7 → 4.0.8

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

@@ -1,5 +1,5 @@
 import { type AnyCallback } from 'vitarx';
-import type { GuardResult, NavTarget, RouteIndex, RouteLocation, RoutePath, URLHash, URLQuery } from '../types/index.js';
+import type { GuardResult, NavTarget, RouteIndex, RouteLocation, RoutePath, ScrollTarget, URLHash, URLQuery } from '../types/index.js';
 /**
  * 判断是否为外部链接
  *
@@ -85,3 +85,9 @@ export declare function resolveNavTarget(index: NavTarget | RouteIndex | RouteLo
 export declare function registerHookTool<T extends {
     [key: string]: any;
 }>(hooks: T, type: keyof T, hook: AnyCallback): void;
+/**
+ * web 滚动到指定位置
+ *
+ * @param target - 滚动目标
+ */
+export declare function webScrollTo(target: ScrollTarget): void;

package/dist/core/common/utils.js

@@ -1,4 +1,4 @@
-import { isDeepEqual, isPlainObject, isString } from 'vitarx';
+import { isDeepEqual, isPlainObject, isString, logger } from 'vitarx';
 import { normalizePath, parseQuery } from '../shared/utils.js';
 /**
  * 判断是否为外部链接
@@ -149,3 +149,44 @@ export function registerHookTool(hooks, type, hook) {
         set.add(hook);
     }
 }
+/**
+ * web 滚动到指定位置
+ *
+ * @param target - 滚动目标
+ */
+export function webScrollTo(target) {
+    try {
+        if ('el' in target && target.el) {
+            const { el, ...rest } = target;
+            if (isString(el)) {
+                let element = null;
+                try {
+                    // 如果选择器以 # 开头，则进行解码
+                    const selector = el.startsWith('#') ? decodeURIComponent(el) : el;
+                    element = document.querySelector(selector);
+                }
+                catch (e) {
+                    logger.warn(`[Router] Invalid selector "${el}", skipping scroll to element`, e);
+                    return;
+                }
+                if (element) {
+                    if (element.scrollIntoView) {
+                        element.scrollIntoView(rest);
+                    }
+                    else {
+                        window.scrollTo({
+                            top: element.getBoundingClientRect().top + window.scrollY,
+                            left: element.getBoundingClientRect().left + window.scrollX
+                        });
+                    }
+                }
+            }
+        }
+        else {
+            window.scrollTo(target);
+        }
+    }
+    catch (e) {
+        logger.warn(`[Router] Failed to scroll to specified position, please check scroll target parameters: ${JSON.stringify(target)}`, e);
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { RouteLocation } from '../types/index.js';
+import type { RouteLocation, RouterOptions } from '../types/index.js';
 import { Router } from './router.js';
 /**
  * 基于内存实现的路由器
@@ -11,6 +11,7 @@ export declare class MemoryRouter extends Router {
     protected _history: RouteLocation[];
     protected _pendingGo: number | null;
     private _currentIndex;
+    constructor(options: RouterOptions);
     /**
      * 当前历史路由索引
      *

package/dist/core/router/memory.js

@@ -1,3 +1,4 @@
+import { webScrollTo } from '../common/utils.js';
 import { Router } from './router.js';
 /**
  * 基于内存实现的路由器
@@ -7,8 +8,8 @@ import { Router } from './router.js';
  * > 注意：不要在浏览器端使用，因为浏览器端有原生的history对象，使用内存模式会和浏览器端的历史记录冲突，导致路由异常。
  */
 export class MemoryRouter extends Router {
-    constructor() {
-        super(...arguments);
+    constructor(options) {
+        super(options);
         // 路由历史记录数组
         Object.defineProperty(this, "_history", {
             enumerable: true,
@@ -23,13 +24,17 @@ export class MemoryRouter extends Router {
             writable: true,
             value: null
         });
-        /// 当前历史路由索引
+        // 当前历史路由索引
         Object.defineProperty(this, "_currentIndex", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: -1
         });
+        // 兼容在electron 中使用内存路由器时享有滚动行为
+        if (typeof window !== 'undefined' && typeof window.scrollTo === 'function') {
+            this.scrollTo = webScrollTo;
+        }
     }
     /**
      * 当前历史路由索引

package/dist/core/router/router.js

@@ -789,31 +789,28 @@ export class Router {
         if (__VITARX_SSR__)
             return;
         const defaultTarget = to.hash ? { el: to.hash } : { top: 0, left: 0 };
-        // 初始化目标滚动位置为保存的位置
-        let target = savedPosition || defaultTarget;
-        // 检查是否配置了自定义滚动行为函数
-        if (isFunction(this.config.scrollBehavior)) {
-            try {
-                // 调用自定义滚动行为函数
-                const result = this.config.scrollBehavior(to, from, savedPosition);
-                if (result === false)
-                    return; // 如果返回 false，则不进行滚动
-                if (isPlainObject(result))
-                    target = result; // 如果有返回值，则更新目标位置
-            }
-            catch (e) {
-                // 捕获并记录自定义滚动行为函数中的错误
-                logger.error('[Router] Error in scrollBehavior callback:', e);
-            }
-        }
-        // 没有滚动行为函数，则直接返回
-        if (!this.scrollTo)
-            return;
         const id = ++this._scrollTaskID;
         // 等待路由组件解析完成后滚动
         this.waitViewRender().then(async () => {
             // 确保滚动目标未改变
             if (id === this._scrollTaskID) {
+                // 初始化目标滚动位置为保存的位置
+                let target = savedPosition || defaultTarget;
+                // 检查是否配置了自定义滚动行为函数
+                if (isFunction(this.config.scrollBehavior)) {
+                    try {
+                        // 调用自定义滚动行为函数
+                        const result = this.config.scrollBehavior(to, from, savedPosition);
+                        if (result === false)
+                            return; // 如果返回 false，则不进行滚动
+                        if (isPlainObject(result))
+                            target = result; // 如果有返回值，则更新目标位置
+                    }
+                    catch (e) {
+                        // 捕获并记录自定义滚动行为函数中的错误
+                        logger.error('[Router] Error in scrollBehavior callback:', e);
+                    }
+                }
                 // 执行滚动到目标位置
                 this.scrollTo?.(target);
             }

package/dist/core/router/web.js

@@ -1,6 +1,6 @@
-import { isString, logger } from 'vitarx';
+import { logger } from 'vitarx';
 import { NavState } from '../common/constant.js';
-import { parseHashContent } from '../common/utils.js';
+import { parseHashContent, webScrollTo } from '../common/utils.js';
 import { normalizePath, parseQuery } from '../shared/utils.js';
 import { Router } from './router.js';
 export class WebRouter extends Router {
@@ -136,40 +136,7 @@ export class WebRouter extends Router {
      * @inheritDoc
      */
     scrollTo(target) {
-        try {
-            if ('el' in target && target.el) {
-                const { el, ...rest } = target;
-                if (isString(el)) {
-                    let element = null;
-                    try {
-                        // 如果选择器以 # 开头，则进行解码
-                        const selector = el.startsWith('#') ? decodeURIComponent(el) : el;
-                        element = document.querySelector(selector);
-                    }
-                    catch (e) {
-                        logger.warn(`[Router] Invalid selector "${el}", skipping scroll to element`, e);
-                        return;
-                    }
-                    if (element) {
-                        if (element.scrollIntoView) {
-                            element.scrollIntoView(rest);
-                        }
-                        else {
-                            window.scrollTo({
-                                top: element.getBoundingClientRect().top + window.scrollY,
-                                left: element.getBoundingClientRect().left + window.scrollX
-                            });
-                        }
-                    }
-                }
-            }
-            else {
-                window.scrollTo(target);
-            }
-        }
-        catch (e) {
-            logger.warn(`[Router] Failed to scroll to specified position, please check scroll target parameters: ${JSON.stringify(target)}`, e);
-        }
+        webScrollTo(target);
     }
     /**
      * 将当前 URL 转换为 NavigateTarget 对象

package/dist/file-router/config/validate.js

@@ -7,64 +7,76 @@
 /**
  * 验证 pages 配置
  *
+ * pages 支持 string（单目录路径）、PageDirOptions（单目录配置对象）以及
+ * 它们的数组形式，此处对应每种形态分别校验，与 FileRouterOptions.pages 类型保持一致。
+ *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
 function validatePagesDir(opts) {
     if (opts.pages === undefined)
         return;
+    // 字符串形式：单个页面目录路径
     if (typeof opts.pages === 'string') {
-        if (opts.pages.trim() === '') {
-            throw new Error('options.pages 不能为空字符串');
-        }
+        validatePageSource(opts.pages, 'options.pages');
         return;
     }
+    // 数组形式：多个页面来源
     if (Array.isArray(opts.pages)) {
         if (opts.pages.length === 0) {
             throw new Error('options.pages 数组不能为空');
         }
         opts.pages.forEach((item, i) => {
-            validatePagesDirItem(item, i);
+            validatePageSource(item, `options.pages[${i}]`);
         });
         return;
     }
-    throw new Error('options.pages 必须是字符串、字符串数组或对象数组');
+    // 对象形式：单个页面目录配置（PageDirOptions）
+    if (typeof opts.pages === 'object' && opts.pages !== null) {
+        validatePageSource(opts.pages, 'options.pages');
+        return;
+    }
+    throw new Error('options.pages 必须是字符串、对象或字符串/对象数组');
 }
 /**
- * 验证 pages 数组中的单个项目
+ * 验证单个页面来源配置
+ *
+ * 同时用于单对象配置（fieldPrefix 为 'options.pages'）与数组项
+ * （fieldPrefix 为 'options.pages[i]'）的校验，通过 fieldPrefix 拼接出
+ * 准确的错误定位信息，避免单对象与数组两套校验逻辑的重复实现。
  *
- * @param item - 数组项
- * @param index - 数组索引
+ * @param source - 页面来源，可为字符串或 PageDirOptions 对象
+ * @param fieldPrefix - 错误信息字段前缀
  * @throws {Error} 当配置无效时抛出错误
  */
-function validatePagesDirItem(item, index) {
-    if (typeof item === 'string') {
-        if (item.trim() === '') {
-            throw new Error(`options.pages[${index}] 不能为空字符串`);
+function validatePageSource(source, fieldPrefix) {
+    if (typeof source === 'string') {
+        if (source.trim() === '') {
+            throw new Error(`${fieldPrefix} 不能为空字符串`);
         }
         return;
     }
-    if (typeof item === 'object' && item !== null) {
-        const config = item;
+    if (typeof source === 'object' && source !== null) {
+        const config = source;
         if (!config.dir || typeof config.dir !== 'string' || config.dir.trim() === '') {
-            throw new Error(`options.pages[${index}].dir 必须是非空字符串`);
+            throw new Error(`${fieldPrefix}.dir 必须是非空字符串`);
         }
         if (config.include !== undefined && !Array.isArray(config.include)) {
-            throw new Error(`options.pages[${index}].include 必须是数组`);
+            throw new Error(`${fieldPrefix}.include 必须是数组`);
         }
         if (config.exclude !== undefined && !Array.isArray(config.exclude)) {
-            throw new Error(`options.pages[${index}].exclude 必须是数组`);
+            throw new Error(`${fieldPrefix}.exclude 必须是数组`);
         }
         if (config.group === true &&
             config.prefix !== undefined &&
             typeof config.prefix === 'string' &&
             config.prefix !== '/' &&
             config.prefix.endsWith('/')) {
-            throw new Error(`options.pages[${index}].prefix 当 group 为 true 时不能以 '/' 结尾，请使用 '${config.prefix.slice(0, -1)}'`);
+            throw new Error(`${fieldPrefix}.prefix 当 group 为 true 时不能以 '/' 结尾，请使用 '${config.prefix.slice(0, -1)}'`);
         }
         return;
     }
-    throw new Error(`options.pages[${index}] 必须是字符串或对象`);
+    throw new Error(`${fieldPrefix} 必须是字符串或对象`);
 }
 /**
  * 验证 root 配置

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.7",
+  "version": "4.0.8",
   "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",