@zphhpzzph/vue-route-gen 1.1.0 → 2.0.0

package/README.md

@@ -13,6 +13,8 @@ Vue 3 基于文件系统的路由生成器，为 Vue Router 提供完整的类
 - TypeScript 支持并生成完整类型
 - **类型安全的路由 Hooks**（`useRoute` 和 `useRouter` 提供完整类型推断）
 - **自动从动态路由提取参数类型**
+- **`<route>` 自定义块支持** - 在 SFC 中定义路由元数据，零运行时开销
+- **精确的字面量类型推断** - 为路由元数据提供编译时类型安全，详见 [字面量类型推断文档](./docs/LiteralTypes.md)
 
 ## 安装
 
@@ -63,7 +65,71 @@ src/pages/
 
 ## 配置选项
 
-### 选项
+### Vite 配置
+
+`@zphhpzzph/vue-route-gen` 提供了两个 Vite 插件：
+
+#### 1. `routeBlockPlugin()` - 处理路由自定义块（必需）
+
+必须添加，用于移除 `<route>` 自定义块和 `defineRoute()` 宏：
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { routeBlockPlugin } from '@zphhpzzph/vue-route-gen/vite';
+
+export default defineConfig({
+  plugins: [
+    routeBlockPlugin(),  // 处理 <route> 自定义块和 defineRoute()
+    vue(),
+  ],
+});
+```
+
+**注意**：`routeBlockPlugin` 会移除 `<route>` 自定义块，因为这些块已经在构建时被 `vue-route-gen` 提取并合并到路由配置中，不需要在运行时处理。
+
+#### 2. `routeGenPlugin()` - 自动生成路由（推荐）
+
+**开发体验优化**：自动监听文件变化并重新生成路由，无需手动运行命令。
+
+```typescript
+// vite.config.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(),  // 1. 最先执行
+    routeGenPlugin(),    // 2. 自动生成路由
+    vue(),               // 3. Vue 插件
+  ],
+});
+```
+
+**功能特性**：
+
+- ✅ 开发服务器启动时自动生成路由
+- ✅ 监听 `pages` 目录的文件变化
+- ✅ 智能判断是否需要重新生成（避免不必要的重建）
+- ✅ 自动触发 HMR 更新
+- ✅ 支持自定义配置
+
+**自定义配置**：
+
+```typescript
+routeGenPlugin({
+  pagesDir: './src/pages',      // 可选，默认 'src/pages'
+  outFile: './src/router/route.gen.ts',  // 可选，默认 'src/router/route.gen.ts'
+})
+```
+
+**插件顺序**：`routeBlockPlugin()` → `routeGenPlugin()` → `vue()`
+
+详细文档：[Vite 插件使用指南](./docs/VitePlugin.md)
+
+### 生成器选项
 
 - `pagesDir`: 页面目录路径（默认：`src/pages`）
 - `outFile`: 输出文件路径（默认：`src/router/route.gen.ts`）
@@ -87,9 +153,306 @@ src/pages/
 3. `ROUTE_PATH_BY_NAME` - 按名称查找路径
 4. `RouteParams` - 每个路由的参数类型接口
 5. `RouteParamsByName<T>` - 根据路由名称获取参数类型的工具类型
-6. `routes` - Vue Router 路由记录数组
-7. `useRoute()` - 类型安全的路由访问 Hook，提供参数类型推断
-8. `useRouter()` - 类型安全的路由导航 Hook，提供参数验证
+6. `RouteMetaMap` - 每个路由的元数据类型接口（从 `<route>` 块提取）
+7. `RouteMetaByName<T>` - 根据路由名称获取元数据类型的工具类型
+8. `routes` - Vue Router 路由记录数组
+9. `useRoute()` - 类型安全的路由访问 Hook，提供参数和元数据类型推断
+10. `useRouter()` - 类型安全的路由导航 Hook，提供参数验证
+
+## 使用 `<route>` 自定义块
+
+`@zphhpzzph/vue-route-gen` 支持在 Vue SFC 文件中使用 `<route>` 自定义块来定义路由元数据。这些元数据会在**构建时**被提取并合并到生成的路由配置中，**零运行时开销**。
+
+### 基础用法
+
+在 Vue 组件中添加 `<route>` 自定义块：
+
+```vue
+<template>
+  <div>
+    <h1>用户列表</h1>
+  </div>
+</template>
+
+<script setup lang="ts">
+// 组件逻辑
+</script>
+
+<route>
+{
+  "title": "用户列表",
+  "layout": "admin",
+  "requiresAuth": true,
+  "roles": ["admin", "moderator"]
+}
+</route>
+```
+
+### 支持的元数据属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `title` | `string` | 页面标题，用于 document.title 和面包屑 |
+| `layout` | `string \| false` | 布局组件名称，或 `false` 禁用布局 |
+| `keepAlive` | `boolean` | 是否缓存页面组件 |
+| `requiresAuth` | `boolean` | 是否需要认证 |
+| `roles` | `string[]` | 允许访问的用户角色 |
+| `redirect` | `string \| { name: string }` | 重定向配置 |
+| `icon` | `string` | 菜单图标（自定义属性） |
+| `hidden` | `boolean` | 是否隐藏菜单（自定义属性） |
+| `*` | `any` | 支持任何自定义属性 |
+
+### JSON 和 JavaScript 对象语法
+
+`<route>` 块支持两种语法：
+
+#### 1. JSON 语法（推荐）
+
+```vue
+<route>
+{
+  "title": "用户详情",
+  "layout": "admin",
+  "requiresAuth": true,
+  "roles": ["admin"]
+}
+</route>
+```
+
+#### 2. JavaScript 对象语法
+
+```vue
+<route>
+{
+  title: '用户详情',
+  layout: 'admin',
+  requiresAuth: true,
+  roles: ['admin', 'moderator']
+}
+</route>
+```
+
+### 完整示例
+
+#### 用户列表页面
+
+```vue
+<!-- src/pages/users/index.vue -->
+<template>
+  <div class="users-page">
+    <h1>用户列表</h1>
+    <UserList />
+  </div>
+</template>
+
+<script setup lang="ts">
+import UserList from './components/UserList.vue';
+</script>
+
+<route>
+{
+  "title": "用户列表",
+  "layout": "admin",
+  "requiresAuth": true,
+  "roles": ["admin"],
+  "icon": "User",
+  "keepAlive": true
+}
+</route>
+```
+
+#### 用户详情页面
+
+```vue
+<!-- src/pages/users/[id].vue -->
+<template>
+  <div class="user-detail">
+    <h1>用户详情</h1>
+    <UserInfo :user-id="userId" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useRoute } from '@/router/route.gen';
+import UserInfo from './components/UserInfo.vue';
+
+const route = useRoute<'users-[id]>();
+const userId = computed(() => route.params.id);
+</script>
+
+<route>
+{
+  "title": "用户详情",
+  "layout": "admin",
+  "requiresAuth": true,
+  "roles": ["admin", "moderator"],
+  "icon": "UserProfile"
+}
+</route>
+```
+
+#### 公开页面（无需认证）
+
+```vue
+<!-- src/pages/about.vue -->
+<template>
+  <div class="about-page">
+    <h1>关于我们</h1>
+    <p>这是关于页面</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+// 组件逻辑
+</script>
+
+<route>
+{
+  "title": "关于我们",
+  "layout": "default",
+  "requiresAuth": false,
+  "keepAlive": false
+}
+</route>
+```
+
+### 自定义元数据属性
+
+你可以在 `<route>` 块中添加任何自定义属性，并通过 TypeScript 模块扩展来获得类型支持：
+
+```typescript
+// types/route-meta.d.ts
+declare module '@zphhpzzph/vue-route-gen/runtime' {
+  interface RouteMeta {
+    icon?: string;
+    hidden?: boolean;
+    order?: number;
+    badge?: string | number;
+  }
+}
+```
+
+然后在组件中使用：
+
+```vue
+<route>
+{
+  "title": "仪表盘",
+  "icon": "Dashboard",
+  "hidden": false,
+  "order": 1,
+  "badge": "New"
+}
+</route>
+```
+
+### 构建时提取
+
+路由元数据在构建时被提取，零运行时开销：
+
+```typescript
+// 生成的 route.gen.ts
+export const routes = [
+  {
+    path: "/users/:id",
+    name: "users-[id]",
+    component: () => import("../pages/users/[id].vue"),
+    meta: {
+      title: "用户详情",
+      layout: "admin",
+      requiresAuth: true,
+      roles: ["admin", "moderator"],
+      icon: "UserProfile"
+    },
+    children: [],
+  }
+] satisfies RouteRecordRaw[];
+```
+
+### 在路由守卫中使用元数据
+
+```typescript
+// router/guards.ts
+import { router } from './router';
+
+router.beforeEach((to, from, next) => {
+  const meta = to.meta;
+
+  // 检查认证
+  if (meta.requiresAuth && !isAuthenticated()) {
+    return next({ name: 'login' });
+  }
+
+  // 检查角色权限
+  if (meta.roles && !hasRole(meta.roles)) {
+    return next({ name: 'forbidden' });
+  }
+
+  // 设置页面标题
+  if (meta.title) {
+    document.title = `${meta.title} - My App`;
+  }
+
+  next();
+});
+```
+
+### 与导航菜单结合
+
+```vue
+<!-- components/Sidebar.vue -->
+<script setup lang="ts">
+import { routes } from '@/router/route.gen';
+
+const menuItems = routes
+  .filter(route => route.meta && !route.meta.hidden)
+  .map(route => ({
+    title: route.meta?.title,
+    icon: route.meta?.icon,
+    path: route.path,
+    order: route.meta?.order ?? 999,
+  }))
+  .sort((a, b) => a.order - b.order);
+</script>
+
+<template>
+  <nav>
+    <router-link
+      v-for="item in menuItems"
+      :key="item.path"
+      :to="item.path"
+    >
+      <Icon :name="item.icon" />
+      {{ item.title }}
+    </router-link>
+  </nav>
+</template>
+```
+
+### 类型安全扩展
+
+通过 TypeScript 模块扩展，让你的自定义元数据属性类型安全：
+
+```typescript
+// types/route-meta.d.ts
+import '@zphhpzzph/vue-route-gen/runtime';
+
+declare module '@zphhpzzph/vue-route-gen/runtime' {
+  interface RouteMeta {
+    // 页面权限
+    permissions?: string[];
+    // 页面描述
+    description?: string;
+    // SEO 关键词
+    keywords?: string[];
+    // 是否在标签页中打开
+    openInTab?: boolean;
+    // 自定义中间件
+    middleware?: string[];
+  }
+}
+```
 
 ## 类型安全的路由
 
@@ -100,7 +463,7 @@ src/pages/
 ```typescript
 // 在 route.gen.ts 中生成
 export interface RouteParams {
-  'users-id': {
+  'users-[id]': {
     id: string;
   };
   // ... 其他路由
@@ -109,19 +472,49 @@ export interface RouteParams {
 
 ### 使用 useRoute
 
-生成的 `useRoute` Hook 为路由参数提供完整的类型推断：
+生成的 `useRoute` Hook 为路由参数和元数据提供完整的类型推断：
 
 ```typescript
 import { useRoute, ROUTE_NAME } 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 ✅
+
+  // 类型安全的元数据访问
+  console.log(route.meta.title);        // 类型为 string ✅
+  console.log(route.meta.layout);      // 类型为 string ✅
+  console.log(route.meta.requiresAuth); // 类型为 boolean ✅
+  console.log(route.meta.roles);       // 类型为 string[] ✅
+
+  // ❌ TypeScript 报错：属性不存在
+  // console.log(route.meta.wrongProp);
 }
 ```
 
+**Meta 类型自动推导**：
+- 从 `<route>` 块中提取的元数据会自动生成对应的 TypeScript 类型
+- 不同路由有不同的 meta 类型
+- 访问不存在的 meta 属性时 TypeScript 会报错
+
+**获取特定路由的 Meta 类型**：
+
+```typescript
+import type { RouteMetaByName } from '@/router/route.gen';
+
+// 获取特定路由的 meta 类型
+type UsersIdMeta = RouteMetaByName<typeof ROUTE_NAME.USERS_ID>;
+// 类型为：
+// {
+//   title: string;
+//   layout: string;
+//   requiresAuth: true;
+//   roles: string[];
+// } & RouteMeta
+```
+
 ### 使用 useRouter
 
 生成的 `useRouter` Hook 提供类型安全的导航：
@@ -216,6 +609,54 @@ function navigateToUser(userId: string) {
 
 ## 高级用法
 
+### 类型工具（从 `@zphhpzzph/vue-route-gen` 导入）
+
+包中提供了一些高级类型工具用于自定义类型安全的路由 hooks：
+
+```typescript
+import {
+  createTypedUseRoute,
+  createTypedUseRouter,
+  type TypedRoute,
+  type TypedRouter,
+  type TypedRouteLocation,
+} from '@zphhpzzph/vue-route-gen';
+```
+
+#### 创建自定义类型安全的 useRoute Hook
+
+如果需要为特定路由创建类型更精确的 hook：
+
+```typescript
+import { createTypedUseRoute } from '@zphhpzzph/vue-route-gen';
+
+// 创建针对特定路由的 hook
+const useUserDetailRoute = createTypedUseRoute<'users-[id]', { id: string }>();
+
+// 在组件中使用
+const route = useUserDetailRoute();
+console.log(route.params.id); // 类型为 string
+```
+
+#### 创建类型安全的 Router
+
+```typescript
+import { createTypedUseRouter } from '@zphhpzzph/vue-route-gen';
+
+const useRouter = createTypedUseRouter();
+const router = useRouter();
+
+// 导航时提供类型检查
+router.push({
+  name: 'users-[id]',
+  params: { id: '123' },
+});
+```
+
+**注意**：大多数情况下，你应该使用生成的 `useRoute()` 和 `useRouter()` hooks（从 `route.gen.ts` 导入），它们已经提供了完整的类型安全。这些底层类型工具主要用于高级自定义场景。
+
+> 💡 **深入阅读**：更多高级用法和完整文档，请参阅[文档索引](./docs/README.md)
+
 ### 获取特定路由的参数类型
 
 ```typescript
@@ -248,6 +689,15 @@ src/pages/
 1. **始终使用生成的常量**：使用 `ROUTE_NAME` 而不是硬编码字符串
 2. **利用类型推断**：让 TypeScript 为你检查路由参数
 3. **组合使用 Hooks**：`useRoute` 和 `useRouter` 提供完整的类型安全
+4. **使用 `<route>` 块定义元数据**：在组件中直接定义路由元数据，便于维护
+
+## 📚 文档
+
+查看完整文档：
+- **[文档索引](./docs/README.md)** - 所有文档���导航目录
+- **[更新日志](./CHANGELOG.md)** - 版本更新记录和迁移指南
+- **[路由元数据字面量类型推断](./docs/LiteralTypes.md)** - 精确的类型推断系统详解
+- **[Vite 插件使用指南](./docs/VitePlugin.md)** - 自动路由生成和智能更新
 
 ## 发布新版本（维护者）
 

package/dist/extract-meta.d.ts

@@ -1,17 +1,33 @@
-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 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 extractRouteConfig(filePath: string): RouteConfigOverride | undefined;
 /**
  * Parse Vue SFC and extract metadata from <route> custom block
+ * @deprecated Use extractRouteConfig() instead for full configuration support
  */
-export declare function extractRouteMeta(filePath: string): RouteMeta;
+export declare function extractRouteMeta(filePath: string): Record<string, any>;
+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;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAStE"}