guided-demo

引导式演示模式

为任何 HTML／Web 应用添加自述式演示。声明式步骤数组驱动 setTimeout 循环，为 DOM 元素切换 CSS 类，并在固定面板中逐字写入文本。引擎会叠加在现有页面上，不修改其代码。演示停止时，所有状态都会重置。

核心部分约 100 行 JS 和 30 行 CSS。过场、速度控制、键盘快捷键和进度条都是可选的扩展功能。

实现前

向用户询问以下问题（对话中已回答的问题可跳过）：

1. 有哪些区段？ 标签页、路由、滚动位置、幻灯片索引？这决定了区段切换的方式。
2. 使用什么框架？ 原生 HTML 可直接使用。React／Vue／Svelte 需要将引擎作为条件叠加组件，并且必须在渲染后运行 querySelector。
3. 演示时由讲解者同步讲解，还是由演示自行讲解？ 同步讲解：文本更短，停顿更长。自行讲解：文本更详细，停顿适中。
4. 需要触发哪些交互元素？ 将它们映射到步骤操作。确认 CSS 选择器稳定（不是框架生成的哈希值）。
5. 是否需要离线使用？ 如果需要，请将所有内容放在一个文件中。使用 CDN 依赖时必须提供备用方案。
6. 有多少个步骤？ 推介演示少于 15 步，详细演示为 20–30 步。超过 40 步会让观众失去注意力。
7. 是否需要支持触屏设备？ 大多数引导式演示面向桌面／笔记本电脑演示场景。讲解面板带有可在触屏设备上使用的屏幕内上一步／播放／下一步按钮，但通常不需要滑动手势或移动端专用布局。

实现

阅读 references/implementation.md，了解所有代码片段（原生 JS／静态 HTML）。如果目标应用使用 React 和 React Router，还要阅读 references/react-integration.md，了解针对 React 的模式，包括过期闭包、路由导航时序和组件架构。对于其他 SPA 框架（Vue、Svelte 等），同样的概念也适用（路由切换后轮询查找元素，在响应式系统之外存储与计时器相关的状态），但实现细节有所不同。

必需的四个部分：

1. 讲解面板——固定定位栏，包含文本容器和进度条
2. 高亮类——使用 outline（而非 border），带有动画光晕，且不引发布局偏移
3. 打字机函数——递归调用 setTimeout，通过 textContent 设置讲解文本（绝不使用 innerHTML 设置用户编写的讲解文本），通过 CSS 实现闪烁光标。每次计时前使用 innerHTML = '' 清空内容是有意为之且安全的（不涉及用户内容）
4. 播放循环——playStep(idx) 用于切换区段、执行操作、添加高亮、逐字显示文本并自动进入下一步

步骤数组

唯一事实来源。每个步骤都是一个普通对象：

const DEMO_SCRIPT = [
  { section: 0, target: '.card', text: "Narration text." },
  { section: 1, target: null, text: "Transition.", transition: true },
  { section: 1, target: '#el', text: "Detail.", action: 'open', actionTarget: 'panel-id' },
];

属性：section（视图）、target（CSS 选择器或 null）、text（讲解文本）、transition（是否显示过场）、action／actionTarget（触发界面变化）、delay（可选的每步停顿时长，单位为 ms；默认使用 PAUSE_MS）。

默认时序

常量	默认值	何时调整
TYPE_SPEED	5ms/字	长文本用 3ms，戏剧性短句用 15ms
PAUSE_MS	3000ms	如果观众是阅读而非聆听，可调至 4–5s
速度范围	0.5x–2x	两个常量都除以倍率

撰写讲解文本

打字机效果会逐个显示单词，因此写作风格很重要：

• 使用简短的陈述句。每个步骤只表达一个要点。
• 采用对话式语气，使用现在时。直接面向观众讲解。
• 说明元素的含义，而不是界面显示了什么：“这一列量化了成本影响”，而不是“成本显示在这一列中”。
• 不要使用观众不熟悉的术语。术语应与领域相符，而非与实现方式相符。
• 由讲解者主讲的演示，每步不超过 30 个词；自行讲解的演示，每步最多 50 个词。

