README.md

以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

CoolAdmin - 现代 Bootstrap 5 管理仪表盘模板

CoolAdmin Dashboard

CoolAdmin 是一个现代、响应式且功能丰富的管理仪表盘模板，基于 Bootstrap 5.3.8 和 vanilla JavaScript 构建——无需 jQuery，也无需构建步骤即可使用。提供 35 个开箱即用的 HTML 页面，并配备 Pug + SCSS + Vite 源码流水线，供希望一次性编辑共享局部模板而非重复编辑 35 次的贡献者使用。

所有依赖项均处于当前发布版本，且无未解决的安全公告。请参阅下文 v3.4.0 的新特性，或查阅 CHANGELOG.md 获取完整历史记录。

v3.4.0 的新特性（2026 年 8 月）

依赖项更新——全部为最新版本，零安全警报

所有 npm 及本地依赖项现已更新至当前发布版本，且 npm audit 报告 0 个漏洞。

所有 8 个未解决的安全公告已修复 — shell-quote（严重），immutable ×2，postcss，vite（高危），launch-editor（中危），esbuild（低危）。每一个都存在于构建时的 devDependency 中，因此没有任何已发布的模板文件受到影响。当 Vite 8 用 Rolldown 替换 esbuild 时，launch-editor 和 esbuild 完全移出了依赖树。
构建工具链： Vite 7 → 8.2.0，concurrently 9 → 10.0.4，chokidar 4 → 5.0.0，sass → 1.102.0。三个主要版本升级，无需更改配置。Sass 输出与之前的构建完全一致（字节级相同）。
FullCalendar 6.1.20 → 7.0.2 — 这是一次真正的迁移，而非简单的版本升级。v7 生成带哈希的内部类名，因此旧的 .fc-* 覆盖已被替换为主题公开的 --fc-classic-* 自定义属性，并映射到 CoolAdmin 的设计令牌。日历现在会自动跟随强调色预设切换器，并且包含暗色模式令牌。无需 temporal-polyfill — 全局捆绑包自带 Temporal shim。
Font Awesome 7.2.0 → 7.3.1，css-hamburgers → 1.2.1。Bootstrap 5.3.8、Chart.js 4.5.1 和 Leaflet 1.9.4 已是最新版本。

修复

card.html 上的空白图标 — fa-presentation-screen 是一个 Font Awesome Pro 图标，从未包含在 Free 包中，因此一直渲染为空白字形。现在是 fa-display。
三个打包压缩文件中的悬空 sourcemap 引用 指向从未发布的 .map 文件，导致浏览器开发者工具中出现 404 错误。
日历事件点击处理器中遗留的 console.log，已替换为 toast，使交互实际可见。

全部 35 个页面均在无头 Chromium 中验证，控制台错误为 0，失败请求为 0；日历还额外在月、周、日和列表视图中进行了测试。

之前的版本

每个版本的完整详情见 CHANGELOG.md。

v3.3.0（2026 年 5 月）— 将带有年份风味的 theme-2026 覆盖层重命名为 app（css/app.css、body.app），以便该约定不会过时。无视觉变化。
v3.2.0（2026 年 5 月）— 引入了 Pug + SCSS + Vite 源流水线。侧边栏导航位于一个文件中（src/pug/partials/_nav-data.pug）并传播到每个页面；SCSS 拆分为 56 个部分。所有 35 个页面现在都从 Pug 源生成，而构建后的 HTML 和 CSS 仍然位于仓库根目录，因此最终用户无需工具链。解决了 issue #35。
v3.1.0（2026 年 5 月）— 现代应用外壳：设计覆盖层、Cmd+K 命令面板、6 预设主题切换器、toast 系统、加载骨架、交互式收件箱，以及 11 个新页面（看板、个人资料、定价、发票、数据表、向导、文档、通知、404/500/维护）。
v3.0.0（2026 年 5 月）— 审计通过。通过移除未使用的库，每页减少约 260 KB 的 JS，整合为单一图标字体，添加了可访问性地标和每页 SEO 元数据，引入了设计令牌，并清理了 718 个过时的供应商前缀。

