@zphhpzzph/vue-route-gen 1.1.0 → 3.0.0

package/README.md

@@ -2,303 +2,350 @@
 
 > [English](./README_en.md) | 简体中文
 
-Vue 3 基于文件系统的路由生成器，为 Vue Router 提供完整的类型推断支持。
+Vue 3 基于文件系统的路由生成器，为 Vue Router 提供完整的类型推断支持。类似 Nuxt 的路由系统，但更轻量。
 
-## 特性
+## ✨ 特性
 
-- 从文件结构自动发现路由
-- 支持布局文件 (`layout.vue` 或 `layout/index.vue`)
-- 动态路由参数 (`$param` 或 `[param]`)
-- 缓存机制，快速重建
-- TypeScript 支持并生成完整类型
-- **类型安全的路由 Hooks**（`useRoute` 和 `useRouter` 提供完整类型推断）
-- **自动从动态路由提取参数类型**
+- 📁 **自动路由生成** - 基于 `pages/` 目录结构自动生成路由
+- 🔒 **类型安全** - 路由跳转和参数���取都有完整的 TypeScript 类型检查
+- 🎨 **完整路由配置** - 支持所有 Vue Router 配置（`<route>` 块或 `defineRoute()` 宏）
+- 📦 **开箱即用** - 5 分钟即可完成配置
 
-## 安装
+## 📦 快速开始
+
+### 1. 安装
 
 ```bash
-npm install @zphhpzzph/vue-route-gen
-# 或
 pnpm install @zphhpzzph/vue-route-gen
-# 或
-yarn add @zphhpzzph/vue-route-gen
 ```
 
-## 使用方法
-
-### CLI
+### 2. 配置 Vite
 
-```bash
-vue-route-gen
-```
-
-### 编程方式
+在 `vite.config.ts` 中添加插件：
 
 ```typescript
-import { generateRoutes } from '@zphhpzzph/vue-route-gen';
-
-// 使用默认选项生成路由
-generateRoutes();
-
-// 或指定自定义目录
-generateRoutes({
-  pagesDir: './src/pages',
-  outFile: './src/router/route.gen.ts'
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { routeBlockPlugin, routeGenPlugin } from '@zphhpzzph/vue-route-gen/vite';
+
+export default defineConfig({
+  plugins: [
+    routeBlockPlugin(),  // 处理 <route> 自定义块
+    routeGenPlugin(),    // 自动生成路由
+    vue(),
+  ],
 });
 ```
 
-## 文件结构
+### 3. 创建页面文件
+
+在 `src/pages/` 目录下创建 `.vue` 文件：
 
 ```
 src/pages/
-├── layout.vue              # 根布局
-├── index.vue               # 首页 (/)
-├── about.vue               # 关于页面 (/about)
-├── users/
-│   ├── layout.vue          # 用户布局 (/users)
-│   ├── index.vue           # 用户列表 (/users)
-│   └── [id].vue            # 用户详情 (/users/:id)
-└── $slug.vue               # 通配路由 (/:slug)
+├── index.vue          # 首页 → /
+├── about.vue          # 关于页 → /about
+└── users/
+    ├── index.vue      # 用户列表 → /users
+    └── [id].vue       # 用户详情 → /users/:id
 ```
 
-## 配置选项
-
-### 选项
+### 4. 配置路由
 
-- `pagesDir`: 页面目录路径（默认：`src/pages`）
-- `outFile`: 输出文件路径（默认：`src/router/route.gen.ts`）
+在 `src/router/index.ts` 中使用生成的路由：
 
-### 自动排除的目录
-
-以下目录会被自动排除：
-- `components`
-- `hooks`
-- `services`
-- `types`
-- `constants`
-- `utils`
+```typescript
+import { createRouter } from 'vue-router';
+import { routes } from './route.gen';
 
-## 生成内容
+export const router = createRouter({
+  routes,
+  // ... 其他配置
+});
+```
 
