React-Admin-Vite

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

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

它使用了最新的前端技术栈，内置了 i18n 国际化解决方案，动态路由，权限验证，提炼了典型的业务模型，提供了丰富的功能组件。

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

访问地址：https://jiangyiming.cn/frontend/reactadmin

代码仓库：https://gitee.com/jiangsihan/react-admin-vite

🎨 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)	`''`

代码示例：获取主题状态

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

{
    "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

{
  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`)

权限控制深度集成在动态路由加载流程中：

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

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

在 src/routes/index.jsx 中通过 roles 字段配置菜单/路由的可见性：

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

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

🛠️ 3. 技术栈文档

技术	版本	说明
React	`^18.2.0`	核心框架
Vite	`^4.4.9`	极速构建工具
Ant Design	`^6.2.0`	企业级 UI 组件库
@ant-design/icons	`^6.1.0`	图标库
@ant-design/charts	`^2.6.7`	图表库AntV
React Router	`^6.10.0`	路由管理
Redux	`^4.2.1`	状态管理
Axios	`^1.3.6`	HTTP 请求库
i18next	`^25.7.4`	国际化方案
Less	`^4.1.3`	CSS 预处理器
moment	`^2.29.4`	日期处理库
react-activation	`^0.13.4`	页面组件缓存KeepAlive
crypto-js	`^4.1.1`	加密库

关键集成方案

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

⚙️ 4. 配置文件说明

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

配置参数解析

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：本地开发调试接口

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

场景 2：部署到生产环境

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

👨‍💻 5. 作者信息

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

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

目录CONTENT

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

React-Admin-Vite

🎨 1. 主题配置

主题定制选项

主题变量配置

代码示例：获取主题状态

🛣️ 2. 路由菜单配置

路由方案

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

返回后处理转为以下格式或静态路由配置（前端可直接使用）src/routes/index.jsx

权限控制

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

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

🛠️ 3. 技术栈文档

关键集成方案

⚙️ 4. 配置文件说明

配置参数解析

使用场景示例

👨‍💻 5. 作者信息

评论区

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

React-Admin-Vite

🎨 1. 主题配置

主题定制选项

主题变量配置

代码示例：获取主题状态

🛣️ 2. 路由菜单配置

路由方案

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

返回后处理转为以下格式或静态路由配置（前端可直接使用）src/routes/index.jsx

权限控制

动态路由模式 (ISROUTER: true)

静态路由模式 (ISROUTER: false)

🛠️ 3. 技术栈文档

关键集成方案

⚙️ 4. 配置文件说明

配置参数解析

使用场景示例

👨‍💻 5. 作者信息

评论区

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

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