在线演示

preview.colorlib.com/theme/cooladmin/ — 完整模板托管在 Cloudflare R2 上。

直接链接到每个仪表板变体：

预览

仪表盘变体

每个缩略图都链接到其在 Cloudflare R2 上的实时演示。

仪表盘 1 — 概览	仪表盘 2 — 销售管道	仪表盘 3 — 营销分析	仪表盘 4 — 项目

UI 组件与页面

交互式图表 - 折线图、柱状图、环形图和实时图表
数据表格 - 带有水平滚动指示器的响应式表格
现代表单 - Bootstrap 5 原生表单组件
高级日历 - FullCalendar v6+ 集成
UI 元素 - 卡片、模态框、按钮、警报、进度条
移动优化 - 在所有设备上提供完美体验

主要功能

现代架构

Bootstrap 5.3.8 配合最新的实用工具和组件
原生 JavaScript - 无 jQuery 依赖，性能更佳
ES6+ 代码 - 现代 JavaScript 模式和最佳实践
模块化设计 - 易于定制和扩展
SEO 优化 - 干净的标记和语义化 HTML5

高级数据可视化

Chart.js 4.5.1 - 性能增强的最新版本
6 种预置图表类型 - 折线图、柱状图、环形图、面积图等
响应式图表 - 在所有屏幕尺寸上完美显示
实时更新 - 动态数据可视化能力
现代动画 - 平滑的过渡和交互

移动优先设计

响应式网格系统 - Bootstrap 5 改进的网格
触控友好导航 - 优化的侧边栏和菜单
移动表格 - 带有视觉指示器的水平滚动
手势支持 - 移动设备的滑动导航
性能优化 - 在移动网络上快速加载

美观的 UI 组件

35 个 HTML 页面 - 仪表盘、应用、组件、认证和错误页面
50+ UI 元素 - 卡片、按钮、表单、表格、模态框
现代设计系统 - 一致的颜色、排版和间距
细自定义滚动条 - 提升用户体验的微妙 8px 滚动条
简洁排版 - 可读性强的字体和适当的层级

升级到高级仪表盘

需要高级功能、专属支持和生产就绪的代码？探索我们在 DashboardPack 上精心挑选的专业管理模板合集。

Apex Dashboard _{Next.js 16 + React 19 + Tailwind CSS v4 + shadcn/ui。5 种仪表盘变体，20+ 应用页面，125+ 路由，完整 CRUD。}	Zenith Dashboard _{Next.js 16 + React 19 + Tailwind CSS v4 + shadcn/ui。无彩色设计，50+ 页面，6 个仪表盘，实时主题自定义器。}
Haze _{Nuxt 4 + Nuxt UI v4 + Tailwind CSS v4。92+ 页面，7 种布局，5 个仪表盘，RTL，i18n，模拟 API 层。}	TailPanel _{React + TypeScript + Tailwind CSS + Vite。9 种仪表盘设计，深色和浅色主题。}
Admindek _{Bootstrap 5 + 原生 JS。100+ 组件，深色/浅色模式，RTL 支持，10 种颜色预设。}	SvelteForge Premium _{SvelteKit + Tailwind CSS v4。30+ 已连接模块，从第一行开始支持多租户，深色/浅色/系统模式。}

查看全部高级模板 →

技术规格

核心技术

{
  "version": "3.4.0",
  "bootstrap": "5.3.8",
  "chart.js": "4.5.1",
  "fontawesome": "7.3.1",
  "fullcalendar": "7.0.2",
  "leaflet": "1.9.4",
  "javascript": "ES6+ Vanilla",
  "css": "CSS3 + Custom Properties (authored in SCSS)",
  "html": "HTML5 Semantic Markup (authored in Pug)",
  "build": "Vite 8 + Sass + Pug (optional — built artifacts ship in repo)"
}

浏览器支持

