🚀 ng-antd-admin

基于 Angular 22 的企业级中后台前端解决方案

!License !TypeScript !ng-zorro

在线预览 · 功能演示 · 问题反馈 · 更新日志

📖 项目简介

ng-antd-admin 是一个生产就绪的企业级中后台前端解决方案，基于 Angular 21 和 ng-zorro-antd 21 构建。

本项目紧跟 Angular 技术演进，充分利用最新特性，包括 Standalone Components、Zoneless Change Detection、Signals API 和 View Transitions，旨在为开发者提供一个现代化、高性能、易于维护的开发模板。

💡 为什么选择 ng-antd-admin？

• ✅ 技术前沿：率先拥抱 Angular 21 全新生态（Signals, Zoneless, Control Flow）。
• ✅ 性能卓越：全链路 OnPush 策略 + 智能路由复用 + 懒加载，体验媲美原生应用。
• ✅ 开箱即用：内置成熟的 RBAC 权限系统、主题切换、多页签管理等核心功能。
• ✅ 代码规范：集成严格的 ESLint + TypeScript + Prettier 配置，保障代码质量。
• ✅ 教学友好：代码注释详尽，不仅是脚手架，更是学习现代 Angular 的最佳实践。
• ✅ 持续维护：承诺跟随 Angular 官方版本长期更新迭代。

✨ 核心特性

🎯 技术栈一览

| 技术 | 版本 | 说明 | |------|------|------| | Angular | 21.0.3 | 核心框架，全面采用 Standalone 架构 | | TypeScript | 5.9.3 | 开发语言，开启严格模式 | | ng-zorro-antd | 21.0.0 | 企业级 UI 组件库 (Ant Design) | | RxJS | 7.8.0 | 响应式编程库 | | Less | 4.2.0 | CSS 预处理器 | | NestJS | 10.x | (可选) 后端服务框架 |

🚀 前沿特性详解

1️⃣ Standalone Components - 零 NgModule

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [CommonModule, NzButtonModule],
  templateUrl: './example.component.html'
})
export class ExampleComponent {}

2️⃣ Zoneless Change Detection - 性能飞跃

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection()
  ]
};

3️⃣ Signals API - 细粒度响应式

export class ThemeService {
  $isNightTheme = signal(false);
  $themesOptions = signal<SettingInterface>({ ...defaultOptions });
  
  toggleTheme() {
    this.$isNightTheme.update(v => !v);
  }
}

4️⃣ 智能路由复用 (Keep-Alive)

// 路由配置
data: { 
  key: 'user-list',           // 缓存唯一标识
  scrollContain: ['#table']   // 自动恢复滚动条位置
}

5️⃣ View Transitions API

provideRouter(routes, withViewTransitions({ skipInitialTransition: true }))

🏗️ 架构与功能

前端架构

• 模块化设计：清晰的目录结构 (core 核心, shared 共享, pages 页面, widget 组件)。
• 依赖注入：全面使用 inject() 函数，代码更简洁。
• 极致性能：全局 OnPush 策略 + 自定义预加载策略。

UI 功能

• 🌈 多主题：默认、暗黑、阿里云、紧凑 4 种风格一键切换。
• 🔖 多页签：支持右键菜单、拖拽排序，类浏览器体验。
• 📱 响应式：完美适配 PC、平板、手机等各种屏幕尺寸。
• 🔒 安全增强：内置锁屏功能、细粒度的按钮级权限控制。
• 🌍 多语言：内置简体中文、繁体中文、英文、越南语，运行时无刷新切换，覆盖菜单、Tab 标题、浏览器标签页、设置面板全链路。

后端集成 (可选)

• RBAC 模型：用户-角色-菜单-权限的精细化控制。
• JWT 认证：标准的 Token 身份验证流程。
• 完整模块：包含用户管理、部门管理、菜单管理等基础业务接口。

📦 快速开始

方式一：仅前端预览 (推荐体验)

# 1. 克隆
git clone https://github.com/huajian123/ng-antd-admin.git
2. 进入前端目录
cd ng-antd-admin/ui
3. 安装依赖
npm install
4. 启动项目
npm start
5. 访问 http://localhost:4201