-生成器会创建：
+**就这么简单！** 路由会自动生成并保持更新。
 
-1. `ROUTE_NAME` - 路由名称常量
-2. `ROUTE_PATH` - 路由路径常量
-3. `ROUTE_PATH_BY_NAME` - 按名称查找路径
-4. `RouteParams` - 每个路由的参数类型接口
-5. `RouteParamsByName<T>` - 根据路由名称获取参数类型的工具类型
-6. `routes` - Vue Router 路由记录数组
-7. `useRoute()` - 类型安全的路由访问 Hook，提供参数类型推断
-8. `useRouter()` - 类型安全的路由导航 Hook，提供参数验证
+## 🚀 常见用法
 
-## 类型安全的路由
+### 路由跳转（类型安全）
 
-### 自动生成的参数类型
+```vue
+<script setup lang="ts">
+import { useRouter, ROUTE_NAME } from '@/router/route.gen';
 
-对于 `/users/[id].vue` 这样的路由，生成器会自动提取 `id` 参数：
+const router = useRouter();
 
-```typescript
-// 在 route.gen.ts 中生成
-export interface RouteParams {
-  'users-id': {
-    id: string;
-  };
-  // ... 其他路由
+// 跳转到用户详情页
+function goToUser(userId: string) {
+  router.push({
+    name: ROUTE_NAME.USERS_ID,
+    params: { id: userId } // ✅ TypeScript 会检查参数
+  });
 }
+</script>
 ```
 
-### 使用 useRoute
+### 获取路由参数（类型安全）
 
-生成的 `useRoute` Hook 为路由参数提供完整的类型推断：
-
-```typescript
-import { useRoute, ROUTE_NAME } from '@/router/route.gen';
+```vue
+<script setup lang="ts">
+import { useRoute } from '@/router/route.gen';
 
-const route = useRoute<'users-id'>();
-// route.params.id 的类型为 `string`
+const route = useRoute();
 
+// 当在用户详情页时
 if (route.name === ROUTE_NAME.USERS_ID) {
-  console.log(route.params.id); // 完整类型支持！
+  console.log(route.params.id); // ✅ 类型为 string
 }
+</script>
 ```
 
-### 使用 useRouter
+### 覆盖默认路由配置
 
-生成的 `useRouter` Hook 提供类型安全的导航：
+在组件中添加 `<route>` 自定义块，支持完整的路由配置,将覆盖文件路由的默认配置：
 
-```typescript
-import { useRouter, ROUTE_NAME } from '@/router/route.gen';
+```vue
+<template>
+  <div><h1>用户列表</h1></div>
+</template>
+
+<route>
+{
+  "meta": {
+    "title": "用户列表",
+    "layout": "admin",
+    "requiresAuth": true,
+    "roles": ["admin"]
+  }
+}
+</route>
+```
 
-const router = useRouter();
+或者使用 `defineRoute()` 宏：
 
-// 类型安全的导航 - TypeScript 会验证参数
-router.push({
-  name: ROUTE_NAME.USERS_ID,
-  params: { id: '123' } // 必需的参数会被检查
+```vue
+<script setup lang="ts">
+defineRoute({
+  meta: {
+    title: '用户列表',
+    layout: 'admin',
+    requiresAuth: true,
+    roles: ['admin']
+  }
 });
+</script>
+```
+
+**注意**：可以自定义路径、别名等所有 Vue Router 配置项，详见 [路由配置指南](./docs/RouteConfig.md)。
+
+### 在路由守卫中使用元数据
 
-// 错误：类型 '{ id: string; }' 不能赋值给类型 'Record<string, never>'
-router.push({
-  name: ROUTE_NAME.HOME, // HOME 路由没有参数
-  params: { id: '123' } // TypeScript 报错！
+```typescript
+// router/guards.ts
+router.beforeEach((to, from, next) => {
+  // 设置页面标题
+  if (to.meta.title) {
+    document.title = to.meta.title;
+  }
+
+  // 检查认证
+  if (to.meta.requiresAuth && !isAuthenticated()) {
+    return next({ name: 'login' });
+  }
+
+  next();
 });
 ```
 
-## 完整示例
-
-### 项目结构
+## 📁 目录结构约定
 
 ```
-src/
-├── pages/
-│   ├── index.vue          # 首页
-│   ├── users/
-│   │   ├── [id].vue       # 用户详情页
-│   │   └── index.vue      # 用户列表页
-│   └── posts/
-│       └── $slug.vue      # 文章详情页
-└── router/
-    └── route.gen.ts       # 自动生成
+src/pages/
+├── layout.vue              # 根布局
+├── index.vue               # 首页 (/)
+├── about.vue               # 关于页面 (/about)
+├── users/
+│   ├── layout.vue          # 用户布局（嵌套）
+│   ├── index.vue           # 用户列表 (/users)
+│   └── [id].vue            # 用户详情 (/users/:id)
+└── $slug.vue               # 通配路由 (/:slug)
 ```
 
-### 生成的类型定义
+**自动排除的目录**：`components/`、`hooks/`、`services/`、`types/`、`constants/`、`utils/`
 
-```typescript
-// route.gen.ts (自动生成)
-export const ROUTE_NAME = {
-  INDEX: "index",
-  USERS_INDEX: "users-index",
-  USERS_ID: "users-[id]",
-  POSTS_SLUG: "posts-$slug",
-} as const;
-
-export interface RouteParams {
-  index: Record<string, never>;
-  'users-index': Record<string, never>;
-  'users-[id]': {
-    id: string;
-  };
-  'posts-$slug': {
-    slug: string;
-  };
-}
+## ⚙️ 配置
+
+### Vite 插件配置
 
-export function useRoute<TName extends RouteName = RouteName>(
-  name?: TName
-): /* 类型增强的路由对象 */;
+如需自定义页面目录或输出文件路径：
 
-export function useRouter(): /* 类型增强的路由对象 */;
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    routeBlockPlugin(),
+    routeGenPlugin({
+      pagesDir: './src/pages',           // 可选，默认 'src/pages'
+      outFile: './src/router/route.gen.ts',  // 可选，默认 'src/router/route.gen.ts'
+    }),
+    vue(),
+  ],
+});
 ```
 
-### 在组件中使用
+### 自定义路由元数据类型
 
-```vue
-<script setup lang="ts">
-import { useRoute, useRouter, ROUTE_NAME } from '@/router/route.gen';
-
-const route = useRoute();
-const router = useRouter();
+在项目中扩展路由元数据类型：
 