浏览器	版本	状态
Chrome	88+	完全支持
Firefox	78+	完全支持
Safari	14+	完全支持
Edge	88+	完全支持
Mobile Safari	iOS 14+	完全支持
Chrome Mobile	Android 8+	完全支持

性能指标

包大小: 2.4MB（较 v1.0 减少 25%）
加载时间: 比基于 jQuery 的版本快约 30%
移动端性能: 针对 3G/4G 网络优化
依赖项: 仅 8 个核心依赖项（从 15+ 减少）

文件结构

CoolAdmin/
├── css/                          # Built CSS (regenerated by sass from src/scss/)
│   ├── theme.css                 # Legacy stylesheet (~14k lines, ~207 KB)
│   ├── app.css                # App theme overlay (~7k lines, scoped to body.app)
│   └── font-face.css             # Poppins font-face declarations
├── js/
│   ├── vanilla-utils.js          # jQuery replacement utilities ($, $$, on, addClass, ready…)
│   ├── bootstrap5-init.js        # Initializes tooltips + popovers only
│   ├── main-vanilla.js           # Chart.js configs + sidebar/dropdown UI behaviors
│   └── modern-plugins.js         # Counters, modern progress bars, lightbox
├── vendor/
│   ├── bootstrap-5.3.8.min.css   # Bootstrap 5.3.8
│   ├── bootstrap-5.3.8.bundle.min.js
│   ├── fontawesome-7.3.1/        # Font Awesome 7.3.1 (single icon font)
│   ├── chartjs/                  # Chart.js 4.5.1 UMD bundle
│   ├── fullcalendar-7.0.2/      # FullCalendar 7.0.2
│   └── css-hamburgers/           # Animated hamburger menu icons
├── src/                          # Pug + SCSS sources (contributors only)
│   ├── pug/                      # Layouts, partials, pages — see "Source layout" above
│   └── scss/                     # 56 SCSS partials + two entry files
├── scripts/
│   └── build-pug.js              # Renders src/pug/pages/*.pug → root *.html
├── images/                       # Avatars, logos, UI graphics
├── fonts/poppins/                # Self-hosted Poppins
├── screenshots/                  # README assets
├── *.html (24 pages)             # Built HTML at repo root — clone-and-open ready
│   ├── index.html, index2.html, index3.html, index4.html   # 4 dashboard variants
│   ├── chart.html, table.html, data-table.html             # Data + analytics
│   ├── calendar.html, map.html, kanban.html, inbox.html    # Apps
│   ├── form.html, wizard.html                              # Forms
│   ├── card.html, button.html, modal.html, tab.html,       # UI components
│   │   alert.html, progress-bar.html, badge.html,
│   │   switch.html, grid.html, typo.html, fontawesome.html
│   ├── profile.html, pricing.html, invoice.html,           # Account / commerce
│   │   docs.html, notifications.html
│   ├── login.html, register.html, forget-pass.html         # Auth
│   └── 404.html, 500.html, maintenance.html                # Error / status
├── package.json                  # npm scripts: dev, build, build:pug, build:sass
├── vite.config.js                # Vite dev server config (MPA mode, port 3000)
├── CHANGELOG.md                  # Per-release history
└── README.md                     # This file

快速开始

CoolAdmin 提供两种运行方式，具体取决于你是想编辑共享的部分（partials）还是仅预览已构建的模板。

作为最终用户 — 无需 Node

已构建的 HTML 和 CSS 位于仓库根目录。克隆后，以静态方式提供服务，并在浏览器中打开：

git clone https://github.com/puikinsh/CoolAdmin.git
cd CoolAdmin
python3 -m http.server 8000      # or:  npx serve .

然后打开 http://localhost:8000/index.html。每一页（共 35 页）均可在无工具链的情况下运行。

作为贡献者 — Pug + SCSS + Vite

若要编辑共享布局、侧边栏导航或 SCSS 部分，请运行源流水线：

npm install                      # one-time
npm run dev                      # starts pug-watch + sass-watch + Vite dev server at :3000

npm run dev 并发运行三个监视器：

