自动放映与翻页配置

本文说明如何为项目设置翻页动画和自动放映，以及从 Editor 进入放映后的控制方式。平台支持单窗口定时放映、媒体结束翻页和演讲者双窗口自动放映；无人值守长期放映尚未开放。

1. 配置项目默认值

1. 打开项目的页面列表，在顶部工具栏点击 项目设置，切换到 放映 分区。
2. 在 自动放映 区域设置：
   • 动画效果：none、fade 或 push。push 翻回上一页时方向自动反转。
   • 动画时长：none 必须为 0 秒；其他效果可设置 0.1～2 秒。
   • 翻页模式：手动翻页、定时翻页或媒体结束。手动模式保留停留时长，但不会自动翻页；媒体结束模式等待当前页参与的媒体全部播放完毕后翻页，没有参与媒体时按停留时长翻页。
   • 停留时长：定时模式下当前页就绪且过渡结束后的等待时间，媒体结束模式下无媒体时的回退时间，可设置 1 秒～1 小时。
   • 媒体等待上限：仅媒体结束模式可设置，默认 5 分钟，可设置 1 秒～1 小时；超时后进入错误暂停，可重试、跳到下一页或停止。
   • 循环放映：自动模式下末页后回到第一个可放映页面；手动模式末页不绕回。
   • 进入放映后自动推进：开启后进入全屏放映时按当前页翻页方式自动推进；关闭时先进入手动模式，仍可在放映控制条随时切回自动。
3. 点击 保存配置。配置会写入项目默认值，不影响页面源码，也不会创建页面变更任务。

浏览器要求全屏请求由用户手势触发。请在 Runtime 窗口中点击 进入放映（或按 F）；进入全屏即开始本次放映，退出全屏即结束放映并回到预览。按 F11 或使用浏览器菜单全屏只是把窗口放大，不会进入放映，也不会开始自动推进。

2. 设置旁白与音效

在资源库上传音频后，打开项目 项目设置 → 音频，调整主音量、旁白音量和音效音量，并按需绑定前进、后退或 interaction.* cue。保存后重新进入放映，才能让新快照使用更新后的绑定。页面旁白由页面中的 AssetAudio.v1 以 purpose="narration" 引用音频资源；页面交互音效由 useAudioCue.v1 触发。

旁白和 cue 在实际放映时播放；普通预览、截图和静态 PDF/PPTX 导出不会自动播放。浏览器阻止自动播放时可在放映控制条重试。当前实机证据以桌面 Chromium 为主，其它浏览器和部分音频格式需按实际环境确认。

3. 为单页覆盖默认值

1. 在 已加入路由 分区点击 页面结构，打开页面与放映顺序。
2. 点击目标页面行，在右侧检查器的 放映 区域勾选 覆盖翻页动画 或 覆盖翻页方式，填写该页的值；未勾选的项目继承项目默认值。
3. 修改会在草稿中立即生效，点击底部 保存页面结构 后写入项目。点击 恢复继承 会清除该页覆盖，重新使用项目默认值。

覆盖按整组生效：勾选“覆盖翻页动画”后，效果和时长一起写入；清除时整组恢复继承。分组不能单独覆盖，组内页面各自设置；选中分组后点击 批量设置本章 可以统一修改本章子页。

页面结构顶部会显示项目默认放映摘要和预计总时长；预计时长不含手动页停留时间，媒体结束页按兜底停留时间估算。隐藏页不显示在目录，也不参与自动或手动翻页。

4. 进入放映

• 在页面列表或页面详情点击 放映，会打开 Runtime 预览；在 Runtime 窗口点击右上角 进入放映（或按 F）后请求全屏，并开始本次放映。
• 在 页面结构 中选中页面后，点击检查器底部的 保存并从这里放映，会先保存整棵页面结构，再按该页生成新的只读快照；进入 Runtime 预览后同样需要点击 进入放映。选中分组时，从本章第一个可见子页开始。
• 非全屏状态只是预览：保留侧栏、缩略图、卡片、导出和翻页按钮，不启动任何自动计时。
• 进入全屏后只保留画布和一条放映控制条；侧栏、缩略图、导出和旧翻页按钮隐藏。
• 退出全屏即结束本次放映并返回预览，当前页保持不变。浏览器拒绝全屏时留在预览并显示提示，不会降级为窗口放映。
• 每次放映都会生成一个新的只读快照；已经打开的放映窗口不会自动更新，修改配置后需要重新进入放映。
• 在预览工具栏或放映控制条点击 演讲（或按 Shift+P）会打开演讲者控制台和观众窗口。观众窗口是唯一放映和推进者；主窗口变为控制台，只发送命令并回显状态。
• 从预览直接进入演讲时，本窗口不会先开始放映；观众窗口按项目的 进入放映后自动推进 设置起步。从放映控制条进入时，观众窗口继承当前的自动/手动模式。

