@vlian/router 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,483 @@
+# @vlian/router
+
+基于 React Router 的高级路由管理包，支持动态路由、权限控制、路由转换等功能。
+
+## 📦 安装
+
+```bash
+npm install @vlian/router
+# 或
+pnpm add @vlian/router
+# 或
+yarn add @vlian/router
+```
+
+## 🔧 依赖要求
+
+本项目需要以下 peer dependencies：
+
+- `react`: ^19.2.0
+- `react-dom`: ^19.2.0
+- `react-router-dom`: ^7.0.0
+- `@ant-design/cssinjs`: >=1.24.0
+- `classnames`: >=2.3.0
+
+## ✨ 特性
+
+- 🚀 **动态路由加载** - 支持从 API 动态获取路由配置
+- 🔐 **权限控制** - 支持基于角色和登录状态的权限控制
+- 🎨 **布局系统** - 灵活的布局配置，支持嵌套布局
+- ⚡ **懒加载** - 路由组件自动懒加载，优化首屏性能
+- 🔄 **路由转换** - 将自定义路由格式自动转换为 React Router 格式
+- 📱 **子应用支持** - 支持微前端子应用模式
+- 🎯 **类型安全** - 完整的 TypeScript 类型定义
+- 🎭 **加载状态** - 内置加载动画，支持自定义加载组件
+- 🛡️ **错误处理** - 支持自定义错误边界组件
+- 📋 **菜单生成** - 自动从路由配置生成菜单数据
+
+## 📖 使用指南
+
+### 基础用法
+
+```tsx
+import { RouterProvider } from '@vlian/router';
+import type { RouteItem } from '@vlian/router';
+
+// 定义路由组件导入映射
+const imports = {
+  // 页面组件
+  pages: {
+    root: () => import('./pages/Root'),
+    home: () => import('./pages/Home'),
+    about: () => import('./pages/About'),
+    '404': () => import('./pages/NotFound'),
+  },
+  // 布局组件
+  layouts: {
+    root: () => import('./layouts/RootLayout'),
+    admin: () => import('./layouts/AdminLayout'),
+  },
+  // 加载组件
+  loadings: {
+    root: () => import('./components/Loading'),
+  },
+  // 错误组件
+  errors: {
+    root: () => import('./components/ErrorBoundary'),
+  },
+};
+
+// 获取动态路由的函数
+const fetchRoutes = async (): Promise<RouteItem[]> => {
+  const response = await fetch('/api/routes');
+  return response.json();
+};
+
+function App() {
+  return (
+    <RouterProvider
+      fetchRoutes={fetchRoutes}
+      imports={imports}
+    />
+  );
+}
+```
+
+### 路由配置格式
+
+路由配置使用 `RouteItem` 类型，支持以下字段：
+
+```typescript
+type RouteItem = {
+  // 布局组件的 key（对应 imports.layouts 中的键）
+  layout?: string | null;
+  
+  // 页面组件的 key（对应 imports.pages 中的键）
+  page?: string | null;
+  
+  // 加载组件的 key（对应 imports.loadings 中的键）
+  loading?: string | null;
+  
+  // 错误组件的 key（对应 imports.errors 中的键）
+  errors?: string | null;
+  
+  // 路由名称，唯一标识
+  name: string;
+  
+  // 路由路径
+  path: string | undefined;
+  
+  // 是否为分组路由（不渲染自身，只作为容器）
+  isGroup?: boolean;
+  
+  // 是否启用重定向到第一个子路由
+  enableRedirection?: boolean;
+  
+  // 路由元数据
+  handle: RouteItemHandle;
+  
+  // 子路由
+  children?: RouteItem[];
+};
+
+type RouteItemHandle = {
+  // 路由标题
+  title: string;
+  
+  // 国际化 key
+  i18nKey?: string;
+  
+  // 排序顺序
+  order: number;
+  
+  // 图标
+  icon?: string;
+  
+  // 在菜单中隐藏
+  hideInMenu?: boolean;
+  
+  // 隐藏页脚
+  hideFooter?: boolean;
+  
+  // 保活（Keep Alive）
+  keepAlive?: boolean;
+  
+  // 是否需要登录
+  needLogin?: boolean;
+  
+  // 允许访问的角色列表
+  roles?: string[];
+  
+  // 其他自定义字段
+  [key: string]: unknown;
+};
+```
+
+### 路由配置示例
+
+```typescript
+const routes: RouteItem[] = [
+  {
+    name: 'home',
+    path: '/home',
+    page: 'home',
+    layout: 'root',
+    handle: {
+      title: '首页',
+      order: 1,
+      icon: 'home',
+      needLogin: true,
+    },
+  },
+  {
+    name: 'admin',
+    path: '/admin',
+    layout: 'admin',
+    isGroup: true,
+    enableRedirection: true,
+    handle: {
+      title: '管理后台',
+      order: 2,
+      icon: 'admin',
+      roles: ['admin'],
+    },
+    children: [
+      {
+        name: 'admin-users',
+        path: '/admin/users',
+        page: 'adminUsers',
+        handle: {
+          title: '用户管理',
+          order: 1,
+        },
+      },
+      {
+        name: 'admin-settings',
+        path: '/admin/settings',
+        page: 'adminSettings',
+        handle: {
+          title: '系统设置',
+          order: 2,
+        },
+      },
+    ],
+  },
+];
+```
+
+### 使用路由 Hook
+
+```tsx
+import { useRoute } from '@vlian/router';
+
+function MyComponent() {
+  const route = useRoute();
+  
+  // route 包含以下信息：
+  // - id: 路由 ID
+  // - pathname: 当前路径
+  // - search: 查询字符串
+  // - hash: 哈希值
+  // - query: 解析后的查询参数对象
+  // - fullPath: 完整路径（pathname + search + hash）
+  // - handle: 路由元数据
+  // - data: 路由数据（来自 loader）
+  
+  return (
+    <div>
+      <h1>{route.handle?.title}</h1>
+      <p>当前路径: {route.pathname}</p>
+      <p>查询参数: {JSON.stringify(route.query)}</p>
+    </div>
+  );
+}
+```
+
+### 使用导航工具
+
+在子应用模式下，可以通过 `window.$router` 访问导航工具：
+
+```typescript
+// 导航到指定路径
+window.$router.push('/home');
+
+// 带查询参数导航
+window.$router.push('/users', { page: 1, size: 10 });
+
+// 替换当前历史记录
+window.$router.replace('/login');
+
+// 返回上一页
+window.$router.back();
+
+// 前进
+window.$router.forward();
+
+// 跳转到首页
+window.$router.goHome();
+
+// 向上导航（父路由）
+window.$router.navigateUp();
+
+// 重新加载
+window.$router.reload();
+
+// 使用 React Router 的 navigate 方法
+window.$router.navigate('/path', { replace: true });
+```
+
+### 生成菜单数据
+
+```tsx
+import { formatMenusDate } from '@vlian/router';
+import { useRoute } from '@vlian/router';
+
+function Menu() {
+  const route = useRoute();
+  // 假设你有路由数据
+  const routes = route.dynamicRoutes || [];
+  const menus = formatMenusDate(routes);
+  
+  return (
+    <ul>
+      {menus.map(menu => (
+        <li key={menu.key}>
+          <a href={menu.path}>{menu.name}</a>
+          {menu.children && (
+            <ul>
+              {menu.children.map(subMenu => (
+                <li key={subMenu.key}>
+                  <a href={subMenu.path}>{subMenu.name}</a>
+                </li>
+              ))}
+            </ul>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### RouterProvider 配置选项
+
+```tsx
+<RouterProvider
+  // 必需：获取动态路由的函数
+  fetchRoutes={fetchRoutes}
+  
+  // 必需：组件导入映射
+  imports={imports}
+  
+  // 可选：根路由配置（默认使用内置配置）
+  rootRoutes={customRootRoutes}
+  
+  // 可选：静态路由（默认包含 404 路由）
+  staticRoutes={customStaticRoutes}
+  
+  // 可选：React Router 配置选项
+  options={{
+    future: {
+      v7_startTransition: true,
+      v7_relativeSplatPath: true,
+    },
+  }}
+  
+  // 可选：是否为子应用模式（默认 false）
+  isSubApp={false}
+  
+  // 可选：自定义加载组件
+  loadingRender={<CustomLoading />}
+  
+  // 可选：加载动画大小（默认 '24px'）
+  loadingSize="32px"
+  
+  // 可选：加载动画颜色（默认 'currentColor'）
+  loadingColor="#1890ff"
+  
+  // 可选：加载动画透明度（默认 0.25）
+  loadingOpacity={0.3}
+/>
+```
+
+## 🎨 组件导出
+
+### RouterProvider
+
+路由提供者组件，用于初始化和管理路由系统。
+
+### Hooks
+
+- `useRoute<T>()` - 获取当前路由信息
+- `useRouterTransform()` - 路由转换 Hook（内部使用）
+
+### 工具函数
+
+- `navigator(router)` - 创建导航工具对象
+- `formatMenusDate(routes)` - 将路由配置格式化为菜单数据
+
+## 🔍 类型定义
+
+主要类型定义：
+
+- `RouteItem` - 路由项类型
+- `RouteItemHandle` - 路由元数据类型
+- `RouteMapType` - 路由组件映射类型
+- `RouterProviderProps` - RouterProvider 属性类型
+- `RouterContextType` - 路由上下文类型
+- `FormattedMenuItem` - 格式化后的菜单项类型
+
+## 🚀 高级用法
+
+### 自定义根路由
+
+```typescript
+import { RouteItem } from '@vlian/router';
+
+const customRootRoutes: RouteItem = {
+  name: 'root',
+  path: '/',
+  page: 'root',
+  layout: 'customRoot',
+  handle: {
+    title: '应用根',
+    order: 0,
+  },
+  children: [],
+};
+
+<RouterProvider
+  fetchRoutes={fetchRoutes}
+  imports={imports}
+  rootRoutes={customRootRoutes}
+/>
+```
+
+### 自定义静态路由
+
+```typescript
+import { RouteItem } from '@vlian/router';
+
+const customStaticRoutes: RouteItem[] = [
+  {
+    name: '403',
+    path: '/403',
+    page: 'forbidden',
+    handle: {
+      title: '无权限',
+      order: 99999997,
+    },
+  },
+  {
+    name: '404',
+    path: '/404',
+    page: 'notFound',
+    handle: {
+      title: '页面不存在',
+      order: 99999998,
+    },
+  },
+  {
+    name: 'notFound',
+    path: '*',
+    page: 'notFound',
+    handle: {
+      title: '页面不存在',
+      order: 99999999,
+    },
+  },
+];
+
+<RouterProvider
+  fetchRoutes={fetchRoutes}
+  imports={imports}
+  staticRoutes={customStaticRoutes}
+/>
+```
+
+### 子应用模式
+
+在微前端场景中，可以启用子应用模式，通过 `window.$router` 访问路由导航：
+
+```tsx
+<RouterProvider
+  fetchRoutes={fetchRoutes}
+  imports={imports}
+  isSubApp={true}
+/>
+```
+
+## 📝 注意事项
+
+1. **路由名称唯一性**：每个路由的 `name` 字段必须唯一，它作为路由的唯一标识符。
+
+2. **组件导出格式**：所有通过 `imports` 导入的组件必须使用默认导出，例如：
+   ```typescript
+   // ✅ 正确
+   export default function MyPage() { ... }
+   
+   // ❌ 错误
+   export function MyPage() { ... }
+   ```
+
+3. **布局和页面**：
+   - 如果路由有 `layout` 且不是分组路由，会使用布局组件包裹页面
+   - 如果路由有 `page` 且有子路由，会自动创建 index 路由来渲染页面
+   - 分组路由（`isGroup: true`）不会渲染自身，只作为子路由的容器
+
+4. **路由排序**：子路由会根据 `handle.order` 自动排序，数值越小越靠前。
+
+5. **权限控制**：当前版本的路由转换支持权限相关的元数据配置，但具体的权限验证逻辑需要在业务层面实现。
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+MIT
+
+## 🔗 相关链接
+
+- [React Router 文档](https://reactrouter.com/)
+- [React 文档](https://react.dev/)

package/dist/styles/square-rotate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"square-rotate.d.ts","sourceRoot":"","sources":["../../src/styles/square-rotate.ts"],"names":[],"mappings":"AA0CA,eAAO,MAAM,sBAAsB;;;;CAiBlC,CAAC"}
+{"version":3,"file":"square-rotate.d.ts","sourceRoot":"","sources":["../../src/styles/square-rotate.ts"],"names":[],"mappings":"AAyCA,eAAO,MAAM,sBAAsB;;;;CAiBlC,CAAC"}

package/dist/styles/square-rotate.js

@@ -1,5 +1,4 @@
-import Keyframes from '@ant-design/cssinjs/lib/Keyframes';
-import { useStyleRegister } from '@ant-design/cssinjs';
+import { Keyframes, useStyleRegister } from '@ant-design/cssinjs';
 // 定义动画
 var squareRotate2Animation = new Keyframes('square-rotate-2-animation', {
     '0%': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vlian/router",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "基于 React Router 的路由管理包，支持动态路由、权限控制、路由转换等功能",
   "keywords": [
     "router",