键盘控制

使用 isActive 标志控制所有键盘事件捕获，以免干扰页面的正常交互。空格键 = 播放/暂停，方向键 = 逐步切换，M 键 = 切换 TTS 旁白，Escape 键 = 退出并重置。

文本转语音旁白

通过浏览器原生的 Web Speech API speechSynthesis TTS，在打字机效果播放的同时朗读每个步骤的旁白。每个演示都应包含此功能，但默认关闭——未经用户明确操作，绝不朗读。用户可通过控制栏中的扬声器图标或 M 键切换此功能。有关语音选择、唯一调用位置和取消方式，请参阅 references/implementation.md（文本转语音旁白）。

步骤倒计时指示条

在步骤进度条下方放置一条细条，在打字机效果结束后的暂停期间填充，以显示自动进入下一步的剩余时间。每个演示都应包含此功能。有关 CSS 动画实现方式、放置位置以及通过 clearAllTimers() 重置的方法，请参阅 references/implementation.md（步骤倒计时指示条）。

可选：过渡插屏

在各部分之间显示全屏叠加层，并轮播状态消息，以模拟处理耗时。使用二维数组为每个部分定义消息。让每条消息淡出，然后通过回调关闭叠加层。

可选：步骤操作

在 executeStep() 中通过字符串匹配。操作会在高亮之前执行，因为折叠面板内的元素必须等面板打开后才能通过 querySelector 找到。添加新操作只需一个 if 代码块。保持简单。除展开/折叠之外的常见模式：expandOne（打开一个面板并关闭所有同级面板，呈手风琴样式）、call（触发命名函数，例如 requestBriefing()）、addClass/removeClass（在 document.body 上切换 CSS 类，以更改全局状态）。

易错点

以下问题反复出现：

• 布局偏移：使用 outline 而非 border 来实现高亮。轮廓不会影响盒模型。
• 隐藏元素：如果目标位于折叠容器内，必须先通过操作打开容器。因此，操作会在高亮之前执行。
• 动态选择器：框架生成的类名（.css-1a2b3c）在不同构建版本之间会变化。请使用 data-* 属性或 ID。
• 滚动冲突：scrollIntoView({ block: 'center' }) 会与固定页眉/面板冲突。请在滚动容器上设置 scroll-padding-bottom，以适应旁白面板的高度。
• Z-index：旁白面板设为 500+，插屏设为 490，高亮元素设为 2+。请检查是否与现有模态框或下拉菜单冲突。
• 退出时清理：重置演示更改过的所有状态：关闭已打开的面板、移除高亮、清除计时器。遗漏清理会导致令人困惑的 UI 状态。
• 表单输入：如果页面包含文本输入框、文本区域或选择框，键盘处理程序必须跳过它们。否则，在文本框中按空格键会触发播放/暂停，而不是输入空格。检查 e.target.tagName，并在其为 INPUT、TEXTAREA 或 SELECT 时直接返回。
• ES 模块：如果使用 <script type="module">，所有通过 onclick 调用的演示函数都必须挂载到 window.* 上。
• 打印：在 @media print 中隐藏演示面板和插屏。
• 无障碍：旁白面板应设置 role="status" 和 aria-live="polite"。高亮轮廓必须满足对比度要求。

适用场景

适用于：原型、PoC、HTML 幻灯片、数据叙事仪表板、产品演示、研讨会引导、投资者推介、入门引导流程。

不能替代：用户测试工具、屏幕录制工具、生产环境中的入门引导流程（这些场景应使用支持持久化和分析功能的引导库）。

对于框架应用，可将演示引擎挂载为条件叠加组件，并将脚本数组作为 prop 传入。对于单文件演示，可将所有内容内联，以便通过离线方式或 U 盘分发。