# React-admin-vite

**Repository Path**: jiangsihan/react-admin-vite

## Basic Information

- **Project Name**: React-admin-vite
- **Description**: 基于 React 18 + Vite 4 + Ant Design 6 的现代化后台管理系统模板。适用于后台管理 Web 项目的二次开发，帮助开发人员快速搭建后台管理项目。它使用了最新的前端技术栈，内置了 i18n 国际化解决方案，动态路由，权限验证，提炼了典型的业务模型，提供了丰富的功能组件。访问地址：https://jiangyiming.cn/frontend/reactadmin
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: https://jiangyiming.cn/frontend/reactadmin
- **GVP Project**: No

## Statistics

- **Stars**: 40
- **Forks**: 16
- **Created**: 2023-04-26
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, vite, Ant-Design

## README

# React-Admin-Vite

基于 React 18 + Vite 4 + Ant Design 6 的现代化后台管理系统模板。

react-admin-vite 适用于后台管理 web 项目的二次开发，帮助开发人员快速搭建后台管理项目。

**请仔细阅读本文档以后再进行使用！**

访问地址：<a target="_blank" href="https://jiangyiming.cn/frontend/reactadmin">https://jiangyiming.cn/frontend/reactadmin</a>

<!-- 完整文档：<a target="_blank" href="https://jiangyiming.cn/react-admin-vite-press">https://jiangyiming.cn/react-admin-vite-press</a> -->

代码仓库：<a target="_blank" href="https://gitee.com/jiangsihan/react-admin-vite">https://gitee.com/jiangsihan/react-admin-vite</a>

## 🎨 1. 主题配置

本项目采用 `ThemeContext` 进行全局主题状态管理，结合 Ant Design v5+ 的 Design Token 能力，实现了灵活的主题定制方案。

### 主题定制选项

用户可以通过点击右上角的"设置"按钮打开主题配置抽屉，支持以下配置项：

- **整体风格**：
  - 亮色菜单风格 (Light)
  - 暗色菜单风格 (Dark)
  - 暗黑模式 (Real Dark)
  - 跟随系统 (Auto)
- **主题色**：提供 8 种预设颜色（拂晓蓝、薄暮、火山、日暮、明青、极光绿、极客蓝、酱紫）。
- **导航模式**：
  - 侧边菜单布局 (Broadside)
  - 顶部菜单布局 (Top)
  - 混合菜单布局 (Left - 侧边栏+顶部栏)
- **内容区域**：
  - 顶栏固定
  - 内容区域宽度（流式/定宽）
- **其他设置**：
  - 色弱模式
  - 灰色模式
  - 紧凑模式
  - 全局圆角设置

### 主题变量配置

主题状态通过 `src/components/ThemeContext.jsx` 管理，并持久化存储在 Cookie 中。主要变量包括：

| 变量名 | 说明 | 默认值 |
|Data | Description | Default |
|---|---|---|
| `isDark` | 是否开启暗黑模式 | `false` |
| `primaryColor` | 主题主色 | `#1890ff` |
| `borderRadius` | 全局圆角 | `6` |
| `navTheme` | 导航栏主题样式 | `light` |
| `layoutMode` | 整体布局模式 | `broadside` |
| `weakOrGray` | 特殊模式(weak/gray) | `''` |

### 代码示例：获取主题状态

```jsx
import { useThemeContext } from "@/components/ThemeContext";

const MyComponent = () => {
  const { isDark, primaryColor, updateTheme } = useThemeContext();

  return (
    <div style={{ color: primaryColor }}>
      当前模式：{isDark ? "暗黑" : "亮色"}
    </div>
  );
};
```

---

## 🛣️ 2. 路由菜单配置

项目支持**本地路由**和**动态路由**两种模式，通过 `public/config/index.js` 中的 `ISROUTER` 参数控制。

### 路由方案

- **本地路由 (`ISROUTER: false`)**：

  - 路由定义在 `src/routes/index.jsx`。
  - 适合简单的静态展示型项目。

- **动态路由 (`ISROUTER: true`)**：
  - 菜单数据由后端接口返回（或模拟接口）。
  - 数据存储在 LocalStorage 中 (`ROOT_APP_INFO`)。
  - 通过 `src/routes/setRouter.js` 中的 `setmenu` 方法将后端数据转换为 React Router 可用的路由结构。
  - **组件映射**：后端返回的 `component` 字符串（如 `"dashboard/analysis"`）会自动映射到 `src/pages/dashboard/analysis/index.jsx`。

### 动态路由数据结构规范 (后端返回格式)参考 src/assets/res.router.json

```json
{
    "id": "...",
    "name": "菜单名称",
    "url": "/path/to/menu",
    "component": "component/path",
    "redirect": null,
    "icon": "IconName",
    "isRoute": boolean,      // 是否路由菜单
    "keepAlive": boolean,    // 是否缓存
    "hidden": 0/1,           // 是否隐藏 (1=隐藏, 0=显示)
    "alwaysShow": boolean,   // 是否聚合路由
    "internalOrExternal": 0/1， // 外部链接 (1=是, 0=否)
    "children": [
        {
            "id": "...",
            "name": "子菜单名称",
            "url": "/path/to/submenu",
            "component": "component/path",
            "redirect": null,
            "icon": "IconName",
            "isRoute": boolean,
            "keepAlive": boolean,
            "hidden": 0/1,
            "alwaysShow": boolean,
            "internalOrExternal": 0/1
        }
    ]
    ...
}
```
#### 返回后处理转为以下格式或静态路由配置（前端可直接使用）src/routes/index.jsx
```json
{
  label: "菜单名称",
  key: "/dashboard/analysis",
  element: lazy(() => import("@/pages/dashboard/analysis")),
  icon: <HomeOutlined />,
  disabled: false,
  hidden: false,
  route: true,
  keepAlive: false,
  alwaysShow: false,
  internalOrExternal: false,
  children: [
    {
      label: "子菜单名称",
      key: "/path/to/submenu",
      element: lazy(() => import("@/pages/component/path")),
      icon: <IconName />,
      disabled: false,
      hidden: false,
      route: true,
      keepAlive: false,
      alwaysShow: false,
      internalOrExternal: false,
    }
  ]
},
```
### 权限控制

