# 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-02-11

## Categories & Tags

**Categories**: Uncategorized

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

## README

# React-Admin-Vite

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

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

推荐node版本：v18+

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

访问地址：<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)
  - 分栏菜单布局 (Double)
  - 混合菜单布局 (Composite)
- **内容区域**：
  - 顶栏固定
  - 内容区域宽度（流式/定宽）
- **其他设置**：
  - 色弱模式
  - 灰色模式
  - 紧凑模式
  - 全局圆角设置
  - 侧边栏宽度设置

### 主题变量配置

主题状态通过 `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`)，权限的配置方式也有所区别。

#### 1. 动态路由模式 (`ISROUTER: true`)

在此模式下，权限控制主要由**后端**主导。

- **菜单/路由权限**：
  1. 用户登录后，后端根据用户角色计算出该用户可访问的菜单列表。
  2. 前端通过接口获取 `menuList`。
  3. 前端利用 `src/routes/setRouter.js` 将菜单数据动态转换为 React 路由并注册。
  4. **特点**：前端无需维护角色与菜单的映射关系，完全由后端返回的数据决定显示哪些菜单。

- **按钮/操作权限**：
  1. 后端在返回用户信息或菜单信息时，同时返回该用户拥有的按钮权限标识列表（如 `['user:add', 'user:delete']`）。
  2. 前端将权限列表存入 Store 或 Context。
  3. 组件中使用 `AuthButton` 或 `usePermission` 判断权限。

#### 2. 静态路由模式 (`ISROUTER: false`)

在此模式下，权限控制完全在**前端**配置。

- **菜单/路由权限**：
  在 `src/routes/index.jsx` 中，通过为路由对象添加 `roles` 字段来控制可见性。

  ```javascript
  // src/routes/index.jsx
  {
      label: "用户管理",
      key: "/system/user",
      // ...
      roles: ['admin', 'manager'], // 仅 admin 和 manager 角色可见
  }
  ```
  - **未配置 `roles`**：所有登录用户均可见。
  - **配置为 `[]`**：所有用户均不可见（隐藏路由）。

- **按钮/操作权限**：
  通过 `src/routes/buttonPermissionConfig.js` 文件配置角色与按钮权限的映射。

  ```javascript
  // src/routes/buttonPermissionConfig.js
  export const ROLE_PERMISSIONS = {
      'admin': ['user:add', 'user:edit', 'user:delete'],
      'editor': ['user:edit']
  };
  ```
  前端根据当前用户的角色，自动加载对应的按钮权限列表。

#### 按钮/细粒度权限控制 (通用)

项目提供统一的按钮权限配置方案，支持静态路由 (`ISROUTER: false`) 和动态路由模式。

**配置文件**: `src/routes/buttonPermissionConfig.js`

```javascript
/**
 * 角色-按钮权限映射配置
 * Key: 角色代码 (role code)
 * Value: 该角色拥有的权限标识数组 (permission identifiers)
 */
export const ROLE_PERMISSIONS = {
    'admin': [
        'user:add',
        'user:edit',
        'user:delete',
        'role:list'
    ],
    'editor': [
        'user:list',
        'article:publish'
    ],
    'guest': [
        'article:view'
    ]
};
```

**使用方式**:

在组件中使用 `AuthButton` 或 `usePermission` hook 进行权限控制。

```jsx
// 1. 使用 AuthButton 组件
import AuthButton from '@/components/AuthButton';

<AuthButton perms="sys:user:add">
  <Button type="primary">添加用户</Button>
</AuthButton>

// 2. 使用 hasPermission 工具函数
import { hasPermission } from '@/utils/permission';

const MyComponent = () => {
  // 条件渲染
  if (!hasPermission('sys:user:view')) {
      return <div>无权限</div>;
  }
  
  return (
    hasPermission('sys:user:edit') && <Button>编辑</Button>
  );
};

// 3. 使用 usePermission hook (推荐)
import usePermission from '@/hooks/usePermission';

const MyComponent = () => {
  const { hasPermission } = usePermission();
  
  return (
    hasPermission('sys:user:edit') && <Button>编辑</Button>
  );
};
```

---

## 🛠️ 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
>
> 注：本项目后端基于 Spring Boot + Mybatis-Plus + MySQL + Maven 开发，后端代码暂未开源。如有需要，欢迎联系作者。