-// 访问路由参数（完全类型安全）
-if (route.name === ROUTE_NAME.USERS_ID) {
-  const userId = route.params.id; // 类型为 string
+```typescript
+// src/types/router.d.ts
+declare module '@zphhpzzph/vue-route-gen/runtime' {
+  interface RouteMeta {
+    icon?: string;        // 菜单图标
+    hidden?: boolean;     // 是否隐藏
+    order?: number;       // 排序
+  }
 }
+```
 
-// 导航到其他路由（参数类型受保护）
-function navigateToUser(userId: string) {
-  router.push({
-    name: ROUTE_NAME.USERS_ID,
-    params: { id: userId } // TypeScript 会检查参数类型
-  });
+然后在 `<route>` 块中使用：
+
+```vue
+<route>
+{
+  "title": "仪表盘",
+  "icon": "Dashboard",
+  "hidden": false,
+  "order": 1
 }
-</script>
+</route>
 ```
 
-## 高级用法
+### 支持的路由配置
 
-### 获取特定路由的参数类型
+支持所有 Vue Router 配置项及自定义元数据：
 
-```typescript
-import type { RouteParamsByName } from '@/router/route.gen';
+| 配置项 | 类型 | 说明 |
+|--------|------|------|
+| `path` | `string` | 自定义路由路径 |
+| `name` | `string` | 自定义路由名称 |
+| `alias` | `string \| string[]` | 路由别名 |
+| `redirect` | `string \| object` | 重定向配置 |
+| `props` | `boolean \| object` | 路由参数传递 |
+| `meta` | `object` | 路由元数据（见下表） |
 
-type UserDetailParams = RouteParamsByName<'users-[id]'>;
-// 类型为：{ id: string }
+**常用 meta 属性**：
 
-function fetchUserData(params: UserDetailParams) {
-  // params.id 的类型为 string
-  return api.get(`/users/${params.id}`);
-}
-```
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `title` | `string` | 页面标题 |
+| `layout` | `string \| false` | 布局组件或 `false` 禁用 |
+| `keepAlive` | `boolean` | 是否缓存页面 |
+| `requiresAuth` | `boolean` | 是否需要认证 |
+| `roles` | `string[]` | 允许的角色 |
+| `icon` | `string` | 菜单图标 |
+| `hidden` | `boolean` | 是否隐藏菜单 |
+| `*` | `any` | 支持任何自定义属性 |
+
+完整配置示例请查看 [路由配置指南](./docs/RouteConfig.md)。
+
+## 📖 实用示例
 
-### 布局嵌套
+### 示例 1：创建嵌套路由
 
 ```
 src/pages/
-├── layout.vue           # 根布局
-├── index.vue            # / (使用根布局)
+├── layout.vue              # 根布局
+├── index.vue               # → /
 ├── admin/
-│   ├── layout.vue       # /admin 布局
-│   ├── index.vue        # /admin (使用 admin 布局)
+│   ├── layout.vue          # 管理后台布局
+│   ├── index.vue           # → /admin
 │   └── users/
-│       └── [id].vue     # /admin/users/:id (使用 admin 布局)
+│       ├── index.vue       # → /admin/users
+│       └── [id].vue        # → /admin/users/:id
 ```
 
-## 最佳实践
+### 示例 2：动态路由参数
 
-1. **始终使用生成的常量**：使用 `ROUTE_NAME` 而不是硬编码字符串
-2. **利用类型推断**：让 TypeScript 为你检查路由参数
-3. **组合使用 Hooks**：`useRoute` 和 `useRouter` 提供完整的类型安全
+两种语法都支持：
 
-## 发布新版本（维护者）
+```
+# 方式 1：Vue Router 风格
+users/[id].vue          # → /users/:id
 
-### 快速发布
+# 方式 2：Nuxt 风格
+posts/$slug.vue         # → /posts/:slug
+```
 
-```bash
-# 补丁版本 (1.0.0 -> 1.0.1)
-pnpm run release:patch
+### 示例 3：完整页面示例
 
-# 次要版本 (1.0.0 -> 1.1.0)
-pnpm run release:minor
+```vue
+<!-- src/pages/users/[id].vue -->
+<template>
+  <div>
+    <h1>用户详情</h1>
+    <p>用户 ID: {{ userId }}</p>
+  </div>
+</template>
 
-# 主要版本 (1.0.0 -> 2.0.0)
-pnpm run release:major
-```
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useRoute } from '@/router/route.gen';
 
-### 预发布版本
+const route = useRoute('users-[id]');
+const userId = computed(() => route.params.id);
+</script>
 
-```bash
-# 预发布补丁 (1.0.0 -> 1.0.1-0)
-pnpm run release:pre
+<route>
+{
+  "path": "/users/:id",
+  "props": true,
+  "meta": {
+    "title": "用户详情",
+    "layout": "admin",
+    "requiresAuth": true,
+    "roles": ["admin", "moderator"]
+  }
+}
+</route>
 ```
 
-### 手动发布流程
+## 🔍 生成的内容说明
 
-```bash
-# 1. 更新版本号
-npm version patch|minor|major
+`vue-route-gen` 会生成 `route.gen.ts` 文件，包含：
+
+- **`routes`** - Vue Router 路由配置数组
+- **`ROUTE_NAME`** - 路由名称常量（避免硬编码）
+- **`useRoute()`** - 类型增强的路由 hook
+- **`useRouter()`** - 类型增强的路由导航 hook
 
-# 2. 构建
-pnpm run build
+**通常你只需要使用这几个导出即可，无需关心底层实现细节。**
 
-# 3. 发布到 npm
-npm publish --access public --registry https://registry.npmjs.org/
+## ❓ 常见问题
+
+### Q: 如何手动触发路由生成？
+
+A: 运行 CLI 命令：
+```bash
+pnpm exec vue-route-gen
 ```
 
-### 发布脚本说明
+### Q: 如何禁用某个目录的路由生成？
+
+A: 以下目录自动排除：`components/`、`hooks/`、`services/`、`types/`、`constants/`、`utils/`
+
+### Q: 开发时路由会自动更新吗？
+
+A: 使用 `routeGenPlugin()` 后，路由会在文件变化时自动重新生成。
 
-- `release:patch` - 自动更新补丁版本并发布（bug 修复）
-- `release:minor` - 自动更新次要版本并发布（新功能）
-- `release:major` - 自动更新主要版本并发布（破坏性变更）
-- `release:pre` - 发布预发布版本（alpha/beta/rc）
-- `release` - 仅发布（不更新版本号）
-- `pre-release` - 发布预发布版本（不更新版本号）
+## 📚 深入阅读
 
-这些脚本会自动：
-1. 更新 package.json 中的版本号
-2. 创建 git tag
-3. 构建 TypeScript 代码
-4. 发布到 npm registry
+- **[文档索引](./docs/README.md)** - 完整文档导航
+- **[更新日志](./CHANGELOG.md)** - 版本更新记录
+- **[路由配置指南](./docs/RouteConfig.md)** - `<route>` 块和 `defineRoute()` 完整用法
+- **[Vite 插件详解](./docs/VitePlugin.md)** - 插件工作原理
 
-## License
+## 📄 License
 
 MIT

package/dist/extract-meta.d.ts

@@ -1,17 +1,28 @@
-export interface RouteMeta {
-    title?: string;
-    layout?: string | false;
-    keepAlive?: boolean;
-    requiresAuth?: boolean;
-    roles?: string[];
-    redirect?: string | {
-        name: string;
-        path?: string;
-    };
+import type { RouteRecordRaw, RouteRecordRedirectOption, _RouteRecordProps } from 'vue-router';
+type RouteRecordProps = _RouteRecordProps;
+/**
+ * Route configuration override interface
+ * Supports all RouteRecordRaw fields for complete customization
+ */
+export interface RouteConfigOverride {
+    path?: string;
+    name?: string;
+    alias?: string | string[];
+    redirect?: RouteRecordRedirectOption;
+    props?: RouteRecordProps;
+    meta?: Record<string, any>;
+    children?: RouteRecordRaw[];
+    beforeEnter?: any;
     [key: string]: any;
 }
 /**
- * Parse Vue SFC and extract metadata from <route> custom block
+ * Parse Vue SFC and extract complete route configuration
+ * Supports both <route> custom block and defineRoute() macro
+ *
+ * @param filePath - Path to the Vue SFC file
+ * @returns Route configuration override, or undefined if no custom config
+ * @throws Error if both <route> block and defineRoute() are present
  */
-export declare function extractRouteMeta(filePath: string): RouteMeta;
+export declare function extractRouteConfig(filePath: string): RouteConfigOverride | undefined;
+export {};
 //# sourceMappingURL=extract-meta.d.ts.map

package/dist/extract-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-meta.d.ts","sourceRoot":"","sources":["../src/extract-meta.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAqB5D"}
+{"version":3,"file":"extract-meta.d.ts","sourceRoot":"","sources":["../src/extract-meta.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG/F,KAAK,gBAAgB,GAAG,iBAAiB,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,GAAG,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAiDpF"}