Pug — 当 src/pug/ 中有任何更改时，node scripts/build-pug.js --watch 会重新编译根 *.html。
Sass — sass --watch src/scss/*.scss:css/*.css 从 src/scss/ 源文件重新编译 css/theme.css 和 css/app.css。
Vite — 位于 http://localhost:3000 的带有 HMR 的开发服务器，自动打开 index.html。

编辑 src/pug/partials/_nav-data.pug 以更改侧边栏 — 更改会自动出现在每个页面上。

对于不带监视器的生产环境重建：

npm run build                    # one-shot pug + sass build

源布局

src/
├── pug/
│   ├── layouts/
│   │   ├── _default.pug         # sidebar + topbar + main content
│   │   └── _auth.pug            # centered single-column (login, register)
│   ├── partials/
│   │   ├── _head.pug            # +head(meta) mixin — emits <head> from { title, description, noindex }
│   │   ├── _nav-data.pug        # SINGLE SOURCE OF TRUTH for menu items
│   │   ├── sidebar.pug          # desktop sidebar — uses _nav-data
│   │   ├── header-mobile.pug    # mobile header + nav — uses _nav-data
│   │   ├── header-desktop.pug   # topbar (search, dropdowns, account menu)
│   │   ├── footer-scripts.pug   # common <script> stack
│   │   └── content/             # per-page inner HTML, included by page Pug files
│   └── pages/
│       ├── index.pug            # extends _default, sets activePage, blocks
│       ├── login.pug            # extends _auth
│       └── table.pug            # extends _default
├── scss/
│   ├── theme.scss               # entry — @use's 20 legacy partials
│   ├── app.scss              # entry — @use's 36 overlay partials
│   ├── _variables.scss          # design tokens (legacy)
│   ├── _generic.scss            # normalize, scrollbars, typography
│   ├── _elements.scss           # title, links
│   ├── _objects.scss            # section, page-wrapper
│   ├── _utilities.scss          # padding/margin spacing utilities
│   ├── _modern-additions.scss   # lightbox, modern progress, skip-link
│   ├── components/              # _buttons, _form, _header, _sidebar, _cards…
│   └── 2026/                    # 36 partials for the modern overlay
└── scripts/
    └── build-pug.js             # Node script: src/pug/pages/*.pug → root *.html

添加新页面（Pug 工作流）

在 src/pug/partials/_nav-data.pug 中添加导航条目。
将页面内容（即 .container-fluid 内部的所有内容）放入 src/pug/partials/content/your-page.html。

创建 src/pug/pages/your-page.pug：

extends ../layouts/_default

block variables
  - var pageMeta = { title: 'Your page', description: 'Short description' }
  - var activePage = 'your-page.html'

block content
  include ../partials/content/your-page.html

运行 npm run build:pug（或保持 npm run dev 运行）。

仪表板页面

主仪表板

index.html - 带有 Chart.js v4 组件的主仪表板
index2.html - 带有任务管理的替代布局
index3.html - 带有不同指标的第三种变体
index4.html - 带有增强图表的第四种布局

数据与分析

table.html - 带有滚动指示器的响应式数据表格
chart.html - 全面的 Chart.js v4 展示
calendar.html - 带有现代事件处理的 FullCalendar v6+

UI 组件

form.html - Bootstrap 5 表单组件和验证
card.html - 现代卡片设计和布局
button.html - 按钮变体和状态
modal.html - 模态对话框和覆盖层
tab.html - 选项卡导航和内容切换
alert.html - 警报消息和通知

实用工具与示例

grid.html - Bootstrap 5 网格系统演示
typo.html - 排版层次和样式
fontawesome.html - FontAwesome 7.0.1 图标展示
progress-bar.html - 进度指示器和动画

自定义指南

颜色与主题

该模板使用 CSS 自定义属性以便于主题定制：

:root {
  /* Primary Colors */
  --primary-color: #4272d7;
  --secondary-color: #6c757d;
  --success-color: #28a745;
  --warning-color: #ffc107;
  --danger-color: #dc3545;
  --info-color: #17a2b8;
  
  /* Background Colors */
  --body-bg: #f8f9fa;
  --card-bg: #ffffff;
  --sidebar-bg: #2c3e50;
  
  /* Text Colors */
  --text-primary: #212529;
  --text-secondary: #6c757d;
  --text-muted: #868e96;
}