也可直接在线预览：https://huajian123.github.io/ng-antd-admin/

方式二：完整全栈版 (前端 + 后端)

1. 启动后端 (NestJS)

# 1. 确保已安装 Docker
docker --version
2. 进入后端目录
cd nest-api
3. 启动 PostgreSQL 容器
docker-compose up -d
4. 导入数据库
使用 DataGrip/Navicat 等工具连接数据库
主机: localhost / 用户名: admin / 密码: 123456
数据库: ng-antd-admin-db
执行文件: nest-api/ng-antd-admin-db.sql
5. 安装依赖并启动
npm install
npm run start

2. 启动前端

# 1. 进入前端目录
cd ui
2. 修改环境environment.ts的  mockEnabled字段
  mockEnabled: true
3. 安装依赖
npm install
4. 启动开发服务器
npm start
5. 浏览器访问 http://localhost:4201

方式三：纯净版 (零业务代码)

https://gitee.com/hjxiaoqianduan/ng-ant-admin-pure

📚 核心开发指南

1. 路由复用配置

const routes: Routes = [
  {
    path: 'list',
    component: ListComponent,
    data: { 
      key: 'list-page',         // 必须：唯一标识
      shouldDetach: 'no',       // 可选：设为 'no' 则强制不缓存
      scrollContain: ['#list']  // 可选：缓存滚动条的选择器
    }
  }
];
// 切换页签时，进入新页签和离开旧页签会触发的组件生命周期钩子
export class ListComponent {
  _onReuseInit() {
    console.log('页面从缓存中恢复');
  }
  _onReuseDestroy() {
    console.log('页面被缓存');
  }
}

2. 响应式布局监听

// 注入服务
private winWidthService = inject(WindowsWidthService);
// 监听断点
this.winWidthService.getWindowWidthStore()
  .pipe(takeUntilDestroyed())
  .subscribe(width => {
    console.log('当前屏幕断点:', width); // xs, sm, md, lg, xl, xxl
  });

3. 多页签控制

// 场景A：“列表中点击详情按钮，打开新 Tab以查看数据详情”,请看在线地址上的演示，菜单为：功能>标签页操作>打开详情页1、打开详情页2、打开详情页3
{ 
  path: 'detail/:id', 
  component: DetailComponent, 
  data: { newTab: 'true', title: '详情', key: 'detail' } 
}
// 场景B：不同路由复用同一组件（如“添加”和“编辑”）,在当前页签中打开详情,场景请看在线地址上的演示，菜单为：系统管理>角色管理>设置权限
// 只要 title 相同，多页签系统会视为同一组业务
{ path: 'add', component: FormComponent, title: '用户管理' },
{ path: 'edit/:id', component: FormComponent, title: '用户管理' }

4. 国际化 (i18n)

项目使用 @ngx-translate/core 实现运行时多语言切换，无需刷新页面，语言偏好持久化到 localStorage。

支持的语言

| 语言 | 代码 | 翻译文件 | |------|------|----------| | 简体中文 | zh_CN | public/i18n/zh_CN.json | | 繁体中文 | zh_TW | public/i18n/zh_TW.json | | English | en_US | public/i18n/en_US.json | | Tiếng Việt | vi_VN | public/i18n/vi_VN.json |

翻译文件结构

每个语言文件按命名空间组织，新增语言只需复制一份并翻译内容：

{
  "common": {
    "search": "搜索",
    "logout": "退出登录"
  },
  "lang": {
    "zhCN": "简体中文",
    "zhTW": "繁體中文",
    "enUS": "English",
    "viVN": "Tiếng Việt"
  },
  "menu": {
    "default:dashboard": "Dashboard",
    "default:dashboard:analysis": "分析页"
  },
  "settings": {
    "themeStyle": "整体风格设置",
    "darkMode": "暗黑模式"
  }
}

在模板中使用翻译