#### 动态路由模式 (`ISROUTER: true`)
权限控制深度集成在动态路由加载流程中：

1. 用户登录后获取 `menuList`。
2. 前端根据 `menuList` 动态生成路由表。
3. 未在 `menuList` 中的路由将不会被注册，访问会进入 404 或 403 页面。
4. 关于菜单权限在角色授权里动态配置。

#### 静态路由模式 (`ISROUTER: false`)
在 `src/routes/index.jsx` 中通过 `roles` 字段配置菜单/路由的可见性：

```javascript
{
    // ... 其他配置
    roles: ['admin', 'manager'], // 仅 admin 和 manager 角色可见
}
```

- **不配置 `roles` 或为 `undefined`**: 所有用户可见。
- **配置为 `[]` (空数组)**: 任何角色都不可见（隐藏）。
- **配置为 `['roleA', 'roleB']`**: 仅拥有 `roleA` 或 `roleB` 的用户可见。


---

## 🛠️ 3. 技术栈文档

| 技术                  | 版本      | 说明             |
| --------------------- | --------- | ---------------- |
| [**React**](https://react.dev/)             | `^18.2.0` | 核心框架         |
| [**Vite**](https://vitejs.dev/)              | `^4.4.9`  | 极速构建工具     |
| [**Ant Design**](https://ant.design/)        | `^6.2.0`  | 企业级 UI 组件库 |
| [**@ant-design/icons**](https://ant.design/components/icon) | `^6.1.0`  | 图标库           |
| [**@ant-design/charts**](https://charts.ant.design/) | `^2.6.7`  | 图表库AntV       |
| [**React Router**](https://reactrouter.com/)      | `^6.10.0` | 路由管理      |
| [**Redux**](https://redux.js.org/)             | `^4.2.1`  | 状态管理         |
| [**Axios**](https://axios-http.com/)             | `^1.3.6`  | HTTP 请求库      |
| [**i18next**](https://www.i18next.com/)           | `^25.7.4` | 国际化方案       |
| [**Less**](https://lesscss.org/)              | `^4.1.3`  | CSS 预处理器     |
| [**moment**](https://momentjs.com/)            | `^2.29.4` | 日期处理库       |
| [**react-activation**](https://github.com/CJY0208/react-activation)  | `^0.13.4` | 页面组件缓存KeepAlive  |
| [**crypto-js**](https://cryptojs.gitbook.io/docs/)         | `^4.1.1`  | 加密库             |
<!-- | **Tailwind CSS**      | `^4.1.18` | 原子化 CSS 框架   | -->

### 关键集成方案

- **路由懒加载**：使用 `React.lazy` + `import.meta.glob` 实现组件的按需加载。
- **全局状态**：使用 `ThemeContext` 管理 UI 状态，`Redux` 管理业务数据。
- **国际化**：集成 `react-i18next`，支持中英切换。

---

## ⚙️ 4. 配置文件说明

全局配置文件位于 `public/config/index.js`，该文件在运行时加载，修改后无需重新打包即可生效。

### 配置参数解析

```javascript
window.envConfig = {
  // 环境地址标识
  // 0: 开发环境 (使用本地代理)
  // 1: 测试环境
  // 2: 生产环境
  key: 2,

  // 是否开启代理 (仅在 key=0 时有效)
  // true: 使用 /api/ 前缀进行代理
  // false: 直接请求 noProxyUrl
  proxy: true,

  // 路由模式开关
  // true: 请求后端获取动态菜单
  // false: 使用 src/routes/index.jsx 中的本地配置
  ISROUTER: true,

  // 系统显示的名称
  ROOT_APP_NAME: "React-admin-vite",

  // 本地存储 Key (防止多项目部署在同一域名下缓存冲突)
  ROOT_APP_INFO: "React-Admin-Info",

  // API 基础配置 (通常在下方的 switch 语句中根据 key 自动设置)
  API_BASE_URL: "",
  API_BASE_PORT: "",
  API_BASE_TIMEOUT: 10, // 请求超时时间 (秒)
};
```

### 使用场景示例

**场景 1：本地开发调试接口**

```javascript
// public/config/index.js
window.envConfig = {
  key: 0,
  proxy: true, // 开启代理，配合 vite.config.js 中的 proxy 配置
  // ...
};
```

**场景 2：部署到生产环境**

```javascript
// public/config/index.js
window.envConfig = {
  key: 2,
  // ...
};
// 底部 switch 自动匹配：
// window.envConfig['API_BASE_URL'] = 'https://jiangyiming.cn/'
```

---

## 👨‍💻 5. 作者信息

- **作者**：江一铭
- **个人网站**：[https://jiangyiming.cn/](https://jiangyiming.cn/)
- **联系邮箱**：jianghaoluck@163.com
- **更新时间**：2026-01-15

---

> 文档最后更新时间：2026-01-15