图表自定义

图表使用 Chart.js v4 配置格式：

const chartConfig = {
  type: 'line', // line, bar, doughnut, etc.
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    datasets: [{
      label: 'Revenue',
      data: [12, 19, 3, 5, 2, 3],
      borderColor: '#4272d7',
      backgroundColor: 'rgba(66, 114, 215, 0.1)'
    }]
  },
  options: {
    responsive: true,
    maintainAspectRatio: false,
    plugins: {
      legend: { display: true },
      tooltip: { enabled: true }
    },
    scales: {
      x: { display: true },
      y: { display: true }
    }
  }
};

添加新组件

原生 JavaScript 工具使添加新组件变得轻而易举：

// Using the custom vanilla-utils.js
const element = $('.my-selector');           // querySelector
const elements = $$('.my-selector');         // querySelectorAll
on(element, 'click', handler);               // addEventListener
addClass(element, 'active');                // classList.add
removeClass(element, 'active');             // classList.remove
toggleClass(element, 'active');             // classList.toggle

移动端优化

响应式特性

移动优先网格 - Bootstrap 5 改进的响应式网格系统
触摸导航 - 支持滑动手势的侧边栏和菜单交互
响应式表格 - 带有视觉滚动指示器的水平滚动
优化图表 - 支持触摸操作的 Chart.js 配置
移动表单 - 针对移动输入优化的原生表单控件

性能优化

懒加载 - 图表和重型组件在需要时加载
优化图像 - 压缩资源以加快移动端加载速度
极简 JavaScript - 原生 JS 消除了 jQuery 的开销
高效 CSS - 利用现代 CSS 特性减小打包体积

现代 JavaScript 特性

原生 JavaScript 工具

用现代 JavaScript 模式替换 jQuery：

// Old jQuery way
$('.element').addClass('active').on('click', handler);

// New vanilla way
const element = $('.element');
addClass(element, 'active');
on(element, 'click', handler);

// Modern ES6+ patterns
document.querySelectorAll('.elements').forEach(el => {
  el.addEventListener('click', (e) => {
    e.target.classList.toggle('active');
  });
});

Chart.js v4 集成

具备改进性能的现代图表配置：

// Automatic chart initialization
document.addEventListener('DOMContentLoaded', () => {
  const charts = document.querySelectorAll('[data-chart]');
  charts.forEach(canvas => {
    const type = canvas.dataset.chart;
    const config = getChartConfig(type);
    new Chart(canvas, config);
  });
});

使用场景

完美适用于

📊 商业仪表盘 - 分析、KPI 和报告
🏢 管理面板 - 内容管理和系统管理
📈 分析平台 - 数据可视化和洞察
🛍️ 电商后台 - 订单管理和库存
💼 SaaS 应用 - 多租户仪表盘界面
🏥 医疗系统 - 患者管理和病历
🎓 教育平台 - 学习管理系统
💰 金融应用 - 交易平台和组合管理

行业

科技与软件 - 科技初创公司和软件公司
电商与零售 - 在线商店和市场平台
医疗 - 医疗机构和医疗技术
金融 - Fintech 应用和投资平台
教育 - EdTech 平台和教育机构
营销 - 数字代理和营销自动化工具

安全特性

现代安全标准

CSP 就绪 - 兼容内容安全策略
XSS 防护 - 输入清理和输出编码
HTTPS 友好 - 安全资源加载和外部链接
现代身份验证 - 支持 OAuth、JWT 和 2FA 集成

最佳实践

安全外部链接 - rel="nofollow" target="_blank" 关于外部链接
表单验证 - 客户端和服务器端验证模式
干净的 URL - 对 SEO 友好且安全的 URL 结构
错误处理 - 适当的错误消息，避免信息泄露

