JavaScript 插件概述

AdminLTE 将 7 个 JavaScript 插件打包为一个单独的包（adminlte.js）。每个插件都从包根目录导出，可以通过 data-lte-* 属性以声明方式触发使用，并暴露出方法供代码驱动控制。

概览

插件	Data 属性	方法	文档
PushMenu	`data-lte-toggle="sidebar"`	`.toggle()` / `.expand()` / `.collapse()`	参考
Treeview	`data-lte-toggle="treeview"` 的父菜单上	`.toggle()` / `.open()` / `.close()`	参考
CardWidget	`data-lte-toggle="card-collapse"`, `card-remove`, `card-maximize`	`.toggle()` / `.collapse()` / `.expand()` / `.remove()` / `.maximize()` / `.minimize()` / `.toggleMaximize()`	参考
DirectChat	`data-lte-toggle="chat-pane"`	`.toggle()`	参考
FullScreen	`data-lte-toggle="fullscreen"`	`.toggleFullScreen()` / `.inFullScreen()` / `.outFullscreen()`	参考
Layout	(自动应用于 `<body>`)	`.holdTransition(time)`	参考
AccessibilityManager	(辅助函数： `initAccessibility()`)	`.announce()` / `.focusElement()` / `.trapFocus()` / `.addLandmarks()`	参考

两种使用方式

1. Data 属性（声明式）

对于大多数页面，Data 属性就足够了——无需编写 JavaScript 代码。在触发元素上添加相应的 data-lte-* 属性，包会在页面加载时自动进行绑定：

<!-- 侧边栏切换 -->
<button data-lte-toggle="sidebar">☰</button>

<!-- 卡片折叠 / 移除 / 最大化 -->
<div class="card">
  <div class="card-header">
    <h3 class="card-title">Title</h3>
    <div class="card-tools">
      <button class="btn btn-tool" data-lte-toggle="card-collapse" aria-label="Collapse card">
        <i data-lte-icon="expand" class="bi bi-dash-lg"></i>
        <i data-lte-icon="collapse" class="bi bi-plus-lg"></i>
      </button>
    </div>
  </div>
  <div class="card-body">…</div>
</div>

该包在 DOMContentLoaded 事件上绑定所有 data-API 监听器。动态注入的元素仍然适用于 PushMenu、CardWidget 和 Treeview 插件，因为它们使用事件委托。

2. 程序化（命令式）

如果要在你自己的代码里控制插件（比如登录成功后把侧边栏展开，或者路由变了之后展开某个卡片），有两种方式：一是直接获取数据 API 已经创建好的实例，二是按需自己创建一个——这个从 4.1 版就支持了。

// ESM (打包导入)
import { PushMenu, CardWidget } from "admin-lte"

// 侧边栏： 数据 API 会在页面加载时自动创建好实例——直接获取即可。
const sidebar = document.querySelector(".app-sidebar")
PushMenu.getInstance(sidebar)?.expand()

// 卡片最大化： 复用已有实例，或新建一个。
const card = document.querySelector("#chart-card")
CardWidget.getOrCreateInstance(card).maximize()

或使用全局变量（UMD 包，无需构建步骤）：

<script>
  // 该捆绑包分配给 window.adminlte
  adminlte.PushMenu.getInstance(document.querySelector(".app-sidebar"))?.expand()
</script>

组件生命周期

每个组件都遵循与 Bootstrap 相同的约定：

Component.getInstance(element) —— 返回该元素对应的实例，若不存在则返回 null。
Component.getOrCreateInstance(element, config?) —— 复用已有实例或新建一个（config 仅在新建时生效）。
instance.dispose() —— 销毁实例；调用后 getInstance() 将返回 null。

每个元素在注册表中只保留一个实例，该注册表基于 WeakMap 实现，因此实例会与其对应的元素一起被垃圾回收（在 Hotwired Turbo 导航时无需额外清理）。数据 API 使用委托的 document 级事件处理器进行监听，这意味着在页面加载后插入的内容（如 AJAX 局部更新、Turbo Frames）中的切换控件也无需重新初始化即可正常工作。

监听插件事件

每个插件都会在其根元素（卡片、导航项、侧边栏）上触发冒泡的 CustomEvent（自定义事件）——你可以在 document 上监听以进行全局拦截，也可以在元素本身上监听以进行局部处理。带有 “before” 前缀的事件是可取消的：调用 preventDefault() 即可阻止它们执行。

document.addEventListener("expanded.lte.card-widget", (e) => {
  console.log("卡片已展开：", e.target)
})