<!-- 文本插值 -->
<span>{{ 'common.logout' | translate }}</span>
<!-- 属性绑定 -->
<input [placeholder]="'common.search' | translate" />
<!-- 动态 key（菜单名称场景） -->
<span>{{ 'menu.' + menu.code | translate }}</span>

路由 title 与 Tab 标题

路由的 title 字段存翻译 key，Tab 组件通过 | translate pipe 自动响应语言切换：

// 路由配置
{
  path: 'account',
  title: 'menu.default:system:account',  // 存 key，不存翻译后的文字
  data: { key: 'account' },
  loadComponent: () => import('./account.component')
}

切换语言

调用 LanguageService.setLang() 即可，它会同步更新 @ngx-translate、ng-zorro 组件库语言包和 localStorage：

private languageService = inject(LanguageService);
// 支持的 Lang 类型：'zh_CN' | 'zh_TW' | 'en_US' | 'vi_VN'
this.languageService.setLang('en_US');

新增一门语言

1. 在 public/i18n/ 下新建 xx_XX.json，参照现有文件翻译全部 key。
2. 在 language.service.ts 中扩展 Lang 类型，并在 nzLocaleMap 中加入对应的 ng-zorro locale。
3. 在 layout-head-right-menu.component.html 的语言菜单里新增一个
4. 选项。
5. 在所有语言文件的 lang 命名空间中加入新语言的显示名称 key。

🗂️ 版本说明

| ng-antd-admin 版本 | Angular 版本 | 说明 | 下载 | |-------------------|-------------|------|------| | Master (最新) | Angular 21+ | 全新架构，推荐使用 | 源码 | | v18.x | Angular 18 | 稳定版 | 下载 | | v17.x | Angular 17 | 引入 Signals | 下载 | | v15.x | Angular 15 | 传统 NgModule 版本 | 下载 |

⚠️ 注意：Angular 15+ 引入了 Standalone Components，项目结构变化较大。请根据您的团队技术栈选择对应的版本。

🤖 AI 辅助上手

本项目在 docs/meta-model/ 下维护了一套项目元模型文档，覆盖模块地图、核心流程、权限体系、状态管理、变更热区等。

如果你使用 AI 编程助手（Claude、Cursor、Copilot 等），可以直接把 meta-index.md 喂给 AI，让它快速建立对项目的完整认知，而不需要重新扫描整个仓库。

推荐用法

1. 快速了解项目结构

把 docs/meta-model/meta-index.md 的内容粘贴到对话里，然后问：

读完这份索引，帮我解释一下这个项目的整体架构

2. 定位某个功能的源码

参考 meta-index.md，帮我找到"多页签"功能的实现逻辑在哪里

3. 处理需求或 Bug

先读 docs/meta-model/meta-index.md，我要给账号管理页新增"批量禁用"功能，帮我定位影响面和需要改哪些文件

4. 理解某个核心流程

参考 docs/meta-model/flow-index.md，帮我梳理登录到权限加载的完整流程

文档索引

| 文档 | 内容 | |------|------| | meta-index.md | 总入口，先读这里 | | module-index.md | 所有页面模块地图 | | functional-inventory.md | 功能清单（功能 → 路由 → 源码） | | auth-login-index.md | 认证与权限体系 | | flow-index.md | 核心流程（登录、HTTP、路由复用等） | | change-hotspots.md | 高风险变更区，二次开发必读 |

元模型文档会随项目持续更新。如果你发现文档与代码不符，欢迎提 PR 修正。

🤝 参与贡献

我们非常欢迎各种形式的贡献！

• 🐛 提交 Bug：请详细描述复现步骤。
• 💡 功能建议：提出您想要的特性。
• 📝 文档改进：帮助完善文档和注释。
• 🔧 Pull Request：提交您的代码改进。

开发规范命令

npm run prettier      # 格式化代码
npm run lint          # ESLint 检查
npm run lint:fix      # 自动修复 Lint 问题
npm run lint:style    # 样式检查

⭐ Star History

如果这个项目对你有帮助，请给个 Star ⭐️ 支持一下！

本项目基于 MIT License 开源。

Made with ❤️ by huajian123