从 reveal.js 3.x 升级到 4.x 的 API 变更与迁移指南

将基于 HTML/CSS/JavaScript 构建的演示文稿框架 reveal.js 从 3.x 版本升级到 4.x 版本，核心任务是完成从“全局单例与动态脚本加载”向“ES 模块化标准与多实例 Promise 管道”的体系迁移。本文详细拆解 4.x 引入的目录调整、弃用 head.js、new Reveal() 实例化、基于 Promise 的生命周期以及全新的 plugins 插件机制，并提供从旧项目平滑过渡的对照表与四步迁移演练。

一、为什么 4.x 是 reveal.js 历史上最大的一次重构？

在 reveal.js 3.x 时代，框架的设计深受早期 Web 前端规范影响：核心代码直接将 Reveal 挂载为浏览器全局对象 window.Reveal，各插件（如 Markdown、Highlight 代码高亮、Notes 演讲者备注）则依赖附带的第三方加载器 head.min.js 进行动态 script 脚本注入。这种设计在单页引入简单幻灯片时很方便，但在现代工程化开发中暴露了诸多缺陷：

• 全局命名空间污染与单例限制：旧版本无法在同一个 HTML 页面中优雅初始化两个独立的幻灯片容器；
• 脚本加载竞态与不透明性：通过 dependencies 数组在运行时动态创建 <script> 标签，无法被 Webpack、Vite、Rollup 等现代打包器进行静态分析和 Tree-shaking 优化；
• 生命周期控制薄弱：基于传统 DOM 自定义事件（如 Reveal.addEventListener('ready')），在复杂异步加载场景下容易因时序问题引发插件注册丢失。

reveal.js 4.x 彻底重写了框架底层，全面拥抱原生 ES Modules（ESM），将所有静态产物统一归拢至 dist/ 目录，确立了清晰的类实例化与标准插件契约。

二、静态资源与目录结构变更

升级的第一步是修正 HTML 模板中的静态资源引用路径。4.x 放弃了以往在根目录下分散存放 css/ 与 js/ 的做法，将构建产物集中到了 dist/ 文件夹，并彻底剔除了 lib/js/head.min.js 依赖。

1. 核心与主题样式路径迁移

在 3.x 中，主样式与主题样式分别存放在 css/reveal.css 和 css/theme/。在 4.x 中，这些资源被转移至 dist/ 目录：

<!-- reveal.js 3.x 引入方式 -->
<link rel="stylesheet" href="css/reveal.css">
<link rel="stylesheet" href="css/theme/black.css">

<!-- reveal.js 4.x 引入方式 -->
<link rel="stylesheet" href="dist/reveal.css">
<link rel="stylesheet" href="dist/theme/black.css">

2. 彻底移除 head.min.js

3.x 的 HTML 底部通常会包含 <script src="lib/js/head.min.js"></script>。在 4.x 中，请务必从 HTML 中完全删除该标签。4.x 不再依赖它来加载脚本，保留它不仅无用，还可能在某些严格安全策略（CSP）环境下报错。

三、初始化方式与生命周期管理

在 3.x 中，初始化是通过静态单例方法 Reveal.initialize(Ellipsis) 同步执行的。而在 4.x 中，框架引入了面向对象的类模式，并全面支持 Promise 异步管道。

1. 实例化模式：从全局单例到 new Reveal()

在 4.x 中，推荐使用 new Reveal() 显式创建幻灯片实例。这不仅带来了更纯粹的作用域隔离，还允许在一张网页中挂载多个独立的幻灯片容器：

// 3.x 旧版：直接调用全局对象
Reveal.initialize({
  controls: true,
  progress: true
});

// 4.x 推荐写法：实例化后启动
let deck = new Reveal({
  controls: true,
  progress: true
});
deck.initialize();

如果页面中存在多个演示文稿，可以在构造函数中传入容器 DOM 节点：

// 4.x 支持同页面多实例演示
let deckA = new Reveal(document.querySelector('.deck-alpha'), { ... });
let deckB = new Reveal(document.querySelector('.deck-beta'), { ... });

deckA.initialize();
deckB.initialize();

（注：若不需要多实例，4.x 依然保留了全局快捷调用 Reveal.initialize(Ellipsis)，但底层同样是创建默认实例并挂载到 window）。

2. 基于 Promise 的异步初始化

在 3.x 中，如果需要在幻灯片和插件加载完成后执行自定义逻辑，通常要绑定 Reveal.addEventListener('ready', callback)。而在 4.x 中，initialize() 方法直接返回一个标准 Promise：

let deck = new Reveal({ ... });

// 使用 Promise 链式调用
deck.initialize().then(() => {
  console.log('幻灯片与全部插件已渲染完毕');
});

// 或者在 async 函数中使用 await
async function bootPresentation() {
  let deck = new Reveal({ ... });
  await deck.initialize();
  console.log('当前位于第 ' + deck.getIndices().h + ' 页');
}

3. 事件监听 API 简写：deck.on 与 deck.off

