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	(helper function: `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. 程序化（命令式）

当您需要从自己的代码中控制插件时——例如在登录成功后打开侧边栏，或在路由变更时展开卡片——直接实例化类即可：

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

// 侧边栏
new PushMenu(document.body, {}).expand()

// 卡片最大化
const card = document.querySelector("#chart-card")
new CardWidget(card, {}).maximize()

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

<script>
  // 该捆绑包分配给 window.adminlte
  new adminlte.PushMenu(document.body, {}).expand()
</script>

监听插件事件

每个插件都会在其操作的元素上触发 CustomEvent 或 Event。监听这些事件以与您自己的代码协调：

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

document.addEventListener("open.lte.push-menu", () => {
  // 用户打开了侧边栏——例如分析调用
})

事件名称参考

插件	事件	触发时机
PushMenu	`open.lte.push-menu`	侧边栏展开
PushMenu	`collapse.lte.push-menu`	侧边栏折叠
Treeview	`expanded.lte.treeview`	子菜单打开
Treeview	`collapsed.lte.treeview`	子菜单关闭
Treeview	`load.lte.treeview`	页面加载时检测到预先打开的子菜单
CardWidget	`expanded.lte.card-widget`	卡片展开
CardWidget	`collapsed.lte.card-widget`	卡片折叠
CardWidget	`remove.lte.card-widget`	卡片移除
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`	退出全屏

所有事件都会冒泡。将监听器绑定到 document 或 document.body 上用于全局钩子，或绑定到特定的卡片/侧边栏元素上用于作用域监听。

通过 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 辅助