html-slides

HTML 幻灯片 — 带动画、适配视口的演示文稿

生成专业动画、响应式视口适配和精选样式预设的单文件独立 HTML 演示文稿。运行时零外部依赖——所有 CSS/JS 均内联。

架构

每个 HTML 演示文稿都遵循以下结构：

1. 单文件 — 一个内联 CSS 和 JS 的 .html 文件（无需构建工具）
2. 适配视口 — 每张幻灯片锁定为 100vh/100dvh，并设置 overflow: hidden
3. CSS 自定义属性 — 所有主题样式均通过 :root 变量设置，方便重新设计样式
4. 语义化 HTML — 每张幻灯片使用一个 <section>，控件使用 <nav>
5. 渐进增强 — 无 JS 时也能正常运行，JS 可增强动画效果

强制视口规则

对每个演示文稿应用 assets/viewport-base.css 中的视口基础 CSS。关键规则：

• 每张幻灯片：height: 100vh; height: 100dvh; overflow: hidden
• 所有排版均使用 clamp(min, preferred, max) 实现响应式缩放
• 图片最大高度限制为 min(50vh, 400px)
• 在 700px、600px、500px 高度处设置响应式断点
• 包含 prefers-reduced-motion 支持
• 网格回退方案：grid-template-columns: repeat(auto-fit, minmax(min(100%, 250px), 1fr))

绝不允许在幻灯片内滚动。如果内容超出容量，请拆分到多张幻灯片中。

边缘情况：负数 Clamp 值 需要负的视口边缘间距（例如负边距、负内边距）时，请使用 calc(-1 * clamp(...))。此模式可在反转值的同时保留 clamp 函数的响应能力。

iOS Safari 的 100vh 问题 iOS Safari 中的 100vh 单位包含地址栏高度，可能导致内容溢出。请始终在回退链中同时使用 100vh 和 100dvh。如果存在 100dvh，现代视口会忽略 100vh。

动画系统

CSS 优先方案（默认）

以 CSS 动画作为基础方案。应用 .reveal 类，并通过 transition-delay 依次错开：

.reveal {
  opacity: 0;
  transform: translateY(20px);
  transition: opacity 0.6s var(--ease-out-expo), transform 0.6s var(--ease-out-expo);
}
.reveal.visible {
  opacity: 1;
  transform: translateY(0);
}

通过 Intersection Observer 在元素进入视口时添加 .visible 类来触发动画。

缓动：所有入场动画均使用 --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1)。

GSAP 增强（按需使用）

对于复杂动画，请从 CDN 加载 GSAP，并使用基于时间轴的编排。详细的 GSAP 示例请参阅 references/animation-patterns.md，API 参考请参阅 GSAP 文档。关键集成点：

• 从 https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js 加载 GSAP + ScrollTrigger
• 使用 gsap.timeline() 编排连续的幻灯片入场动画
• 使用 gsap.matchMedia() 实现响应式动画行为
• 遵循 prefers-reduced-motion 设置——启用时禁用动画

使用位置参数编排时间轴入场动画 在时间轴中使用位置参数错开显示，无需显式设置延迟。示例：

const tl = gsap.timeline();
tl.to('.heading', { opacity: 1, duration: 0.6 })
  .to('.subtitle', { opacity: 1, duration: 0.4 }, '<0.2') // Starts 0.2s before heading ends
  .to('.bullet', { opacity: 1, stagger: 0.1 }, '<0.15');

使用 SplitText 实现标题及单词/字符显示动画 为标题中的单个单词或字符添加动画：

gsap.registerPlugin(SplitText);
const split = new SplitText('.headline', { type: 'words,chars' });
gsap.from(split.chars, { 
  opacity: 0, 
  duration: 0.4, 
  stagger: 0.05,
  ease: 'back.out'
});

使用 ScrollTrigger 实现逐张幻灯片导航 将幻灯片切换与滚动位置关联，打造交互式演示文稿：

gsap.registerPlugin(ScrollTrigger);
gsap.to('.slide', {
  scrollTrigger: {
    trigger: '.slide-container',
    pin: true,
    scrub: 1,
    snap: 1 / slideCount
  }
});

Remotion 弹簧物理效果的时间参数 将 Remotion 弹簧物理效果转换为 GSAP 弹性缓动，实现自然运动：

• 平滑（阻尼：200）→ elastic.out(1, 0.1) — 轻微回弹，效果精致
• 利落（阻尼：20）→ elastic.out(1, 0.35) — 明显的弹簧效果，具有现代感
• 活泼（阻尼：8）→ elastic.out(1, 0.5) — 活泼回弹，充满动感

动画清单

动画	CSS 类	使用场景
淡入并向上滑动	.reveal	文本/卡片的默认入场效果
缩放进入	.reveal-scale	图片、功能卡片
从左侧滑入	.reveal-left	两栏内容
模糊进入	.reveal-blur	背景元素、叠加层
错开显示	:nth-child(n) 延迟	列表、网格项

动画指南

• 活泼：弹性缓动，400-600ms，交错显示
• 专业：轻柔淡入，200-300ms，尽量减少移动
• 电影感：缓慢淡入 1-1.5s，视差效果，缩放过渡
• 技术风：干脆、快速（150-200ms），无弹跳效果

幻灯片导航

