演讲者备注插件

相关源文件

• plugin/notes/notes.esm.js
• plugin/notes/notes.js
• plugin/notes/plugin.js
• plugin/notes/speaker-view.html

本文档介绍 Reveal.js 的演讲者备注插件，该插件为演示者提供一个单独的窗口，其中包含演讲者备注、时间信息和幻灯片预览。本页面重点介绍备注插件的技术实现和使用方法。

有关在演示文稿中创建演讲者备注内容的信息，请参阅演讲者备注。

1. 概述

演讲者备注插件允许演示者：

• 查看每张幻灯片的私有备注，观众看不到
• 查看下一张幻灯片的预览
• 使用计时器和时钟跟踪演示时间
• 监控进度信息以保持按计划进行
• 从备注窗口控制演示

该插件通过打开一个独立的浏览器窗口来工作，该窗口通过 postMessage API 与主演示窗口通信，确保两个窗口保持同步。

来源：plugin/notes/plugin.js5-15

2. 架构

演讲者备注系统架构

来源：plugin/notes/plugin.js16-22 plugin/notes/plugin.js66-87 plugin/notes/speaker-view.html342-366

通信流程

来源：plugin/notes/plugin.js68-87 plugin/notes/plugin.js177-196 plugin/notes/speaker-view.html384-437

3. 使用演讲者备注插件

激活方法

该插件可以通过以下三种方式激活：

1. 键盘快捷键：在演示过程中按 's' 键
2. URL 参数：在演示 URL 中添加 ?notes
3. 通过编程方式：使用 Reveal.getPlugin('notes').open() 方法

来源：plugin/notes/plugin.js225-267

备注内容来源

该插件从以下来源检索备注，按优先级（从高到低）列出：

来源	格式	描述
片段备注	HTML/Markdown	片段内的 <aside class="notes">
片段数据属性	纯文本	片段上的 data-notes 属性
幻灯片备注	HTML/Markdown	幻灯片中的 <aside class="notes"> 元素
幻灯片数据属性	纯文本	幻灯片上的 data-notes 属性

当存在多个备注来源时，片段备注优先于幻灯片备注，以便演讲者可以在渐进式显示（progressive reveal）的每个步骤中拥有不同的备注。

来源：plugin/notes/plugin.js108-157

4. 演讲者视图界面

演讲者视图窗口分为几个部分：

可用布局

演讲者视图提供四种不同的布局，可以从右上角的下拉菜单中选择：

布局	描述
默认	当前幻灯片（左）、下一张幻灯片（右上）、备注（右下）
宽屏	当前幻灯片和下一张幻灯片并排（顶部），备注在下方
高屏	当前幻灯片在下一张幻灯片上方（左），备注在右侧
仅备注	仅显示备注部分（全窗口）

布局保存在 localStorage 中，以记住演示者的偏好设置。

来源：plugin/notes/speaker-view.html218-284 plugin/notes/speaker-view.html357-362 plugin/notes/speaker-view.html790-866

5. 时间管理功能

演讲者视图包含复杂的时间管理功能：

计时器组件

• 时钟：显示当前本地时间
• 计时器：显示自演示开始或上次重置以来的经过时间
• 进度：根据总演示时间显示当前幻灯片的剩余时间

幻灯片计时配置

该插件支持使用以下方式配置幻灯片的时间分配：

• 单个幻灯片上的 data-timing 属性（时间以秒为单位）
• Reveal.js 初始化中的 totalTime 配置（总演示时间）
• 用于默认每张幻灯片计时设置的 defaultTiming 配置
• 设置幻灯片计时警告阈值的 minimumTimePerSlide

来源：plugin/notes/speaker-view.html595-643 plugin/notes/speaker-view.html665-786

6. 技术实现

插件架构

备注插件遵循 Reveal.js 插件模式，主插件在 plugin.js 中定义，演讲者视图在单独的 HTML/JS 文件中。

来源：plugin/notes/plugin.js16-268

通信协议

演讲者备注插件使用定义明确的消息协议进行窗口间通信：

消息类型	方向	目的
connect（连接）	主窗口 → 备注窗口	使用演示 URL 启动连接
connected（已连接）	备注窗口 → 主窗口	确认连接成功
state（状态）	主窗口 → 备注窗口	发送当前演示状态
call（调用）	备注窗口 → 主窗口	请求调用 Reveal.js API 方法
return（返回）	主窗口 → 备注窗口	返回 API 调用结果
heartbeat（心跳）	备注窗口 → 主窗口	保持连接活跃并允许重新连接

每条消息都有一个 namespace 属性，设置为 'reveal-notes'，以标识其来源。

来源：plugin/notes/plugin.js77-82 plugin/notes/plugin.js93-102 plugin/notes/plugin.js108-159 plugin/notes/speaker-view.html403-413 plugin/notes/speaker-view.html451-462

安全考量

为防止 XSS 攻击，插件实现了源验证：

1. 仅当打开窗口与当前窗口具有相同源时，演讲者备注窗口才运行
2. 消息仅在来自相同源时才被处理
3. 对 file:// 源进行了例外处理，以支持本地演示

来源：plugin/notes/plugin.js166-195 plugin/notes/speaker-view.html373-378 plugin/notes/speaker-view.html387-391

7. 扩展演讲者备注插件

演讲者备注插件可以通过以下方法进行扩展：

自定义样式

可以通过修改 speaker-view.html 中的 CSS 来设置演讲者视图的样式。布局通过 CSS 控制，使用 body 上的 data-speaker-layout 属性。

添加自定义功能

可以通过以下方式添加自定义功能：

1. 修改 speaker-view.html 文件
2. 扩展 plugin.js 中的插件实现
3. 使用 Reveal.js API 进行窗口间通信

请注意，对演讲者视图文件的任何更改都需要重新构建插件。

来源：plugin/notes/speaker-view.html1-3

8. 常见问题和故障排除

问题	可能原因	解决方案
演讲者视图无法打开	弹窗拦截器	允许演示域的弹窗
连接错误	跨域问题	确保演示文稿从相同源提供服务
备注丢失	备注添加不正确	检查幻灯片中的备注语法
窗口断开连接	页面重新加载	演讲者窗口将尝试重新连接
F5 键问题	默认浏览器刷新	为防止断开连接，演讲者视图中禁用了 F5 键

来源：plugin/notes/plugin.js36-39 plugin/notes/speaker-view.html380-382 plugin/notes/speaker-view.html528-537