vitarx-router 4.0.0-beta.4 → 4.0.0-beta.5

package/README.md

@@ -423,17 +423,18 @@ export const router = createRouter({ routes })
 
 ### 文件路由配置选项
 
-| 选项               | 类型                                    | 默认值           | 说明       |
-|------------------|---------------------------------------|---------------|----------|
-| `pages`          | `PageSource \| readonly PageSource[]` | `'src/pages'` | 页面来源配置   |
-| `pathStrategy`   | `'kebab' \| 'lowercase' \| 'raw'`     | `'kebab'`     | 路径命名策略   |
-| `importMode`     | `'lazy' \| 'sync'`                    | `'lazy'`      | 组件导入模式   |
-| `injectImports`  | `readonly string[]`                   | -             | 自定义导入语句  |
-| `dts`            | `boolean \| string`                   | `false`       | 类型声明文件配置 |
-| `layoutFileName` | `string`                              | `'_layout'`   | 布局文件名    |
-| `configFileName` | `string`                              | `'_config'`   | 分组配置文件名  |
-| `transform`      | `CodeTransformHook`                   | -             | 代码转换钩子   |
-| `extendRoute`    | `ExtendRouteHook`                     | -             | 路由扩展钩子   |
+| 选项               | 类型                                         | 默认值           | 说明       |
+|------------------|--------------------------------------------|---------------|----------|
+| `pages`          | `PageSource \| readonly PageSource[]`      | `'src/pages'` | 页面来源配置   |
+| `pathStrategy`   | `'kebab' \| 'lowercase' \| 'raw'`          | `'kebab'`     | 路径格式化策略  |
+| `importMode`     | `'lazy' \| 'sync' \| ImportModeFunction`   | `'lazy'`      | 组件导入模式   |
+| `injectImports`  | `readonly string[]`                        | -             | 自定义导入语句  |
+| `dts`            | `boolean \| string`                        | `false`       | 类型声明文件配置 |
+| `layoutFileName` | `string`                                   | `'_layout'`   | 布局文件名    |
+| `configFileName` | `string`                                   | `'_config'`   | 分组配置文件名  |
+| `transform`      | `CodeTransformHook`                        | -             | 代码转换钩子   |
+| `extendRoute`    | `ExtendRouteHook`                          | -             | 路由扩展钩子   |
+| `pathParser`     | `PathParser`                               | -             | 自定义路径解析器 |
 
 详细配置请参考 [File Router 文档](src/file-router/README.md)。
 

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

@@ -1,4 +1,4 @@
-import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, ImportMode, PageDirOptions, PathParser, PathStrategy } from '../types/index.js';
+import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, ImportMode, PageDirOptions, PageSource, PathParser, PathStrategy } from '../types/index.js';
 export type PageDirConfig = Required<PageDirOptions>;
 /**
  * 规范化后的配置
@@ -16,6 +16,20 @@ export interface ResolvedConfig {
     extendRoute?: ExtendRouteHook;
     pathParser?: PathParser;
 }
+/**
+ * 将 pages 配置规范化为 PageConfig 数组
+ *
+ * 支持四种输入格式：
+ * 1. 字符串：单个目录路径
+ * 2. 对象：单个目录配置
+ * 3. 字符串数组：多个目录路径
+ * 4. 对象数组：每个目录独立配置
+ *
+ * @param pages - 用户配置的 pages
+ * @param root - 项目根目录路径（用于解析相对路径）
+ * @returns - 规范化后的目录配置数组
+ */
+export declare function resolvePageConfigs(pages: PageSource | readonly PageSource[], root: string): PageDirConfig[];
 /**
  * 规范化文件路由配置
  *

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

@@ -4,7 +4,6 @@
  * 提供页面目录配置的处理和文件检查功能。
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
-import { accessSync, constants } from 'node:fs';
 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 = {
@@ -26,7 +25,7 @@ const DEFAULT_PAGE_CONFIG = {
  * @param root - 项目根目录路径（用于解析相对路径）
  * @returns - 规范化后的目录配置数组
  */
