Communitygithub.com

滚动驱动3D叙事

编排随页面滚动而变化的3D场景:滚动关联的摄像机运动、逐节的场景叙事、粘性英雄区、平滑滚动,以及由滚动进度驱动的着色器/动画。

滚动驱动3D叙事 是什么?

该技能构建了顶级AI网站的标志性体验:当用户滚动页面时,3D场景会“讲述故事”——摄像机滑动、模型组装、粒子重组。其核心架构是将一个固定定位的3D canvas置于DOM后面,通过监听滚动事件来计算滚动进度值,然后驱动所有3D元素的状态变化(位置、旋转、材质参数等)。用户需要首先设计故事板,将滚动范围映射到场景状态,然后实现每个节拍的插值器。它推荐使用Lenis库实现平滑滚动,避免劫持原生滚动以保持可访问性。该技能适用于所有支持JavaScript的Web平台,并能与threejs-animation、GSAP ScrollTrigger等工具良好配合,同时提供了性能优化、移动端适配和无障碍回退方案。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BLACKNIGHT-cloud12/scroll-driven-3d-story/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

滚动驱动3D叙事 是做什么的?

顶级AI网站的标志性体验:页面滚动,3D场景讲述故事——摄像机滑动、模型组装、粒子重组。本技能正是实现这一架构的蓝图。

架构:一个固定canvas,滚动驱动一个数值

Canvas 以 position: fixed 固定在 DOM 后方。滚动永远不会移动 canvas——它只会移动一个场景用来插值的进度值。其他都是实现细节。

// DOM 正常滚动;我们只读取,从不劫持。
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

在 RAF 循环中,根据 scrollProgress 插值场景状态。这整场游戏就是这样:先构建一个故事板(见下文),然后为每个节拍编写插值器。

故事板(务必先做一个)

在写代码之前,先在注释或表格中映射滚动范围到场景状态:

0.00–0.15  hero:    model floats center, slow spin, camera z=8
0.15–0.35  feature: camera dollies to x=-4, model splits into 3 parts
0.35–0.60  tech:    camera orbits 90°, particles swarm in, wireframe overlay fades in
0.60–0.80  proof:   camera pulls back, scene dims, DOM cards fade over canvas
0.80–1.00  CTA:     model reassembles center, glow blooms, camera z=5

将每个节拍实现为 (start, end, apply(t)) 配对;将进度裁剪到每个范围,并在应用前对 t 进行缓动。在关键帧状态之间插值摄像机位置、旋转和 uniform 值——除非故意快照,否则不要在节拍中途跳变。

平滑滚动:使用 Lenis,而非劫持滚动

使用 Lenis 实现惯性感;它仍然驱动原生滚动(可访问性安全):

const lenis = new Lenis({ lerp: 0.1 });
function raf(time) { lenis.raf(time); update3D(); requestAnimationFrame(raf); }
requestAnimationFrame(raf);
  • 永远不要阻止原生滚动(在 body 上设置 overflow: hidden)——这会破坏键盘/移动端用户和 SEO。
  • 如果使用 GSAP ScrollTrigger 替代手动进度:仍然保持 canvas 固定并驱动场景状态,不要让 ScrollTrigger 变换 canvas。

摄像机路径

对于多节拍移动,定义一个 THREE.CatmullRomCurve3 通过关键帧位置,并用缓动后的进度采样——比在点对点上 lerp 更平滑。观察目标也有自己的曲线。关联 threejs-animation 以获取缓动/曲线细节。

DOM + 3D 同步

  • 章节文本是普通的 DOM;为其添加 mix-blend-mode 或半透明面板覆盖在 canvas 之上。
  • 将章节揭示与场景节拍同步:从相同的 scrollProgress 范围触发 DOM 动画(GSAP 或 CSS)——只有单一数据源。
  • 将 3D 标签锚定到屏幕空间:每帧将世界坐标投影到屏幕;当在摄像机背后时隐藏。

性能与移动端

  • 保持 canvas 在一个 DPR(上限 1.5–2);滚动关联场景每帧都会重绘,无论是否在滚动——减少其他每帧工作量。
  • 当标签页或场景远离屏幕时暂停 RAF 渲染(document.visibilityState,在章节上使用 IntersectionObserver)。
  • 移动端:减少节拍(而非滚动长度),降低粒子数量,禁用后处理(参见 threejs-performance 和 threejs-postprocessing 技能)。
  • iOS Safari:地址栏大小变化会在滚动中途改变 innerHeight——对 resize 进行防抖,如果节拍看起来跳跃,则优先使用 visualViewport 感知的高度来计算进度。

可访问性与回退

  • 尊重 prefers-reduced-motion:将最终组装状态渲染为静态场景,跳过摄像机编排;滚动保持正常。
  • 3D 关闭回退(弱 GPU / failsIf):渐变背景 + 相同的 DOM 故事。故事必须能在没有 WebGL 的情况下存活。

常见错误

  • 劫持滚动事件或 wheel——这是“高级”网站感觉糟糕的头号原因。
  • 每帧读取 scrollHeight(布局抖动)——在 resize 时缓存。
  • 将原始线性进度应用于摄像机移动——务必进行缓动(慢入慢出),否则显得机械。
  • 多个 ScrollTrigger 同时修改相同的场景属性——它们会冲突;将所有更新路由到一个进度值。
  • 忘记在循环中调用 lenis.raf(time) → 滚动感觉死板。

相关技能

  • threejs-animation——缓动、曲线、变形
  • ai-website-aesthetics——节拍的外观
  • threejs-postprocessing——节拍间的泛光渐变
  • 3d-hero-interactions——英雄节拍的点击/悬停行为

相关技能