加入键盘导航（方向键、空格键、Page Up/Down）、触摸/滑动支持，以及可选的进度指示器。模板见 references/html-template.md。

样式预设应用

从上级 slide-design 技能的 references/style-presets.md 中读取样式预设定义。每个预设都映射到 CSS 自定义属性：

:root {
  --bg-primary: #0a0a0a;
  --bg-secondary: #1a1a1a;
  --text-primary: #ffffff;
  --text-secondary: #a0a0a0;
  --accent: #4a9eff;
  --accent-secondary: #ff6b6b;
  --font-heading: 'Clash Display', sans-serif;
  --font-body: 'IBM Plex Sans', sans-serif;
  --title-size: clamp(2rem, 6vw, 5rem);
  --body-size: clamp(0.9rem, 2vw, 1.25rem);
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
}

从 Google Fonts 或 Fontshare 加载字体——标题绝不能依赖系统字体。

幻灯片类型模板

对于每种幻灯片类型，请遵循 references/html-template.md 中的 HTML 模式。关键模板：

• 标题页 — 全视口主视觉区域，包含标题、副标题和可选背景图片
• 内容页 — 标题 + 项目符号列表或段落，交错显示
• 双栏 — 并排布局，展示图片 + 文本或代码 + 说明
• 图片聚焦页 — 全幅或居中图片，叠加说明文字
• 代码页 — 使用 Prism.js（通过 CDN 加载）实现语法高亮的代码块
• 对比页 — 并排卡片或前后对比布局
• 引用页 — 居中引言块，附带出处
• 功能网格 — CSS Grid 卡片（最多 6 个），包含图标/标题/说明
• 时间线 — 水平或垂直的里程碑布局

Mermaid 图表支持

对于技术演示文稿，请嵌入 Mermaid 图表：

1. 引入 Mermaid CDN：https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.0/mermaid.min.js
2. 使用 <pre class="mermaid"> 代码块绘制图表
3. 支持流程图、时序图、类图和 ER 图
4. 使用与演示文稿配色相匹配的主题变量进行样式设置

PDF 导出支持

加入可选的打印样式表，通过浏览器打印导出 PDF：

@media print {
  .slide { page-break-after: always; height: 100vh; }
  .nav, .progress { display: none; }
  .reveal { opacity: 1; transform: none; }
}

反模式

避免以下常见错误：

• 在幻灯片内滚动（始终使用 overflow: hidden）
• 标题使用系统字体（始终加载 Web 字体）
• 使用千篇一律的“AI 垃圾风”美学（紫色渐变、到处都是 Inter）
• 使用内联样式（改用 CSS 自定义属性）
• 缺少对 prefers-reduced-motion 的支持
• 图片没有尺寸限制
• 功能网格中的项目超过 6 个

用视觉呈现，而非口头描述

践行视觉传达原则，以视觉权重和明确的设计意图强化说明：

• “做得醒目” — 同时提高字体粗细和字号，并搭配强调色。真正醒目的元素应主导视觉层级。
• “让它脱颖而出” — 同时结合 z-index 分层、scale 变换和对比色。要形成视觉隔离，三者缺一不可。
• “每张幻灯片只表达一个想法” — 内容超出承载能力时，应拆分到多张幻灯片。绝不要把字体缩小到最低字号阈值以下。内容拥挤是设计失败。
• 视觉层级规则：最重要元素的尺寸应为辅助元素的 3 倍。如果标题是 3rem，正文应约为 1rem。始终保持这一比例。

混合背景的演示文稿

许多专业演示文稿会在不同幻灯片组之间交替使用背景色。实现方式如下：

• 为每个 <section> 定义 data-theme 属性（例如 data-theme="coral"、data-theme="dark"、data-theme="cream"）
• 通过 [data-theme="coral"] { --bg-primary: #E8845C; --text-primary: #fff; } 为每种主题映射 CSS 自定义属性覆盖值
• 即使背景变化，也要保持字体和布局一致
• 使用对比鲜明的背景来标示章节过渡（例如，演示环节使用黑色背景，信息图使用奶油色背景）

内联编辑模式

生成的 HTML 可以在文本元素上包含 contenteditable="true" 属性，让用户在演示前直接在浏览器中编辑幻灯片。

若要启用内联编辑，请在文本元素上添加 contenteditable="true"：

<h1 contenteditable="true">Edit this headline</h1>
<p contenteditable="true">Edit this paragraph</p>

添加以下 CSS 以提供视觉反馈：

[contenteditable]:hover {
  outline: 2px dashed var(--accent);
  cursor: text;
}

[contenteditable]:focus {
  outline: 2px solid var(--accent);
}

用户可以点击任意可编辑元素，即时修改内容，并直接进行演示，无需导出。若要使用只读模式，请通过 contenteditable="false" 禁用编辑。

其他资源

参考文件

• references/html-template.md — 完整的 HTML 样板，包含导航和所有幻灯片类型模板
• references/animation-patterns.md — CSS 和 GSAP 动画方案，包含时序和缓动设置

资源文件

• assets/viewport-base.css — 必需的视口 CSS（每份演示文稿都要包含）

脚本文件

• scripts/extract-pptx.py — 从 PPTX 文件中提取文本、图片和备注，并转换为 JSON，以便转换为 HTML