从 v3 迁移

AdminLTE 4 是一次从头开始的重写。它基于 Bootstrap 5.3，移除了 jQuery，以 TypeScript 编写的原生 JavaScript 发布，并重新组织了 CSS 类结构。如果你正在升级 AdminLTE 3 项目，以下变更是最可能带来影响的。

概要一览

如果你的项目依赖 jQuery 或 IE 11，请继续使用 AdminLTE 3——这些限制在 v4 中不可逆。

类名重命名

最常见的查找替换工作：

Bootstrap 4 → 5 工具类重命名

这些来自 Bootstrap 本身，而非 AdminLTE，但它们会影响每个页面：

使用正则表达式查找替换可以在几分钟内处理大部分内容。迁移工具 bootstrap-5-migration 可以自动完成批量替换。

jQuery 移除

如果你的应用代码通过 jQuery 调用 AdminLTE 3 插件（例如 $('.sidebar').PushMenu() 等），这些调用将不再有效。替代方案：

// AdminLTE 3
$('.sidebar-toggle').on('click', function () {
  $('body').toggleClass('sidebar-collapse')
})

// AdminLTE 4 — data 属性会为你完成这项工作
// <a href="#" data-lte-toggle="sidebar">...</a>

如果需要编程式控制，直接导入插件类：

import { PushMenu } from "admin-lte"

new PushMenu(document.querySelector(".sidebar-toggle")).toggle()

所有 7 个 JS 插件（Layout、CardWidget、Treeview、DirectChat、FullScreen、PushMenu，以及 initAccessibility）均从 admin-lte 导出。

第三方插件替代方案

AdminLTE 3 打包了一个塞满 jQuery 组件的 plugins/ 文件夹。AdminLTE 4 一个都不带了——它只专注于框架本身，改为在文档里推荐同类最佳的原生 JS 替代方案。下面每一个替代品都是 MIT 许可、仍在积极维护，而且不需要 jQuery：

每个替代方案的安装代码片段和接线代码都在 推荐集成 页面里。

深色模式

AdminLTE 3 使用在 <body> 上切换的 .dark-mode 类。AdminLTE 4 使用 Bootstrap 5.3 原生的 data-bs-theme="dark" 属性，该属性可以应用于任何层级——<html>、<body> 或单个组件。

<!-- AdminLTE 3 -->
<body class="dark-mode">

<!-- AdminLTE 4 -->
<html data-bs-theme="dark">

内置的 Color Mode 组件读取/写入此属性，并将用户的选择保存在 localStorage 中。有关切换实现，请参阅 Color Mode 文档页面。

额外颜色移到了一个按需启用的样式表里

AdminLTE 3 在主 CSS 里塞了一大堆一次性的颜色类（.bg-navy、.bg-purple、.bg-fuchsia、.bg-gradient-*，还有侧边栏/导航栏皮肤）。到了 v4，核心样式表只认 Bootstrap 的主题色；扩展调色板成了一个独立的、按需启用的文件 dist/css/adminlte-colors.css，里面是一套重新设计过的十四种颜色（每一种配白色文字对比度都 ≥ 4.5:1），并且每种颜色都配齐了同样的类系列 —— .bg-*、.text-bg-*、.bg-gradient-*、.card-*、.callout-*……。

<!-- AdminLTE 3 -->
<div class="card bg-navy">…</div>
<aside class="main-sidebar sidebar-dark-primary">…</aside>

<!-- AdminLTE 4 — load css/adminlte-colors.css after adminlte.css -->
<div class="card text-bg-navy">…</div>
<aside class="app-sidebar text-bg-navy shadow" data-bs-theme="dark">…</aside>

lightblue 变成了 sky，maroon 变成了 pink；如果你的标记依赖旧名字，可以用 $lte-palette-aliases 把它们恢复回来。其他所有内容 —— 调色板、皮肤、添加你自己的品牌色 —— 都在颜色页面里。至于给 Bootstrap 自己的颜色换主题，可以在 :root 上覆盖 --bs-primary 等变量；详见自定义。

图标

AdminLTE 3 演示使用 FontAwesome 6 免费版。AdminLTE 4 标准化使用 Bootstrap Icons——它们是 SVG 格式、更轻量、MIT 许可，并与 Bootstrap 生态一同发布。

<!-- AdminLTE 3 -->
<i class="fas fa-home"></i>

<!-- AdminLTE 4 -->
<i class="bi bi-house"></i>

如果你更愿意继续使用 FontAwesome（或使用 Lucide、Tabler Icons、Material Symbols 等），AdminLTE 4 中没有任何内容强制使用 Bootstrap Icons——加载你喜欢的任何图标字体并替换 <i> 类即可。参见 Recommended Integrations 的对比表。

尚未移植的页面

v3 演示中包含的页面尚未全部为 v4 重新创建。v4 发布说明中涵盖了当前的页面目录。如果你依赖某个尚未移植的特定 v3 页面，请 提交 issue——非常欢迎社区为缺失的页面贡献代码。

建议的迁移顺序

对于现有的 AdminLTE 3 项目：

1. 先创建分支。 这不是一个小改动——在 v4 稳定之前，保持 master 分支在 v3 上。
2. 更新 CSS 类名，使用上面的表格进行查找替换。大多数布局可以编译，但在第 3 步之前看起来是错乱的。
3. 更新 data-toggle → data-bs-toggle 等，覆盖所有模板。
4. 将 .dark-mode 切换代码替换为 data-bs-theme 属性写入。
5. 审查 jQuery 调用。 要么移除它们（使用 data 属性），要么直接导入插件类。
6. 替换掉第三方插件，参照上面的替代方案对照表。一次换一个组件——这是最耗时的一步，而且每换一个都可以单独测试。
7. 测试响应式 breakpoint——Bootstrap 5 新增了 xxl。如果你使用了 breakpoint 特定的工具类，请仔细检查新的尺寸体系。
8. 重新测试打印视图——AdminLTE 4 修复了打印布局问题（#5996）；如果你有自定义打印 CSS，请验证其仍然有效。

帮助与讨论

• 迁移问题：GitHub 讨论
• 发现我们遗漏了什么？提交 issue 并标记 migration。