性能优势

升级前后对比 (v1.0 → v2.0)

指标	v1.0 (Bootstrap 4 + jQuery)	v2.0 (Bootstrap 5 + Vanilla)	改进
包大小	~3.2MB	~2.4MB	缩小 25%
依赖项	15+ 个库	8 个核心库	减少 47% 依赖
加载时间	~2.1s	~1.5s	快 30%
移动端性能	良好	优秀	提升 40%
JavaScript 执行	jQuery 开销	原生性能	快 50%

核心 Web 指标

LCP (Largest Contentful Paint) - < 2.5s
FID (First Input Delay) - < 100ms
CLS (Cumulative Layout Shift) - < 0.1

从 v1.0 迁移

破坏性变更

如果您正在从原始 CoolAdmin 模板升级：

Bootstrap 类 - 将 Bootstrap 4 类更新为 Bootstrap 5
jQuery 代码 - 使用提供的工具转换为原生 JavaScript
Chart.js 语法 - 更新为 Chart.js v4 配置格式
表单组件 - 更新为 Bootstrap 5 表单类
数据属性 - 将 data-toggle 更改为 data-bs-toggle

迁移助手

// jQuery → Vanilla JavaScript conversion examples
// OLD: $('.element').addClass('active');
// NEW: addClass($('.element'), 'active');

// OLD: $(document).ready(function() { ... });
// NEW: ready(() => { ... });

// OLD: $.ajax({ ... });
// NEW: fetch('/api/endpoint').then(response => response.json());

支持与社区

文档

📚 全面的 README - 此详细指南
📝 内联注释 - 全程文档完善的代码
🔄 迁移指南 - 轻松从旧版本升级
📋 变更日志 - 详细的版本历史和更新

专业支持

🌐 Colorlib.com - 原始模板创建者及支持
🛠️ DashboardPack.com - 高级仪表盘模板和主题
💬 社区论坛 - 从其他开发者处获取帮助
📧 邮件支持 - 针对定制问题的直接支持

贡献

我们欢迎贡献！请：

Fork 该仓库
创建一个功能分支
进行您的更改
提交一个 pull request
遵循我们的编码标准

许可证

本项目基于 MIT License 授权 - 详见 LICENSE.md 文件。

商业使用

允许 - 用于商业项目
修改 - 根据需要自定义和扩展
分发 - 包含在您的应用程序中
私有使用 - 用于专有软件

下一步是什么？

2025-2026 路线图

🌙 深色模式 - 内置深色主题支持
🌐 RTL 支持 - 从右到左语言支持
🎨 主题构建器 - 可视化主题定制工具
📱 PWA 就绪 - 渐进式 Web 应用能力
🔧 构建工具 - Webpack/Vite 集成以进行优化
🧪 TypeScript - 可选的 TypeScript 定义
🎭 组件库 - 独立组件包

社区请求

📊 更多图表类型 - 热力图、桑基图、树状图
🗃️ 高级表格 - 排序、筛选、分页
🔔 通知系统 - Toast 通知和警报
📁 文件管理器 - 拖放文件处理
🎯 仪表盘构建器 - 拖放式仪表盘创建

奖项与认可

⭐ 最受欢迎 - Colorlib.com 上最受欢迎的 Bootstrap 管理模板
🚀 性能领先 - 同类中加载速度最快的管理模板
📱 移动卓越 - 2025 年度最佳移动体验奖
🔧 开发者之选 - 对开发者最友好的管理模板

联系我们

🌐 网站: colorlib.com
🛒 市场: DashboardPack.com
🐦 Twitter: @colorlib

由 Colorlib] 用 ❤️ 制作

v3.4.0 · 2026年8月 · Bootstrap 5.3.8 · Font Awesome 7.3.1 · Chart.js 4.5.1 · FullCalendar 7.0.2 · Vanilla JavaScript · Pug + SCSS + Vite 源码流水线

⬆ 返回顶部