reveal.js 初始化配置项详解及默认值说明

一、初始化机制与配置调用方式

reveal.js 的初始化本质上是一个异步就绪过程。自 reveal.js 4.0 引入现代化架构后，支持两种初始化形态：全局单例初始化（适用于单一全屏演示页）与多实例构造初始化（适用于页面嵌入多个幻灯片窗口）。

在 HTML 引入脚本与样式后，通常通过以下基础模板进行初始化：

// 方式 A：全局单例模式（最常用）
Reveal.initialize({
  hash: true,
  slideNumber: 'c/t',
  plugins: [ RevealHighlight, RevealNotes ]
}).then(() => {
  // 此时幻灯片布局已完成，插件均已注册就绪
  console.log('reveal.js 初始化就绪');
});

// 方式 B：指定容器的多实例模式
const deck = new Reveal(document.querySelector('.my-deck'), {
  embedded: true,
  keyboardCondition: 'focused'
});
deck.initialize();

无论采用哪种方式，配置项对象传入底层后，都会与内置的完整默认值对象进行浅层合并。未显式声明的参数将一律沿用官方默认值。

二、演示画布尺寸与自适应缩放配置项

reveal.js 的核心排版逻辑是“固定画布设计尺寸 + 等比缩放视口”。页面上的每个幻灯片元素并不是直接按屏幕绝对像素排布，而是在一个预设的虚拟逻辑画布中定位，再通过 CSS transform: scale(...) 缩放到当前浏览器窗口中。

三、导航控制与状态指示配置项

导航指示系统决定了演讲者与听众如何感知当前所处的位置，以及通过何种界面元素进行换页。

四、翻页交互、自动播放与行为控制

这一组配置控制用户日常操作的灵敏度，包括键盘快捷键的激活范围、鼠标滚轮响应、动画片段行为，以及展台轮播场景下不可或缺的自动翻页逻辑。

五、转场动画与外观视图配置项

转场过渡直接影响幻灯片的视觉观感与性能消耗。reveal.js 支持对页面切换动画和背景切换动画进行解耦独立配置。

六、视距加载、媒体与 PDF 打印导出配置

在包含大量高分辨率图片、嵌入式 iframe 网页或视频的长篇幻灯片中，如果一次性将全部资源加载至 DOM 中，容易造成内存剧增甚至浏览器卡死。为此，reveal.js 提供了懒加载视距管理机制。

七、配置项分类归纳与生产场景推荐预设

在实际项目交付中，直接依赖默认配置往往无法满足特定场合的严谨要求。根据演讲汇报、自动化信息大屏、嵌入式交互组件以及讲义打印等主流诉求，推荐以下配置模板。

典型生产配置示例代码

// 生产推荐：专业技术分享配置方案
Reveal.initialize({
  // 1. 采用主流 16:9 物理比例
  width: 1280,
  height: 720,
  margin: 0.06,
  minScale: 0.2,
  maxScale: 1.8,

  // 2. 状态与路由
  hash: true,
  respondToHashChanges: true,
  slideNumber: 'c/t',
  showSlideNumber: 'all',

  // 3. 控制与安全交互
  controls: false,                 // 隐藏屏幕边缘箭头，画面更干净
  progress: true,                  // 底部保留细进度条
  keyboard: true,
  keyboardCondition: null,
  mouseWheel: false,               // 强烈建议禁用，防止滚轮滑步
  touch: true,
  loop: false,

  // 4. 动效与视觉
  center: true,
  transition: 'fade',              // 'fade' 比 'slide' 更加沉稳且性能开销低
  transitionSpeed: 'default',
  backgroundTransition: 'fade',

  // 5. 视图管理
  viewDistance: 3,

  // 6. 插件集成（语法高亮与演讲者视窗）
  plugins: [ RevealHighlight, RevealNotes ]
});