html-presentation

HTML 演示文稿技能

将文档、大纲或自由形式的内容转换为精美、独立的 HTML 幻灯片演示文稿，并支持键盘和滚动导航。

触发此技能的情况

• 用户提供文档，并要求制作 HTML 格式的“演示文稿”“幻灯片”或“幻灯片组”
• 用户要求将笔记、大纲或内容转换为可在浏览器中展示的幻灯片
• 用户想要 Reveal.js 或基于滚动的 HTML 演示文稿
• 用户提到希望通过浏览器而非 PowerPoint 进行演示

步骤 0：收集需求

在生成任何内容之前，检查用户是否已说明以下事项。如果有任何缺失，请用一条简洁的消息请求澄清。不要询问超过一次——对于用户不愿说明的内容，请采用合理的默认值。

必需背景信息（缺失时请询问）：

参数	询问内容	未指定时的默认值
导航模式	“幻灯片应从左到右切换（水平），还是从上到下滚动（垂直）？”	horizontal
主题	“想要哪种视觉风格？选项：dark-editorial（深色背景、衬线标题、编辑风格）、light-minimal（简洁白底、无衬线字体）、corporate（海军蓝/白色、专业风格）、hacker（黑底终端绿字、等宽字体）”	dark-editorial
受众与语气	“这是面向谁的？（例如，投资者、工程师、会议演讲、内部团队）”	根据内容推断
幻灯片数量偏好	“大约需要多少张幻灯片？”	根据内容密度自动确定
品牌元素	“页眉中是否要使用任何徽标文字、标语或强调色？”	无
行动号召 / 结尾内容	“最后一张幻灯片是否需要行动号召、链接或联系信息？”	无

如果用户提供文档并提出类似“把它做成演示文稿”的要求，请一次性询问所有缺失参数。如果用户说“做得好看就行”，则使用默认值并继续。

步骤 1：分析源文档

阅读上传的文档或用户提供的内容。识别：

1. 逻辑章节——将其转换为幻灯片或幻灯片组
2. 关键数据点——数字、指标、百分比 → 使用指标/统计数据幻灯片布局
3. 列表和比较——功能列表、优缺点 → 使用卡片网格或比较表格
4. 引言或用户评价——使用引言区块布局
5. 顺序流程——工作流、时间线 → 使用工作流/时间线幻灯片布局
6. 标题和结论——为首尾幻灯片采用特别设计

编写 HTML 之前，先在脑中拟定大纲，将内容章节对应到幻灯片类型。

第 2 步：选择幻灯片布局

每张幻灯片都应采用以下布局模式之一。混合使用不同布局，让视觉效果更多样——同一种布局连续使用不得超过 2 张幻灯片。

布局	使用场景	CSS 类
标题	开场幻灯片、章节分隔页	slide--section slide--center
分栏	并排展示文本和辅助内容	split or split--60-40
卡片网格	展示 3-6 个相关项目（功能、风险、组件）	grid-2、grid-3、grid-4
指标	强调关键数字／统计数据	metrics with metric items
引言	专家引言、用户评价、关键陈述	quote-block
工作流	顺序流程、管道、架构	workflow with arrow connectors
对比表	功能对比、前后对比	comparison-table
时间线	按时间顺序排列的事件、路线图阶段	timeline
列表	有序或无序的要点	list、list--check、list--numbered
行动号召／结束页	包含链接和联系信息的最后一张幻灯片	slide--section slide--center + contact-grid

第 3 步：生成 HTML

编写代码前，请先从此技能的 references 目录中读取相应的主题和模板文件：

1. 务必阅读 references/THEMES.md，获取所选主题的 CSS 变量和样式
2. 务必阅读 references/TEMPLATES.md，获取各类幻灯片布局的 HTML 模式
3. 务必阅读 references/NAVIGATION.md，获取所选导航模式的正确 JS 初始化代码

然后将演示文稿组装为一个独立的 HTML 文件：

文件结构

<!DOCTYPE html>
<html lang="en">
  <head>
    
    
  </head>
  <body>
    
    
  </body>
</html>

关键规则

