从 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 作为替代方案已文档化） |
| 表单组件 | 在 plugins/ 里打包了约 25 个 jQuery 插件 |
一个都不打包 —— 改为文档化推荐的原生 JS 替代方案 |
如果你的项目依赖 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 (位于 .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 打包了一个塞满 jQuery 组件的 plugins/ 文件夹。AdminLTE
4 一个都不带了——它只专注于框架本身，改为在文档里推荐同类最佳的原生 JS
替代方案。下面每一个替代品都是 MIT 许可、仍在积极维护，而且不需要 jQuery：
| AdminLTE 3 插件（jQuery） | AdminLTE 4 替代方案 | 备注 |
|---|---|---|
| Select2 | Tom Select | 搜索、多选、打标签、远程数据、虚拟滚动。如果非要留着 Select2，见 API 对照 和 Select2 兼容主题。 |
| Bootstrap4 Duallistbox | Tom Select |
一个 multiple 的 Tom Select 就能干同样的活，界面还更简洁。
|
| DataTables | Tabulator |
排序、筛选、分页、行内编辑、导出。用在了
tables/data.html 里。
|
| bootstrap-datepicker | Flatpickr | 一个库就顶替了 v3 里全部四个日期/时间插件。 |
| daterangepicker |
Flatpickr
(mode: "range")
|
|
| Bootstrap Timepicker |
Flatpickr
(noCalendar: true)
|
|
| tempusdominus | Flatpickr | |
| Summernote | Quill |
Snow 和 bubble 两种主题在 forms/editors.html 里有演示。
|
| bootstrap4-wysihtml5 | Quill | |
| SimpleMDE | EasyMDE | EasyMDE 就是 SimpleMDE 仍在维护的那个 fork——API 一模一样。 |
| bootstrap-slider | noUiSlider | |
| iCheck / icheck-bootstrap |
原生 .form-check
|
Bootstrap 5.3 自带的复选框和开关压根不需要插件。 |
| bootstrap-colorpicker | Pickr |
或者用原生的
<input type="color" class="form-control
form-control-color">。
|
| jQuery InputMask | IMask | |
| jQuery Knob | ApexCharts 径向条形图 | |
| jQuery Mapael | jsVectorMap | |
| jQuery UI sortable | SortableJS | 看板演示就是靠它实现的。 |
| fullCalendar（jQuery 版本） | FullCalendar 6 |
同一个项目——v5 之后就不依赖 jQuery 了。用在了
pages/calendar.html 里。
|
| Chart.js 2 | Chart.js 4 / ApexCharts | Chart.js 本来就不依赖 jQuery；只是跨了个大版本。 |
| dropzone | Dropzone 6 或 FilePond | v6 是用纯 JS 重写的。 |
| Ekko Lightbox | GLightbox | |
| jQuery Overlay Scrollbars |
原生 scrollbar-* CSS
|
AdminLTE 4 用 CSS 给侧边栏的滚动条做了样式。 |
| toastr / SweetAlert2 | Bootstrap toasts / SweetAlert2 | SweetAlert2 从 v7 起就不依赖 jQuery 了。 |
| jsGrid | Tabulator |
每个替代方案的安装代码片段和接线代码都在 推荐集成 页面里。
深色模式
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，请验证其仍然有效。