@oiij/auto-router 0.0.3 → 0.0.4

package/README.md

@@ -13,13 +13,11 @@ Use auto-Router 是一个 Vue Router 工具库，为 Vue 3 应用提供自动路
 
 - 🔄 自动解析和排序路由（支持数字前缀排序）
 - 📊 路由扁平化处理
-- 🎯 支持嵌套路由元数据继承
 - 📝 自动规范化路由名称
 
 ### Keep-Alive 管理 💾
 
 - 🚀 自动管理页面缓存
-- 📦 基于路由元数据的缓存配置
 - 🎨 支持动态缓存控制
 
 ### 加载状态管理 ⏳
@@ -56,13 +54,41 @@ yarn add @oiij/auto-router
 
 ## 快速开始 🌟
 
-### 基础使用
+### 1. 安装插件
+
+在 Vue 应用中安装 `createAutoRouter` 插件，必须在 Vue Router 之后安装：
+
+```ts
+import { createAutoRouter } from '@oiij/auto-router'
+import { createApp } from 'vue'
+import { createRouter, createWebHistory } from 'vue-router'
+
+import { routes } from 'vue-router/auto-routes' // 自动生成的路由
+import App from './App.vue'
+
+const app = createApp(App)
+const router = createRouter({
+  history: createWebHistory(),
+  routes
+})
+
+// 必须先安装 Vue Router
+app.use(router)
+// 然后安装自动路由插件
+app.use(createAutoRouter(router, routes))
+
+app.mount('#app')
+```
+
+### 2. 在组件中使用
+
+在 Vue 组件中使用 `useAutoRouter` 获取路由实例：
 
 ```vue
 <script setup>
 import { useAutoRouter } from '@oiij/auto-router'
 
-const { loading, routes, currentRoutePath } = useAutoRouter()
+const { loading, routes, flattenRoutes } = useAutoRouter()
 </script>
 
 <template>
@@ -71,14 +97,14 @@ const { loading, routes, currentRoutePath } = useAutoRouter()
       加载中...
     </div>
     <div v-else>
-      <p>当前路由: {{ currentRoutePath }}</p>
+      <h2>路由列表</h2>
       <nav>
         <router-link
           v-for="route in routes"
           :key="route.path"
           :to="route.path"
         >
-          {{ route.meta?.title }}
+          {{ route.path }}
         </router-link>
       </nav>
     </div>

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 import { AutoRouterInstance } from "./setup-auto-router.mjs";
 import * as vue0 from "vue";
 import { App } from "vue";
-import * as vue_router0 from "vue-router";
 import { RouteRecordRaw, Router } from "vue-router";
 
 //#region src/index.d.ts
@@ -19,7 +18,12 @@ import { RouteRecordRaw, Router } from "vue-router";
  * </script>
  * ```
  */
-declare function useAutoRouter(): AutoRouterInstance;
+declare function useAutoRouter(): {
+  loading: vue0.ComputedRef<boolean>;
+  routesRaw: readonly RouteRecordRaw[];
+  routes: RouteRecordRaw[];
+  flattenRoutes: RouteRecordRaw[];
+};
 /**
  * 创建自动路由插件
  *
@@ -50,9 +54,6 @@ declare function createAutoRouter(router: Router, routes: readonly RouteRecordRa
   routesRaw: readonly RouteRecordRaw[];
   routes: RouteRecordRaw[];
   flattenRoutes: RouteRecordRaw[];
-  keepAlivePath: vue0.ComputedRef<string[]>;
-  currentRoute: vue0.ComputedRef<vue_router0.RouteLocationNormalizedLoaded>;
-  currentRoutePath: vue0.ComputedRef<string>;
   install(app: App): void;
 };
 //#endregion

package/dist/plugin.mjs

@@ -14,14 +14,11 @@
 * ```
 */
 function appendRouterMeta(route) {
-	const sortMatch = route.path.match(/(\d+)_/);
-	const sortNum = sortMatch ? Number(sortMatch[1]) : null;
-	if (sortNum !== null && !Number.isNaN(sortNum)) route.addToMeta({ sort: sortNum });
-	if (route.name) {
-		const newName = route.name.replace(/\d+_/g, "");
-		route.name = newName.startsWith("/") ? newName : `/${newName}`;
-		if (route.path !== "") route.path = route.name;
-	}
+	const reg = /(\d+)[_-]/g;
+	const sort = route.path.match(/(\d+)[_-]/)?.[1];
+	if (sort) route.addToMeta({ sort: Number(sort) });
+	route.path = route.path.replace(reg, "");
+	if (route.name) route.name = route.name.replace(reg, "");
 }
 
 //#endregion

package/dist/setup-auto-router.d.mts

@@ -1,39 +1,64 @@
-import { ComputedRef } from "vue";
-import { RouteLocationNormalizedLoaded, RouteRecordRaw, Router } from "vue-router";
+import * as vue1 from "vue";
+import { RouteRecordRaw, Router } from "vue-router";
 
 //#region src/setup-auto-router.d.ts