1. 单个文件——所有内容都内嵌。除 CDN 资源（Google Fonts、Reveal.js、Lucide 图标）外，不使用外部 CSS／JS 文件。
2. CDN 依赖项（水平模式）：
   • https://cdn.jsdelivr.net/npm/[email protected]/dist/reveal.css
   • https://cdn.jsdelivr.net/npm/[email protected]/dist/reveal.js
   • https://cdn.jsdelivr.net/npm/[email protected]/plugin/highlight/highlight.js（如果包含代码块）
   • https://cdn.jsdelivr.net/npm/[email protected]/plugin/highlight/monokai.css（如果包含代码块）
   • https://unpkg.com/lucide@latest（用于图标）
3. 垂直滚动模式——Reveal.js 不使用任何 CDN 依赖。使用自定义 CSS 滚动捕捉和原生 JS 实现键盘／滚动导航。
4. Google Fonts——加载与主题匹配的字体。始终使用 <link rel="preconnect"> 以提升性能。
5. 响应式——为 1400px、1024px 和 768px 断点添加媒体查询。
6. 片段动画——水平模式下使用 class="fragment" 实现渐进显示。垂直模式下使用交叉观察器淡入动画。
7. 幻灯片编号——始终显示当前幻灯片编号。
8. 导语文本——每张内容幻灯片都添加带编号的导语，例如 01 // Section Name，营造编辑风格。
9. 标题栏——每张内容幻灯片（标题页／章节页除外）都添加包含图标和章节标签的标题栏。

水平模式：Reveal.js 配置

Reveal.initialize({
  hash: true,
  slideNumber: true,
  controls: true,
  controlsLayout: "bottom-right",
  progress: true,
  center: false,
  transition: "slide",
  width: "100%",
  height: "100%",
  margin: 0.04,
  navigationMode: "linear",
  autoAnimate: true,
  autoAnimateDuration: 0.7,
  plugins: [RevealHighlight], // only if code blocks present
});

垂直滚动模式：导航行为

• 每张幻灯片都是一个视口大小的区域，并带有 scroll-snap-align: start
• 上、下、左、右方向键均可在幻灯片之间导航
• 鼠标滚轮可在幻灯片之间滚动（带防抖）
• 支持 Page Up/Down、Home/End
• 底部的进度条显示当前位置
• 幻灯片之间平滑滚动过渡
• 支持移动设备触摸滑动

步骤 4：写入输出

1. 在合适的输出路径创建 HTML 文件（例如 ./presentation.html，或使用用户指定的位置）
2. 将文件交付给用户

如果内容较多（超过 15 张幻灯片），请迭代构建：先编写框架，再分批追加幻灯片内容。

错误处理

问题	原因	修复
CDN 加载失败（Reveal.js、Lucide、Google Fonts）	网络不可用或 CDN 故障	改用内联样式/脚本：将 Reveal.js 核心代码内嵌，使用内联 SVG 路径替换 Lucide 图标，并使用系统字体栈（system-ui, -apple-system, sans-serif）
内容溢出幻灯片视口	每张幻灯片上的文本或元素过多	将幻灯片拆分为两张：把补充细节移至后续幻灯片，或将散文转换为项目符号列表
字体显示异常或加载失败	Google Fonts CDN 被拦截或响应缓慢	在 font-family 字体栈中添加系统字体回退：'Font Name', system-ui, Georgia, serif
Reveal.js 初始化失败	脚本加载顺序问题或缺少插件	确认 CDN 脚本标签位于 Reveal.initialize() 之前；检查浏览器控制台是否有 404 错误

质量检查清单

交付前，请确认：

• 所有幻灯片均可正常显示，且无溢出（内容适合视口）
• 方向键和鼠标滚动均可正常导航
• 幻灯片编号清晰可见
• 片段动画（水平模式）或淡入效果（垂直模式）正常
• 链接可点击（Reveal.js 中设置了 pointer-events: auto）
• 代码块具有语法高亮（如有）
• 在全部三个断点下均可自适应
• 没有失效的图标引用（Lucide 图标已初始化）
• 所有幻灯片的引导语编号保持一致
• 标题页和结束页采用了不同的视觉设计