页面详情只有在页面已加入项目路由时才显示 放映 入口；未加入路由的页面不提供放映。隐藏页面不显示在目录，也不参与自动或手动翻页序列。

5. 放映中的控制

• 控制条只包含：上一页、自动/手动、下一页、页码、状态、剩余时间、演讲和退出。
• 控制条默认收起，鼠标移到窗口底部时显示，移开即隐藏；暂停、错误、受阻或结束状态会保持显示，方便继续、重试或退出。
• 翻页键：→、↓、PageDown、空格 下一页；←、↑、PageUp 上一页。自动和手动模式都可用，手动末页不会绕回首页。焦点停在按钮或链接上时，空格保留按钮的原生激活，不触发翻页。
• 跳页键：Home / End 跳到第一页 / 最后一页；数字键跳到对应页码。总页数超过 9 时支持两位数字，连续输入后约 0.6 秒生效；页码不存在时给出行内提示。
• 预览状态另有：O 打开卡片模式，F 进入放映，Shift+P 打开演讲者模式；放映状态保留 Shift+P。输入框、文本域和可编辑区域内的按键不会被拦截。
• 自动/手动：自动模式按当前页翻页方式推进；切换到手动只停止页面自动前进，正在播放的媒体继续。再切回自动时，定时页重新计一整轮停留；媒体结束页按媒体是否仍在播放决定等待结束或使用回退停留时间。
• 配置为手动的页面在自动会话中仍等待用户翻页，界面显示“本页手动”。
• 媒体结束模式下，控制条会显示“媒体播放中”或“等待媒体”；播放被浏览器阻止时提供重试、跳到下一页和退出，播放失败或超时进入错误暂停并提供同样入口。
• 自动模式末页且未循环时显示“已结束”，可重新开始或退出；手动模式末页等待用户退出或切回自动。
• 退出全屏会结束本次放映并清理计时和媒体，不保留后台推进。
• 切换到后台标签页或窗口会暂停计时，切回后不会自动继续，也不会补跳；需要手动继续。恢复后保持原来的自动/手动模式。
• 演讲模式下观众窗口是唯一推进者，控制台只发送命令并回显状态。观众窗口必须进入全屏后才能开始放映；退出全屏会暂停放映并显示提示，重新全屏后可从控制台继续。
• 观众窗口是只读画面，不响应本地翻页快捷键；请在控制台使用传输栏，或用方向键翻页、空格切换自动/手动。控制台键盘不受观众窗口是否全屏限制，命令由观众窗口按当前状态接收。关闭观众窗口后控制台显示等待，重新打开并全屏后需再次开始；重新打开的观众窗口按项目的 进入放映后自动推进 设置初始化，不继承控制台此前临时切换的自动/手动模式。
• 卡片模式或缩略图预览不会启动后台自动推进；退出卡片模式后保持停止状态。

6. 边界与已知限制

• 定时器从页面就绪且翻页过渡结束后开始计时。页面加载失败或浏览器阻止播放时，控制条会显示错误或受阻状态，可重试或手动翻页。
• 媒体结束模式只等待当前活动页内的非循环原生音视频；循环背景媒体不参与等待，第三方 iframe 播放器、Web Audio 和页面脚本自行创建的音频不在统一判定范围。
• 自动放映只影响放映窗口，不会操纵其他正在运行的浏览器；CLI 和 MCP 保存放映配置也不等于远程控制播放。
• 直接打开构建产物链接默认是预览，不会自动全屏或自动推进；无人值守场景需要在 Runtime 窗口内点击进入放映，或使用另行设计的 kiosk/自动化入口。
• 页面内的视频、图表等元素全屏时，本次放映不会结束，也不会自动暂停页面推进；退出该元素全屏后，浏览器通常不会恢复整个页面的全屏，会按退出全屏处理并结束本次放映。需要继续时请重新点击 进入放映。
• 当前只在桌面 Chromium 验证了媒体、全屏和双窗口；Firefox/WebKit 与移动端行内播放尚未验证，不列为已支持。无人值守长期放映尚未开放，需要独立代理服务与专项长稳验收。
• 截图、PDF、PPTX 和打印使用独立捕获上下文，不会启动自动放映或推进主窗口；媒体在截图中保持暂停首帧。

7. 用 CLI 配置

CLI 使用 wp project slideshow get/update 读写项目默认值，使用 wp project route update 修改页面结构与逐页覆盖，使用 wp project audio get/update/clear 维护项目音量与 cue 绑定。字段语义与 Editor 一致：完整对象写入、显式 null 恢复继承、只读生效值 effective_slideshow 不得回写。具体命令以 CLI 当前帮助为准。