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

package/dist/core/router/web.js

@@ -1,4 +1,5 @@
 import { isString, logger } from 'vitarx';
+import { NavState } from '../common/constant.js';
 import { parseHashContent } from '../common/utils.js';
 import { normalizePath, parseQuery } from '../shared/utils.js';
 import { Router } from './router.js';
@@ -11,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
+        });
         /**
          * 处理浏览器历史记录的返回/前进事件
          */
@@ -48,10 +55,6 @@ export class WebRouter extends Router {
                 this.replace(this.urlToNavigateTarget()).then();
             }
         });
-        // 初始化路由
-        this.replace(this.urlToNavigateTarget()).then();
-        // 初始化时监听 popstate 事件，处理历史记录返回时的路由恢复
-        window.addEventListener('popstate', this.onPopState);
         if (this.config.mode === 'hash') {
             const { pathname, search, hash } = window.location;
             if (!hash) {
@@ -59,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.d.ts

@@ -48,6 +48,13 @@ export interface UseLinkReturn {
      */
     navigate: (e?: MouseEvent) => Promise<NavigateResult | void>;
 }
+/**
+ * 判断是否为外部链接
+ *
+ * @param href - 链接地址
+ * @returns 是否为外部链接
+ */
+export declare function isExternalLink(href: string): boolean;
 /**
  * 创建一个链接助手，用于处理路由导航、生成链接属性及判断激活状态。
  *

package/dist/core/shared/link.js

@@ -14,6 +14,15 @@ const handleTransition = async (callback) => {
     const transition = document.startViewTransition(callback);
     await transition.finished;
 };
+/**
+ * 判断是否为外部链接
+ *
+ * @param href - 链接地址
+ * @returns 是否为外部链接
+ */
+export function isExternalLink(href) {
+    return href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//');
+}
 /**
  * 创建一个链接助手，用于处理路由导航、生成链接属性及判断激活状态。
  *
@@ -31,7 +40,6 @@ const handleTransition = async (callback) => {
  */
 export function useLink(props) {
     const router = useRouter();
-    const httpRegex = /^(https?):\/\/[^\s\/$.?#].\S*$/i;
     /**
      * 计算属性：解析目标路由
      * @returns 返回解析后的路由位置对象，如果无效则返回 null
@@ -45,7 +53,7 @@ export function useLink(props) {
         }
         else if (isString(to)) {
             // 如果是 HTTP/HTTPS 链接则返回 null
-            if (httpRegex.test(to))
+            if (isExternalLink(to))
                 return null;
             target = { index: to };
         }
@@ -100,12 +108,7 @@ export function useLink(props) {
             return props.to.index;
         }
         if (isString(props.to)) {
-            if (httpRegex.test(props.to)) {
-                return props.to;
-            }
-            if (props.to.startsWith('/')) {
-                return props.to;
-            }
+            return props.to;
         }
         return 'javascript:void(0)';
     });

package/dist/core/shared/route.js

@@ -20,8 +20,7 @@ export function useRoute(global = false) {
         return route;
     }
     const record = route.matched[depth];
-    if (!record) {
+    if (!record)
         return route;
-    }
     return createRouteProxy(route, record);
 }

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/types/options.d.ts

@@ -48,6 +48,8 @@ export interface RouterOptions {
      * 全局 props 注入配置
      *
      * 优先级低于 route 的 props 配置
+     *
+     * @default true
      */
     props?: boolean | InjectPropsHandler;
     /**

package/dist/file-router/config/index.d.ts

@@ -3,4 +3,5 @@
  *
  * 导出所有配置相关功能，提供统一的访问入口。
  */
-export * from './configUtils.js';
+export * from './resolve.js';
+export * from './validate.js';

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

@@ -3,4 +3,5 @@
  *
  * 导出所有配置相关功能，提供统一的访问入口。
  */
-export * from './configUtils.js';
+export * from './resolve.js';
+export * from './validate.js';

package/dist/file-router/config/resolve.d.ts

@@ -0,0 +1,43 @@
+import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, GroupParser, ImportMode, PageDirOptions, PageParser, PageSource, PathStrategy, RouteNode } from '../types/index.js';
+export type PageDirConfig = Required<PageDirOptions>;
+/**
+ * 规范化后的配置
+ */
+export interface ResolvedConfig {
+    root: string;
+    pages: readonly PageDirConfig[];
+    pathStrategy: PathStrategy;
+    importMode: ImportMode;
+    injectImports: readonly string[];
+    dts: false | string;
+    layoutFileName: string;
+    configFileName: string;
+    transform?: CodeTransformHook;
+    extendRoute?: ExtendRouteHook;
+    beforeWriteRoutes?: (routes: RouteNode[]) => void | RouteNode[];
+    pageParser?: PageParser;
+    groupParser?: GroupParser;
+}
+/**
+ * 将 pages 配置规范化为 PageConfig 数组
+ *
+ * 支持四种输入格式：
+ * 1. 字符串：单个目录路径
+ * 2. 对象：单个目录配置
+ * 3. 字符串数组：多个目录路径
+ * 4. 对象数组：每个目录独立配置
+ *
+ * @param pages - 用户配置的 pages
+ * @param root - 项目根目录路径（用于解析相对路径）
+ * @returns - 规范化后的目录配置数组
+ */
+export declare function resolvePageConfigs(pages: PageSource | readonly PageSource[], root: string): PageDirConfig[];
+/**
+ * 规范化文件路由配置
+ *
+ * 将用户提供的配置转换为内部统一格式。
+ *
+ * @param options - 用户提供的配置选项
+ * @returns - 规范化后的配置对象
+ */
+export declare function resolveConfig(options: FileRouterOptions): ResolvedConfig;

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

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview 配置处理工具模块
+ *
+ * 提供页面目录配置的处理和文件检查功能。
+ * 与构建工具无关，可在任何 Node.js 环境中使用。
+ */
+import path from 'node:path';
+import { DEFAULT_CONFIG_FILE, DEFAULT_DTS_FILE, DEFAULT_EXCLUDE, DEFAULT_INCLUDE, DEFAULT_LAYOUT_FILE, DEFAULT_PAGES_DIR } from '../constants.js';
+const DEFAULT_PAGE_CONFIG = {
+    exclude: DEFAULT_EXCLUDE,
+    include: DEFAULT_INCLUDE,
+    prefix: '/',
+    group: false
+};
+/**
+ * 将 pages 配置规范化为 PageConfig 数组
+ *
+ * 支持四种输入格式：
+ * 1. 字符串：单个目录路径
+ * 2. 对象：单个目录配置
+ * 3. 字符串数组：多个目录路径
+ * 4. 对象数组：每个目录独立配置
+ *
+ * @param pages - 用户配置的 pages
+ * @param root - 项目根目录路径（用于解析相对路径）
+ * @returns - 规范化后的目录配置数组
+ */
+export function resolvePageConfigs(pages, root) {
+    const list = Array.isArray(pages) ? pages : [pages];
+    return list.map(page => {
+        const config = typeof page === 'string' ? { dir: page } : page;
+        const resolved = {
+            ...DEFAULT_PAGE_CONFIG,
+            ...config,
+            dir: path.isAbsolute(config.dir) ? config.dir : path.resolve(root, config.dir)
+        };
+        if (resolved.prefix !== '/' && !resolved.prefix.startsWith('/')) {
+            resolved.prefix = '/' + resolved.prefix;
+        }
+        return resolved;
+    });
+}
+/**
+ * 规范化文件路由配置
+ *
+ * 将用户提供的配置转换为内部统一格式。
+ *
+ * @param options - 用户提供的配置选项
+ * @returns - 规范化后的配置对象
+ */
+export function resolveConfig(options) {
+    const { dts = false, root = process.cwd(), pages = DEFAULT_PAGES_DIR, importMode = 'lazy', injectImports = [], pathStrategy = 'kebab', layoutFileName = DEFAULT_LAYOUT_FILE, configFileName = DEFAULT_CONFIG_FILE, transform, extendRoute, beforeWriteRoutes, pageParser, groupParser } = options;
+    const resolvedPages = resolvePageConfigs(pages, root);
+    return {
+        dts: typeof dts === 'string' ? dts : dts ? DEFAULT_DTS_FILE : false,
+        root,
+        pages: resolvedPages,
+        importMode,
+        injectImports,
+        pathStrategy,
+        layoutFileName,
+        configFileName,
+        transform,
+        extendRoute,
+        beforeWriteRoutes,
+        pageParser,
+        groupParser
+    };
+}

package/dist/file-router/{utils/validateOptions.d.ts → config/validate.d.ts}

@@ -4,21 +4,22 @@
  * 提供文件路由配置选项的验证功能，确保用户提供的配置符合要求。
  * 当配置无效时抛出明确的错误信息，帮助用户快速定位问题。
  */
-import type { FileRouterOptions } from '../types.js';
+import type { FileRouterOptions } from '../types/index.js';
 /**
  * 验证插件配置选项
  *
  * 验证顺序：
  * 1. root 配置
- * 2. prefix 配置
- * 3. pages 配置
- * 4. extensions 配置
- * 5. include 配置
- * 6. exclude 配置
- * 7. importMode 配置
- * 8. extendRoute 配置
- * 9. injectImports 配置
- * 10. namingStrategy 配置
+ * 2. pages 配置
+ * 3. pathStrategy 配置
+ * 4. importMode 配置
+ * 5. injectImports 配置
+ * 6. dts 配置
+ * 7. layoutFileName 配置
+ * 8. configFileName 配置
+ * 9. transform 配置
+ * 10. extendRoute 配置
+ * 11. pathParser 配置
  *
  * @param opts - 用户提供的配置选项
  * @throws {Error} 当配置无效时抛出错误

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

@@ -0,0 +1,280 @@
+/**
+ * @fileoverview 配置验证工具模块
+ *
+ * 提供文件路由配置选项的验证功能，确保用户提供的配置符合要求。
+ * 当配置无效时抛出明确的错误信息，帮助用户快速定位问题。
+ */
+/**
+ * 验证 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 不能为空字符串');
+        }
+        return;
+    }
+    if (Array.isArray(opts.pages)) {
+        if (opts.pages.length === 0) {
+            throw new Error('options.pages 数组不能为空');
+        }
+        opts.pages.forEach((item, i) => {
+            validatePagesDirItem(item, i);
+        });
+        return;
+    }
+    throw new Error('options.pages 必须是字符串、字符串数组或对象数组');
+}
+/**
+ * 验证 pages 数组中的单个项目
+ *
+ * @param item - 数组项
+ * @param index - 数组索引
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validatePagesDirItem(item, index) {
+    if (typeof item === 'string') {
+        if (item.trim() === '') {
+            throw new Error(`options.pages[${index}] 不能为空字符串`);
+        }
+        return;
+    }
+    if (typeof item === 'object' && item !== null) {
+        const config = item;
+        if (!config.dir || typeof config.dir !== 'string' || config.dir.trim() === '') {
+            throw new Error(`options.pages[${index}].dir 必须是非空字符串`);
+        }
+        if (config.include !== undefined && !Array.isArray(config.include)) {
+            throw new Error(`options.pages[${index}].include 必须是数组`);
+        }
+        if (config.exclude !== undefined && !Array.isArray(config.exclude)) {
+            throw new Error(`options.pages[${index}].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)}'`);
+        }
+        return;
+    }
+    throw new Error(`options.pages[${index}] 必须是字符串或对象`);
+}
+/**
+ * 验证 root 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateRoot(opts) {
+    if (opts.root === undefined)
+        return;
+    if (typeof opts.root !== 'string') {
+        throw new Error('options.root 必须是字符串');
+    }
+    if (opts.root.trim() === '') {
+        throw new Error('options.root 不能为空字符串');
+    }
+}
+/**
+ * 验证 importMode 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateImportMode(opts) {
+    if (opts.importMode === undefined)
+        return;
+    if (typeof opts.importMode === 'function')
+        return;
+    const validModes = ['lazy', 'sync'];
+    if (!validModes.includes(opts.importMode)) {
+        throw new Error(`options.importMode 必须是 'lazy'、'sync' 或函数`);
+    }
+}
+/**
+ * 验证 injectImports 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateInjectImports(opts) {
+    if (opts.injectImports === undefined)
+        return;
+    if (!Array.isArray(opts.injectImports)) {
+        throw new Error('options.injectImports 必须是数组');
+    }
+    opts.injectImports.forEach((imp, i) => {
+        if (typeof imp !== 'string') {
+            throw new Error(`options.injectImports[${i}] 必须是字符串`);
+        }
+    });
+}
+/**
+ * 验证 namingStrategy 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validatePathStrategy(opts) {
+    if (opts.pathStrategy === undefined)
+        return;
+    const validStrategies = ['kebab', 'lowercase', 'raw'];
+    if (!validStrategies.includes(opts.pathStrategy)) {
+        throw new Error(`options.pathStrategy 必须是 'kebab'、'lowercase' 或 'raw'`);
+    }
+}
+/**
+ * 验证 dts 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateDts(opts) {
+    if (opts.dts === undefined)
+        return;
+    if (typeof opts.dts === 'boolean')
+        return;
+    if (typeof opts.dts === 'string') {
+        if (opts.dts.trim() === '') {
+            throw new Error('options.dts 为字符串时不能为空字符串');
+        }
+        return;
+    }
+    throw new Error('options.dts 必须是 boolean 或 string');
+}
+/**
+ * 验证 layoutFileName 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateLayoutFileName(opts) {
+    if (opts.layoutFileName === undefined)
+        return;
+    if (typeof opts.layoutFileName !== 'string') {
+        throw new Error('options.layoutFileName 必须是字符串');
+    }
+    if (opts.layoutFileName.trim() === '') {
+        throw new Error('options.layoutFileName 不能为空字符串');
+    }
+}
+/**
+ * 验证 configFileName 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateConfigFileName(opts) {
+    if (opts.configFileName === undefined)
+        return;
+    if (typeof opts.configFileName !== 'string') {
+        throw new Error('options.configFileName 必须是字符串');
+    }
+    if (opts.configFileName.trim() === '') {
+        throw new Error('options.configFileName 不能为空字符串');
+    }
+}
+/**
+ * 验证 transform 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateTransform(opts) {
+    if (opts.transform === undefined)
+        return;
+    if (typeof opts.transform !== 'function') {
+        throw new Error('options.transform 必须是函数');
+    }
+}
+/**
+ * 验证 extendRoute 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateExtendRoute(opts) {
+    if (opts.extendRoute === undefined)
+        return;
+    if (typeof opts.extendRoute !== 'function') {
+        throw new Error('options.extendRoute 必须是函数');
+    }
+}
+/**
+ * 验证 beforeWriteRoutes 配置
+ * @param opts
+ */
+function validateBeforeWriteRoutes(opts) {
+    if (opts.beforeWriteRoutes === undefined)
+        return;
+    if (typeof opts.beforeWriteRoutes !== 'function') {
+        throw new Error('options.beforeWriteRoutes 必须是函数');
+    }
+}
+/**
+ * 验证 pathParser 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validatePathParser(opts) {
+    if (opts.pageParser === undefined)
+        return;
+    if (typeof opts.pageParser !== 'function') {
+        throw new Error('options.pathParser 必须是函数');
+    }
+}
+/**
+ * 验证 groupParser 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validateGroupParser(opts) {
+    if (opts.groupParser === undefined)
+        return;
+    if (typeof opts.groupParser !== 'function') {
+        throw new Error('options.groupParser 必须是函数');
+    }
+}
+/**
+ * 验证插件配置选项
+ *
+ * 验证顺序：
+ * 1. root 配置
+ * 2. pages 配置
+ * 3. pathStrategy 配置
+ * 4. importMode 配置
+ * 5. injectImports 配置
+ * 6. dts 配置
+ * 7. layoutFileName 配置
+ * 8. configFileName 配置
+ * 9. transform 配置
+ * 10. extendRoute 配置
+ * 11. pathParser 配置
+ *
+ * @param opts - 用户提供的配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+export function validateOptions(opts) {
+    validateRoot(opts);
+    validatePagesDir(opts);
+    validatePathStrategy(opts);
+    validateImportMode(opts);
+    validateInjectImports(opts);
+    validateDts(opts);
+    validateLayoutFileName(opts);
+    validateConfigFileName(opts);
+    validateTransform(opts);
+    validateExtendRoute(opts);
+    validateBeforeWriteRoutes(opts);
+    validatePathParser(opts);
+    validateGroupParser(opts);
+}

package/dist/file-router/constants.d.ts

@@ -3,9 +3,19 @@
  *
  * 定义文件路由的默认配置常量。
  */
-/** 支持的页面文件扩展名列表 */
-export declare const DEFAULT_EXTENSIONS: string[];
 /** 默认的页面目录路径 */
 export declare const DEFAULT_PAGES_DIR = "src/pages";
+/** 默认的类型定义文件路径 */
+export declare const DEFAULT_DTS_FILE = "router.d.ts";
 /** 默认的包含模式 */
 export declare const DEFAULT_INCLUDE: string[];
+/** 默认的排除模式 */
+export declare const DEFAULT_EXCLUDE: string[];
+/**
+ * 布局文件名前缀
+ */
+export declare const DEFAULT_LAYOUT_FILE = "_layout";
+/**
+ * 配置文件名
+ */
+export declare const DEFAULT_CONFIG_FILE = "_config";