-function resolvePageConfigs(pages, root) {
+export function resolvePageConfigs(pages, root) {
     const list = Array.isArray(pages) ? pages : [pages];
     return list.map(page => {
         const config = typeof page === 'string' ? { dir: page } : page;
@@ -38,12 +37,6 @@ function resolvePageConfigs(pages, root) {
         if (resolved.prefix !== '/' && !resolved.prefix.startsWith('/')) {
             resolved.prefix = '/' + resolved.prefix;
         }
-        try {
-            accessSync(resolved.dir, constants.R_OK | constants.W_OK);
-        }
-        catch (error) {
-            throw new Error(`File router: Pages directory "${resolved.dir}" does not exist or is not accessible`);
-        }
         return resolved;
     });
 }

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

@@ -84,9 +84,11 @@ function validateRoot(opts) {
 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'`);
+        throw new Error(`options.importMode 必须是 'lazy'、'sync' 或函数`);
     }
 }
 /**

package/dist/file-router/generator/generateRoutes.js

@@ -115,7 +115,6 @@ function buildRoutes(pages, extendRoute, parent) {
  * @returns 格式化后的组件表达式代码
  */
 function formatComponent(component, importMode, importLines) {
-    // 处理命名视图
     const entries = Object.entries(component).map(([name, file]) => {
         const importPath = JSON.stringify(file);
         let expr;
@@ -123,9 +122,16 @@ function formatComponent(component, importMode, importLines) {
             expr = pathToUniqueName(file);
             importLines.add(`import ${expr} from ${importPath}`);
         }
-        else {
+        else if (importMode === 'lazy') {
             expr = `lazy(() => import(${importPath}))`;
         }
+        else {
+            expr = importMode({
+                importPath,
+                filePath: file,
+                addImport: statement => importLines.add(statement)
+            });
+        }
         return `${JSON.stringify(name)}: ${expr}`;
     });
     return `{ ${entries.join(', ')} }`;
@@ -215,26 +221,23 @@ function generateRouteCode(route, indent, isLast, importMode, importLines) {
 function generateRoutesCode(routes, importMode = 'lazy', customImports, indent = '  ') {
     const importLines = new Set();
     const codeLines = [];
-    // 添加 lazy 导入（如果需要）
     if (importMode === 'lazy') {
         importLines.add(`import { lazy } from 'vitarx'`);
     }
-    // 添加自定义导入语句
     if (customImports && customImports.length > 0) {
         customImports.forEach(imp => importLines.add(imp));
     }
-    // 添加空行
-    if (importMode === 'lazy' || (customImports && customImports.length > 0)) {
-        codeLines.push('');
-    }
-    // 生成路由数组
     codeLines.push('export default [');
     for (let i = 0; i < routes.length; i++) {
         const route = routes[i];
         codeLines.push(...generateRouteCode(route, indent, i === routes.length - 1, importMode, importLines));
     }
     codeLines.push(']');
-    return Array.from(importLines.values()).concat(codeLines).join('\n');
+    const allImports = Array.from(importLines.values());
+    if (allImports.length > 0) {
+        allImports.push('');
+    }
+    return allImports.concat(codeLines).join('\n');
 }
 /**
  * 生成路由配置代码

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

@@ -11,6 +11,7 @@ import { type FilterOptions } from './parser/index.js';
 import type { FileRouterOptions, ParsedNode } from './types/index.js';
 export type * from './types/index.js';
 export * from './utils/logger.js';
+export { resolvePageConfigs } from './config/resolve.js';
 /**
  * 文件路由管理器
  */

package/dist/file-router/index.js

@@ -17,8 +17,9 @@ import { generateRoutes } from './generator/index.js';
 import { isEqualPageOptions, mergePageOptions, parseDefinePage, removeDefinePage } from './macros/index.js';
 import { checkDefaultExport, isPageFile, isPageFileInDirs } from './parser/index.js';
 import { parseRoutePath } from './parser/parsePage.js';
-import { applyPathStrategy, info, normalizePathSeparator, readFileContent, resolvePathVariable, validateOptions } from './utils/index.js';
+import { applyPathStrategy, info, normalizePathSeparator, readFileContent, resolvePathVariable, validateOptions, warn } from './utils/index.js';
 export * from './utils/logger.js';
+export { resolvePageConfigs } from './config/resolve.js';
 /**
  * 文件路由管理器
  */
@@ -98,6 +99,10 @@ export class FileRouter {
     scanPages() {
         const pages = [];
         for (const page of this.config.pages) {
+            if (!existsSync(page.dir)) {
+                warn(`Directory ${page.dir} does not exist, please check your configuration.`);
+                continue;
+            }
             if (page.group && page.prefix) {
                 const route = {
                     filePath: page.dir,

package/dist/file-router/types/options.d.ts

@@ -1,11 +1,46 @@
 import type { CodeTransformHook, ExtendRouteHook } from './hooks.js';
+/**
+ * 自定义导入模式函数的上下文
+ */
+export interface ImportModeContext {
+    /**
+     * 组件文件路径（已 JSON.stringify）
+     */
+    importPath: string;
+    /**
+     * 组件文件原始路径
+     */
+    filePath: string;
+    /**
+     * 添加导入语句
+     * 用于向生成的代码顶部添加 import 语句
+     */
+    addImport: (statement: string) => void;
+}
+/**
+ * 自定义导入模式函数
+ *
+ * @param context - 导入上下文
+ * @returns 组件表达式代码
+ *
+ * @example
+ * ```ts
+ * // 自定义导入模式：使用 React.lazy
+ * (context) => {
+ *   context.addImport(`import { lazy } from 'react'`)
+ *   return `lazy(() => import(${context.importPath}))`
+ * }
+ * ```
+ */
+export type ImportModeFunction = (context: ImportModeContext) => string;
 /**
  * 组件导入模式。
  *
- * - 'lazy': 生成懒加载表达式
- * - 'sync': 同步加载组件
+ * - 'lazy': 生成懒加载表达式 `lazy(() => import(path))`
+ * - 'sync': 同步加载组件，生成 `import` 语句
+ * - 函数: 自定义导入逻辑
  */
-export type ImportMode = 'lazy' | 'sync';
+export type ImportMode = 'lazy' | 'sync' | ImportModeFunction;
 /**
  * 生成路径的策略。
  */
@@ -88,6 +123,22 @@ export interface FileRouterOptions {
     /**
      * 组件导入模式
      *
+     * - 'lazy': 生成懒加载表达式 `lazy(() => import(path))`
+     * - 'sync': 同步加载组件，生成 `import` 语句
+     * - 函数: 自定义导入逻辑
+     *
+     * @example
+     * ```ts
+     * // 使用预设模式
+     * importMode: 'lazy'
+     *
+     * // 使用自定义函数
+     * importMode: (context) => {
+     *   context.addImport(`import { lazy } from 'react'`)
+     *   return `lazy(() => import(${context.importPath}))`
+     * }
+     * ```
+     *
      * @default 'lazy'
      */
     importMode?: ImportMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0-beta.5",
   "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",