Z-Admin

一个基于 React + Vite + Ant Design 构建的现代化后台管理系统模板。

功能特性

• 🎨 主题系统 - 支持亮色/暗色模式切换，自定义主题色，紧凑模式，多种预设主题风格
• 📐 多种布局 - 侧边栏模式、顶部模式、精简模式等多种导航布局
• 🔧 配置面板 - 可视化配置系统，实时预览效果
• 🌐 国际化 - 内置多语言支持
• 📊 页面过渡 - 多种页面切换动画效果，视图过渡动画
• 🏷️ 多标签页 - 支持标签页导航，拖拽排序，多种样式风格
• 📝 代码生成 - 基于 Plop.js 的代码文件自动生成
• 🛡️ 错误处理 - 完善的错误日志收集与打印
• 📦 状态管理 - 基于 Zustand 的轻量级状态管理
• 🎯 权限控制 - 路由权限与菜单权限控制
• 🧩 组件库 - 内置丰富的自定义组件（图标选择器、链接预览、滑块验证码等）

技术栈

核心框架

• React 18 - UI 框架
• Vite - 构建工具
• React Router - 路由管理
• Zustand - 状态管理

UI 组件

• Ant Design 6 - UI 组件库
• Ant Design Pro Components - 业务组件
• Ant Design Charts - 图表组件
• Ant Design Style - CSS-in-JS 样式方案

工具库

• ahooks - React Hooks 工具库
• axios - HTTP 请求库
• @hello-pangea/dnd - 拖拽功能

动画效果

• Animate.css - CSS 动画库
• React Transition Group - React 过渡动画
• View Transitions API - 视图过渡动画

其他

• React Markdown - Markdown 渲染
• CodeMirror - 代码编辑器
• Tailwind CSS - 实用优先 CSS 框架

快速开始

安装依赖

pnpm install

启动开发服务器

pnpm run dev

构建生产版本

pnpm run build

预览生产版本

pnpm run preview

代码检查

pnpm run lint

项目结构

z-admin/
├── docs/                        # 文档
│   ├── components/              # 组件文档
│   ├── guide/                   # 指南文档
│   ├── layout/                  # 布局文档
│   └── theme/                   # 主题文档
├── packages/                    # 子包（Monorepo）
│   ├── components/              # 组件库
│   │   ├── IconPicker/          # 图标选择器
│   │   ├── LinkPreview/         # 链接预览
│   │   ├── Markdown/            # Markdown 渲染
│   │   ├── Marquee/             # 跑马灯
│   │   ├── ShinyText/           # 流光文字
│   │   ├── SliderCaptcha/       # 滑块验证码
│   │   └── SparklesText/        # 闪烁文字
│   ├── layout/                  # 布局包
│   │   ├── components/          # 布局组件
│   │   │   ├── Breadcrumb/      # 面包屑
│   │   │   ├── ConfigPanel/     # 配置面板
│   │   │   ├── Header/          # 头部
│   │   │   ├── TabBar/          # 标签栏
│   │   │   ├── Toolbar/         # 工具栏
│   │   │   ├── UserInfo/        # 用户信息
│   │   │   └── ...
│   │   ├── hooks/               # 自定义 Hooks
│   │   ├── store/               # 状态管理
│   │   └── utils/               # 工具函数
│   └── theme/                   # 主题包
│       ├── bootstrapTheme.ts    # Bootstrap 主题
│       ├── glassTheme.ts        # 玻璃拟态主题
│       ├── illustrationTheme.ts # 插画主题
│       └── muiTheme.ts          # Material UI 主题
├── src/                         # 主应用
│   ├── apis/                    # API 接口
│   ├── assets/                  # 静态资源
│   ├── pages/                   # 页面组件
│   │   ├── index/               # 首页
│   │   └── mall/                # 商城管理
│   ├── store/                   # 应用状态
│   ├── types/                   # TypeScript 类型定义
│   ├── utils/                   # 工具函数
│   ├── App.tsx                  # 应用入口
│   └── main.tsx                 # 入口文件
├── public/                      # 静态资源
├── vite-config/                 # Vite 配置
├── ts-config/                   # TypeScript 配置
├── .env                         # 环境变量
├── .env.development             # 开发环境变量
├── .env.production              # 生产环境变量
├── pnpm-workspace.yaml          # pnpm 工作区配置
├── vite.config.ts               # Vite 主配置
├── tsconfig.json                # TypeScript 配置
└── package.json                 # 根目录依赖

子包说明

@z-admin/components

提供丰富的自定义 UI 组件：

• ZIconPicker - 图标选择器，支持 32+ 个主流图标库
• ZLinkPreview - 链接悬停预览
• ZMarkdown - Markdown 渲染组件
• ZMarquee - 跑马灯效果
• ZShinyText - 流光文字效果
• ZSliderCaptcha - 滑块验证码
• ZSparklesText - 闪烁文字效果

@z-admin/layout

提供完整的布局系统：

• Layout - 主布局组件
• LayoutProvider - 布局配置提供者
• Header - 头部组件（集成 TabBar 和 Toolbar）
• TabBar - 标签栏管理
• Toolbar - 工具栏（面包屑、全屏、主题切换）
• Breadcrumb - 面包屑导航
• UserInfo - 用户信息组件

@z-admin/theme

提供多种预设主题风格：

• useBootstrapTheme - Bootstrap 风格主题
• useGlassTheme - 玻璃拟态主题
• useIllustrationTheme - 插画风格主题
• useMuiTheme - Material UI 风格主题

配置说明

主题配置

在 packages/layout/defaultSetting.ts 中可以修改默认配置：

export const defaultSetting = {
  theme: {
    themeColor: '#1677ff',
    darkMode: 'auto',
    compactMode: false,
    happyEffect: false
  },
  menu: {
    menuType: 'side',
  },
  toolbar: {
    breadcrumb: {
      isEnableBreadcrumb: true,
      style: 'modern'
    }
  }
}

路由配置

基于文件系统的路由，在 src/pages/ 目录下创建文件即可自动生成路由。

开发指南

Git 提交规范

git add .
git commit -m "feat: 添加新功能"
git push origin master

Commit 类型

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• perf: 性能优化
• test: 测试相关
• chore: 构建/工具相关

浏览器支持

• Chrome >= 87
• Firefox >= 78
• Safari >= 14
• Edge >= 88

License

MIT

贡献

欢迎提交 Issue 和 Pull Request。