从 v3 迁移
AdminLTE 4 是一次从头开始的重写。它基于 Bootstrap 5.3，移除了 jQuery，以 TypeScript 编写的原生 JavaScript 发布，并重新组织了 CSS 类结构。如果你正在升级 AdminLTE 3 项目，以下变更是最可能带来影响的。
概要一览
| AdminLTE 3 | AdminLTE 4 | |
|---|---|---|
| CSS 框架 | Bootstrap 4.6 | Bootstrap 5.3 |
| JavaScript | jQuery + vanilla | 仅原生 TypeScript |
| Dark mode | 手动设置 .dark-mode 类 |
data-bs-theme 属性（Bootstrap 原生）
|
| RTL | 独立的 rtl.css 构建 |
通过 rtlcss 自动生成 |
| 浏览器支持 | 提供 IE 11 兼容版本 | 仅支持现代浏览器 |
| 构建工具 | Gulp | Rollup + Sass + PostCSS |
| 图标库 | FontAwesome | Bootstrap Icons （Lucide / Tabler Icons 作为替代方案已文档化） |
如果你的项目依赖 jQuery 或 IE 11，请继续使用 AdminLTE 3——这些限制在 v4 中不可逆。
类名重命名
最常见的查找替换工作：
| AdminLTE 3 | AdminLTE 4 |
|---|---|
.wrapper |
.app-wrapper |
.main-header |
.app-header |
.main-sidebar |
.app-sidebar |
.content-wrapper |
.app-main |
.main-footer |
.app-footer |
.content-header |
.app-content-header |
.content |
.app-content |
.brand-link (inside .main-sidebar) |
.sidebar-brand > .brand-link |
data-widget="pushmenu" |
data-lte-toggle="sidebar" |
data-widget="treeview" |
data-lte-toggle="treeview" （在父级菜单上）
|
data-widget="card-widget" |
data-lte-toggle="card-collapse",
card-remove, card-maximize
|
data-widget="fullscreen" |
data-lte-toggle="fullscreen" |
data-widget="control-sidebar" |
（已移除——由 Bootstrap offcanvas 替代） |
.dark-mode (在 <body> 上) |
data-bs-theme="dark" (（可在任意元素上）) |
Bootstrap 4 → 5 工具类重命名
这些来自 Bootstrap 本身，而非 AdminLTE，但它们会影响每个页面：
| Bootstrap 4 | Bootstrap 5 |
|---|---|
data-toggle |
data-bs-toggle |
data-target |
data-bs-target |
data-dismiss |
data-bs-dismiss |
data-parent |
data-bs-parent |
data-spy |
data-bs-spy |
data-ride |
data-bs-ride |
.ml-*, .mr-* |
.ms-*, .me-* |
.pl-*, .pr-* |
.ps-*, .pe-* |
.float-left, .float-right |
.float-start, .float-end |
.text-left, .text-right |
.text-start, .text-end |
.border-left, .border-right |
.border-start, .border-end |
.rounded-left, .rounded-right |
.rounded-start, .rounded-end |
.font-weight-* |
.fw-* |
.font-italic |
.fst-italic |
.text-monospace |
.font-monospace |
使用正则表达式查找替换可以在几分钟内处理大部分内容。迁移工具
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 使用在 <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 文档页面。
使用 CSS 变量替代 .bg-* 重写类
AdminLTE 3 包含大量一次性的颜色类（如
.bg-navy、.bg-purple、.bg-fuchsia
等）。在 v4 中，推荐使用 Bootstrap 5.3 的 CSS 变量模型：
<!-- AdminLTE 3 -->
<div class="card bg-navy">…</div>
<!-- AdminLTE 4 — 使用 Bootstrap 工具 + CSS 变量，data 属性会为你自动处理 -->
<div class="card text-bg-primary">…</div>
如需完整重新主题，请在 :root 上覆盖
--bs-primary 等变量。参见
Customization。
图标
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 项目：
-
先创建分支。 这不是一个小改动——在 v4 稳定之前，保持
master分支在 v3 上。 - 更新 CSS 类名，使用上面的表格进行查找替换。大多数布局可以编译，但在第 3 步之前看起来是错乱的。
-
更新
data-toggle→data-bs-toggle等，覆盖所有模板。 -
将
.dark-mode切换代码替换为data-bs-theme属性写入。 - 审查 jQuery 调用。 要么移除它们（使用 data 属性），要么直接导入插件类。
-
测试响应式 breakpoint——Bootstrap 5 新增了
xxl。如果你使用了 breakpoint 特定的工具类，请仔细检查新的尺寸体系。 - 重新测试打印视图——AdminLTE 4 修复了打印布局问题（#5996）；如果你有自定义打印 CSS，请验证其仍然有效。