4.x 提供了类似 Node.js EventEmitter 的便捷方法：deck.on() 与 deck.off()，用来替代冗长的 addEventListener：

// 3.x 写法
Reveal.addEventListener('slidechanged', function(event) {
  console.log('当前页索引:', event.indexh);
});

// 4.x 写法
deck.on('slidechanged', event => {
  console.log('切换到横向幻灯片:', event.indexh);
});

四、插件体系改造：从 dependencies 到 plugins

插件加载机制是 3.x 到 4.x 最关键的代码破坏性变更（Breaking Change）。理解新旧两套插件机制的差异，是成功完成迁移的核心。

1. 3.x 的旧方案：dependencies 属性

旧版 reveal.js 中，每一个插件都是作为脚本路径对象写在 dependencies 数组里，并由内部动态拉取：

// 3.x 废弃写法：
Reveal.initialize({
  dependencies: [
    { src: 'plugin/markdown/marked.js' },
    { src: 'plugin/markdown/markdown.js' },
    { src: 'plugin/highlight/highlight.js', async: true },
    { src: 'plugin/notes/notes.js', async: true }
  ]
});

2. 4.x 的新方案：标准 plugins 数组

在 4.x 中，插件必须在调用 initialize() 前先被载入页面（通过传统 <script> 标签或 import 语句），然后在配置对象的 plugins 字段中直接传入插件函数的引用：

方式 A：基于传统脚本引入（适用于纯 HTML 页面）

<!-- 1. 引入 4.x 核心脚本 -->
<script src="dist/reveal.js"></script>

<!-- 2. 依次引入所需插件（此时插件自动暴露全局变量 RevealMarkdown 等） -->
<script src="plugin/markdown/markdown.js"></script>
<script src="plugin/highlight/highlight.js"></script>
<script src="plugin/notes/notes.js"></script>

<!-- 3. 注册插件实例 -->
<script>
  let deck = new Reveal({
    plugins: [ RevealMarkdown, RevealHighlight, RevealNotes ]
  });
  deck.initialize();
</script>

方式 B：基于 ES Module（适用于现代前端工程）

import Reveal from 'reveal.js';
import Markdown from 'reveal.js/plugin/markdown/markdown.esm.js';
import Highlight from 'reveal.js/plugin/highlight/highlight.esm.js';
import Notes from 'reveal.js/plugin/notes/notes.esm.js';

let deck = new Reveal({
  plugins: [ Markdown, Highlight, Notes ]
});
deck.initialize();

五、核心配置项与 API 方法变更对照表

在进行配置迁移时，需要关注以下属性与常用 API 的更替，确保行为与预期一致：

六、实战：四步平滑迁移演练

为了让已有项目从 3.x 顺利升级至 4.x，建议遵循以下标准四个阶段逐步推进并执行功能回归：

第 1 步：更新依赖与清理 HTML 引用

如果是 npm 项目，首先更新包版本号：

npm install reveal.js@^4.6.0

打开 HTML 文件头部与底部，修改静态资源引入链接：

• 将 css/reveal.css 替换为 dist/reveal.css；
• 将 css/theme/*.css 替换为 dist/theme/*.css；
• 删除 <script src="lib/js/head.min.js"></script>；
• 将 js/reveal.js 替换为 dist/reveal.js。

第 2 步：调整插件脚本引入

在 <body> 闭合标签前，按照你的展示需求引入对应的插件脚本。例如常规使用的代码高亮与演讲者备注：

<!-- 4.x 插件规范引入 -->
<script src="plugin/highlight/highlight.js"></script>
<script src="plugin/notes/notes.js"></script>
<script src="plugin/markdown/markdown.js"></script>

第 3 步：重写脚本初始化配置

将过去的 dependencies 移除，换成现代化的 plugins 声明，并将 history: true 替换为 hash: true：

<script>
  // 初始化实例
  const deck = new Reveal({
    hash: true,
    slideNumber: 'c/t',
    plugins: [ RevealHighlight, RevealNotes, RevealMarkdown ]
  });

  // 启动并捕获就绪状态
  deck.initialize().then(() => {
    console.log('reveal.js 4.x 已就绪');
  });
</script>

第 4 步：功能验证与关键特性回归清单

完成修改后在浏览器中打开页面，依次核对以下 5 项测试指标：

1. 控制台错误排查：打开开发者工具控制台，确认没有 404 Not Found 资源错误，也没有未捕获的 JavaScript 异常；
2. URL Hash 导航测试：使用键盘方向键切换幻灯片，检查浏览器地址栏是否正常呈现 #/1、#/2/1 等哈希路由；刷新网页时应停留在当前幻灯片；
3. 代码高亮渲染：检查包含 <pre><code> 的代码段是否正确带有语法高亮色彩；
4. 演讲者视图调试：在页面按键盘按键 S，检查是否能够正常弹出独立的演讲者控制窗口（包含计时器、预览和备忘录）；
5. 全屏与快捷键：按 F 键测试全屏切换，按 O 键进入总览网格视图（Overview mode），确认页面缩放排版正常。