// 在用户确认之前阻止卡片移除。
document.addEventListener("remove.lte.card-widget", (e) => {
  if (!confirm("移除卡片？")) {
    e.preventDefault()
  }
})

事件名称参考

插件	前置事件（可取消）	后置事件	触发对象
PushMenu	`open.lte.push-menu`	`opened.lte.push-menu`	侧边栏展开
PushMenu	`collapse.lte.push-menu`	`collapsed.lte.push-menu`	侧边栏折叠
Treeview	`expand.lte.treeview`	`expanded.lte.treeview`	子菜单打开（动画结束后触发）
Treeview	`collapse.lte.treeview`	`collapsed.lte.treeview`	子菜单关闭（动画结束后触发）
Treeview	—	`load.lte.treeview`	页面加载时检测到预先打开的子菜单
CardWidget	`expand.lte.card-widget`	`expanded.lte.card-widget`	卡片展开（动画结束后触发）
CardWidget	`collapse.lte.card-widget`	`collapsed.lte.card-widget`	卡片折叠（动画结束后触发）
CardWidget	`remove.lte.card-widget`	`removed.lte.card-widget`	卡片移除 (卡片在 `removed` 事件后移出 DOM )
CardWidget	—	`maximized.lte.card-widget`	卡片最大化
CardWidget	—	`minimized.lte.card-widget`	卡片最小化
DirectChat	—	`expanded.lte.direct-chat`	联系人面板打开
DirectChat	—	`collapsed.lte.direct-chat`	联系人面板关闭
FullScreen	—	`maximized.lte.fullscreen`	进入全屏
FullScreen	—	`minimized.lte.fullscreen`	退出全屏
ColorMode	—	`changed.lte.color-mode`	主题已更改（`detail: { theme, resolved }`），在 `document` 上触发

所有事件都会在动画完成后触发（自4.1版本起）。动画动作的“后续”事件会在动画完成时执行，而不是在开始时。

通过 data 属性进行配置

部分插件会从其目标元素的 data-* 属性中读取配置：

<!-- Treeview — 非折叠式（可同时打开多个子菜单） -->
<ul class="nav sidebar-menu" data-lte-toggle="treeview" data-accordion="false">…</ul>

<!-- Treeview — 自定义动画速度 -->
<ul class="nav sidebar-menu" data-lte-toggle="treeview" data-animation-speed="500">…</ul>

<!-- 侧边栏 — 启用本地存储持久化（默认：关闭）
<aside class="app-sidebar" data-enable-persistence="true">…</aside>

<!-- 侧边栏 — 重写移动设备 breakpoint -->
<aside class="app-sidebar" data-sidebar-breakpoint="768">…</aside>

每个插件的参考页面都记录了其支持的属性。

插件管理的 CSS 类

插件会切换一小部分 CSS 类，您也可以对这些类进行样式设置或响应：

类名	设置者	位置	含义
`sidebar-collapse`	PushMenu	`<body>`	侧边栏已折叠（桌面迷你状态，或移动端关闭）
`sidebar-open`	PushMenu	`<body>`	用户明确打开了移动端侧边栏
`sidebar-mini`	PushMenu	`<body>`	迷你侧边栏模式已激活
`menu-open`	Treeview	`.nav-item`	子菜单当前已展开
`collapsed-card`	CardWidget	`.card`	卡片主体/页脚已折叠
`maximized-card`	CardWidget	`<html>` 和 `.card`	卡片处于全屏模式
`direct-chat-contacts-open`	DirectChat	`.direct-chat`	联系人面板可见
`hold-transition`	Layout	`<body>`	暂时禁用过渡动画（如调整大小时等）
`app-loaded`	Layout	`<body>`	初始页面加载动画已完成
`reduce-motion`	AccessibilityManager	`<body>`	检测到操作系统 `prefers-reduced-motion`

生产环境 vs 源码

插件以 TypeScript 模块的形式位于 src/ts/ 中。发布的 dist/js/adminlte.js 是所有 7 个插件的 Rollup 打包文件，在单个 adminlte 命名空间下导出（UMD）或以命名导入方式导出（ESM）。

如果您只需要其中一两个插件并且关注打包体积，从 node_modules/admin-lte/src/ts/ 导入单个模块可以进行 tree-shake——但您的工具链中需要 TypeScript 支持。

接下来去哪里

每个插件的详细参考（上表中的链接）
布局结构 —— 插件所操作的结构类
无障碍访问 —— 键盘导航、焦点陷阱、ARIA 辅助