+declare module 'vue-router' {
+  interface RouteMeta {
+    sort?: number;
+  }
+}
 /**
- * 自动路由实例接口
+ * 设置自动路由
+ *
+ * 解析路由配置，提供路由工具方法和状态管理
+ *
+ * @param router - Vue Router 实例
+ * @param routesRaw - 原始路由配置数组
+ * @returns 自动路由实例，包含路由配置和工具方法
+ *
+ * @example
+ * ```ts
+ * import { setupAutoRouter } from '@oiij/auto-router'
+ * import { router } from './router'
+ * import { routes } from 'vue-router/auto-routes'
+ *
+ * const autoRouter = setupAutoRouter(router, routes)
+ * console.log(autoRouter.routes) // 排序后的路由
+ * console.log(autoRouter.flattenRoutes) // 扁平化路由
+ * ```
  */
-type AutoRouterInstance = {
+declare function setupAutoRouter(router: Router, routesRaw: readonly RouteRecordRaw[]): {
   /**
-   * 加载状态
+   * 路由加载状态
+   *
+   * @type {import('vue').ComputedRef<boolean>}
    */
-  loading: ComputedRef<boolean>;
+  loading: vue1.ComputedRef<boolean>;
   /**
    * 原始路由配置
+   *
+   * @type {readonly RouteRecordRaw[]}
    */
   routesRaw: readonly RouteRecordRaw[];
   /**
    * 解析并排序后的路由配置
+   *
+   * @type {RouteRecordRaw[]}
    */
   routes: RouteRecordRaw[];
   /**
-   * 扁平化的路由列表（将所有子路由提取到一级）
+   * 扁平化的路由配置
+   *
+   * @type {RouteRecordRaw[]}
    */
   flattenRoutes: RouteRecordRaw[];
-  /**
-   * 需要缓存的路由路径列表
-   */
-  keepAlivePath: ComputedRef<string[]>;
-  /**
-   * 当前路由
-   */
-  currentRoute: ComputedRef<RouteLocationNormalizedLoaded>;
-  /**
-   * 当前路由路径
-   */
-  currentRoutePath: ComputedRef<string>;
 };
+/**
+ * 自动路由实例类型
+ *
+ * @remarks
+ * 由 setupAutoRouter 函数返回的对象类型
+ */
+type AutoRouterInstance = ReturnType<typeof setupAutoRouter>;
 //#endregion
 export { AutoRouterInstance };

package/dist/setup-auto-router.mjs

@@ -3,83 +3,109 @@ import { cloneDeep } from "es-toolkit";
 
 //#region src/setup-auto-router.ts
 /**
-* 解析路由配置
+* 深度排序路由配置
 *
-* 处理以下逻辑：
-* 1. 从子路由的 index 页面继承 group 元数据
-* 2. 将空路径的子路由路径设置为父路由路径
-* 3. 根据 sort 元数据排序路由
+* 递归地对路由配置进行排序，包括所有嵌套的子路由
 *
-* @param routes - 原始路由配置
-* @returns 解析后的路由配置
+* @param routes - 原始路由配置数组
+* @returns 排序后的路由配置数组
+*
+* @example
+* ```ts
+* const sortedRoutes = deepSortRoutes([
+*   { path: '/about', meta: { sort: 2 } },
+*   { path: '/home', meta: { sort: 1 } }
+* ])
+* // 结果: [{ path: '/home', ... }, { path: '/about', ... }]
+* ```
 */
-function parseRoutes(routes) {
-	return routes.map((route) => {
-		const indexMeta = (route.children?.find((f) => f.path === ""))?.meta?.group;
+function deepSortRoutes(routes) {
+	return routes.toSorted((a, b) => (a.meta?.sort ?? Infinity) - (b.meta?.sort ?? Infinity)).map((route) => {
 		return {
 			...route,
-			meta: {
-				...route.meta,
-				...indexMeta
-			},
-			children: route.children?.map((child) => ({
-				...child,
-				path: child.path === "" ? route.path : child.path
-			})).toSorted((a, b) => (a.meta?.sort ?? Infinity) - (b.meta?.sort ?? Infinity))
+			children: route.children ? deepSortRoutes(route.children) : void 0
 		};
-	}).toSorted((a, b) => (a.meta?.sort ?? Infinity) - (b.meta?.sort ?? Infinity));
+	});
 }
 /**
 * 扁平化路由配置
 *
-* 将嵌套的路由结构展平为一维数组
+* 将嵌套的路由结构展平为一维数组，包含所有层级的路由
 *
-* @param routes - 路由配置
+* @param routes - 路由配置数组
 * @returns 扁平化后的路由数组
+*
+* @example
+* ```ts
+* const flattened = flattenDeepRoutes([
+*   {
+*     path: '/user',
+*     children: [{ path: '/user/profile' }]
+*   }
+* ])
+* // 结果: [{ path: '/user', ... }, { path: '/user/profile', ... }]
+* ```
 */
-function flattenRoutes(routes) {
-	return cloneDeep(routes).flatMap((route) => route.children ?? route);
+function flattenDeepRoutes(routes) {
+	return routes.flatMap((route) => {
+		const flattened = [route];
+		if (route.children && route.children.length > 0) flattened.push(...flattenDeepRoutes(route.children));
+		return flattened;
+	});
 }
 /**
 * 设置自动路由
 *
-* 解析路由配置，提供路由工具方法
+* 解析路由配置，提供路由工具方法和状态管理
 *
 * @param router - Vue Router 实例
-* @returns 自动路由实例
+* @param routesRaw - 原始路由配置数组
+* @returns 自动路由实例，包含路由配置和工具方法
 *
 * @example
 * ```ts
 * import { setupAutoRouter } from '@oiij/auto-router'
 * import { router } from './router'
+* import { routes } from 'vue-router/auto-routes'
 *
-* const autoRouter = setupAutoRouter(router)
-* console.log(autoRouter.routes) // 解析后的路由
+* const autoRouter = setupAutoRouter(router, routes)
+* console.log(autoRouter.routes) // 排序后的路由
 * console.log(autoRouter.flattenRoutes) // 扁平化路由
 * ```
 */
 function setupAutoRouter(router, routesRaw) {
+	/**
+	* 路由加载状态
+	*
+	* @remarks
+	* 通过导航守卫自动管理，在路由切换时设置为 true，切换完成后设置为 false
+	*/
 	const loading = ref(false);
-	router.beforeEach((to, from, next) => {
+	router.beforeEach(() => {
 		loading.value = true;
-		next();
 	});
 	router.afterEach(() => {
 		loading.value = false;
 	});
-	const routes = parseRoutes(cloneDeep(routesRaw));
-	const flattenRoutesCache = flattenRoutes(routes);
-	const keepAlivePath = computed(() => flattenRoutesCache.filter((f) => f.meta?.keepAlive).map((m) => m.path));
-	const currentRoute = computed(() => router.currentRoute.value);
-	const currentRoutePath = computed(() => currentRoute.value.path);
+	/**
+	* 解析并排序后的路由配置
+	*
+	* @remarks
+	* 使用 deepSortRoutes 对路由进行深度排序，确保所有层级的路由都按 sort 元数据排序
+	*/
+	const routes = deepSortRoutes(cloneDeep(routesRaw));
+	/**
+	* 扁平化的路由配置
+	*
+	* @remarks
+	* 使用 flattenDeepRoutes 将嵌套的路由结构展平为一维数组，方便后续处理
+	*/
+	const flattenRoutes = flattenDeepRoutes(routes);
 	return {
 		loading: computed(() => loading.value),
 		routesRaw,
 		routes,
-		flattenRoutes: flattenRoutesCache,
-		keepAlivePath,
-		currentRoute,
-		currentRoutePath
+		flattenRoutes
 	};
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oiij/auto-router",
   "type": "module",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Vue Router utilities and composables for Vue 3",
   "author": "oiij",
   "license": "MIT",
@@ -26,9 +26,6 @@
     "./plugin": {
       "types": "./dist/plugin.d.mts",
       "import": "./dist/plugin.mjs"
-    },
-    "./auto-router": {
-      "types": "./auto-router.d.ts"
     }
   },
   "main": "./dist/index.mjs",
@@ -37,7 +34,6 @@
   "files": [
     "LICENSE",
     "README.md",
-    "auto-router.d.ts",
     "dist",
     "package.json"
   ],

package/auto-router.d.ts

@@ -1,93 +0,0 @@
-/* eslint-disable */
-/* prettier-ignore */
-// biome-ignore format: off
-// biome-ignore lint: off
-// @ts-nocheck
-// Vue Router 路由元数据类型扩展
-// 这个文件扩展了 vue-router 的 RouteMeta 接口
-// 确保此文件包含在项目的 tsconfig.json 中
-
-import 'vue-router'
-
-// 为了确保这个文件被当作一个模块，添加至少一个 export 声明
-export {}
-
-declare module 'vue-router' {
-  interface RouteMeta {
-    /**
-     * 路由标题
-     */
-    title?: string
-
-    /**
-     * 路由描述
-     */
-    description?: string
-
-    /**
-     * 路由图标
-     */
-    icon?: string
-
-    /**
-     * 图标颜色
-     */
-    iconColor?: string
-
-    /**
-     * 排序权重（数字越小越靠前）
-     */
-    sort?: number
-
-    /**
-     * 布局组件名称
-     */
-    layout?: string
-
-    /**
-     * 过渡动画名称
-     */
-    transitionName?: string
-
-    /**
-     * 是否启用 Keep-Alive 缓存
-     */
-    keepAlive?: boolean
-
-    /**
-     * 是否为根路由
-     */
-    root?: boolean
-
-    /**
-     * 路由分组信息（用于导航菜单等）
-     */
-    group?: {
-      /**
-       * 分组标题
-       */
-      title?: string
-
-      /**
-       * 分组描述
-       */
-      description?: string
-
-      /**
-       * 分组图标
-       */
-      icon?: string
-
-      /**
-       * 分组图标颜色
-       */
-      iconColor?: string
-
-      /**
-       * 分组排序权重
-       */
-      sort?: number
-    }
-  }
-}
-