着陆页动效
为已能正常工作的着陆页添加动效和 3D 效果。你添加的每个效果都必须有明确的目的、一个减少动效的变体,以及一个能让页面保持完整的回退方案。你开始工作前的静态页面就是那个回退方案:如果脚本加载失败、浏览器缺乏某项功能,或者访客要求减少动效,他们看到的是那个页面,而不是一个空白页。
输入
landing/direction.md,Motion and 3D intent部分。这是你的工作简报。它要么写着none,要么列出每个动效时刻及其用途。只实现它列出的内容。不要添加它未列出的动效时刻。- 由
landing-skills:landing-build构建的静态页面,或任何现有页面。该页面在禁用 JavaScript 后,必须能渲染所有文案和转化操作。请先检查这一点:如果不能,请先修复它,然后再添加动效,因为这里的所有方案都假设静态页面就是回退方案。 landing/tokens.css(如果存在)。在着色器和回退方案中使用其中定义的色彩。将动效相关的 token(时长、缓动函数)放在你自己的样式表中;保留tokens.css原有内容,不做修改。
当输入缺失时:
- 缺少
direction.md:询问用户哪些内容应该产生动效以及为什么。如果你无法询问,默认值为none(参见“决定哪些内容产生动效”),并在总结中加以说明。 - 缺少静态页面:停止工作,先构建一个静态页面(使用
landing-skills:landing-build),或者向用户索要。将动效叠加在一个只存在于 JavaScript 中的页面上,是导致 3D 场景失败时,连带毁掉标题和行动号召按钮的原因。 - 技术栈:读取
package.json。React(Vite、Next)项目使用提供 React 变体的方案;其他项目使用纯 HTML、CSS 和 JavaScript 变体。纯客户端 React 应用(所有内容渲染到空的#root中)在无 JavaScript 检查中会直接失败:文案必须首先通过服务端渲染、预渲染或references/webgl-3d.md中描述的岛屿模式出现在 HTML 中。
决定哪些内容产生动效
从 direction.md 中的意图开始。针对其中提到的每个动效时刻,写下:目标元素、角色(入场、反馈、与滚动关联、环境或交互相应 3D),以及访客能从中学到什么。如果你无法完成这个句式,就删除这个动效时刻。
none 是一个有效答案,通常是正确的答案,当意图缺失时也是默认值。许多页面在仅保留反馈状态动效的情况下就已经足够完整,尤其是在使用照片或文案作为主要内容时;几乎没有动效的页面并不会因此损失什么。
在 none 情况下,这是一次简短的检查,而不是新工作。landing-skills:landing-build 已经编写了悬停、聚焦、按下和禁用状态,以及一个包含发送、成功和错误状态的表单脚本。在浏览器中打开页面,并确认以下四点:
- 使用 Tab 键导航时,每个链接、按钮和字段上都显示可见的聚焦环。
- 按钮和链接上的悬停和按下状态有响应。
- 表单提交后,状态提示消息出现并获得焦点(
references/interaction.md,“表单提交反馈”提供了此功能,如果缺失则添加)。 - 没有内容自动动效:无自动播放、无循环、无滚动揭示。
可选地为悬停和按下状态添加时序(references/interaction.md,“悬停和按下状态”)。然后停止。如果你无法打开浏览器,请说明情况,并将上述四项检查列为“未执行”;不要报告页面已检查通过。
当意图明确列出了动效时刻时:
- 每页一个标志性动效。 英雄区序列、产品演示、3D 对象。其他所有动效都要比它安静。
- 按角色区变动效,绝不按区块区动。 反馈动效要快(100 到 200 毫秒),入场动效慢一些,与滚动关联的动效跟随滚动条。对每个区块应用相同的淡入上升、缓动和交错效果,是最容易识别的生成式页面模式,而且它不会给访客带来任何信息。
- 大部分内容不动。 访客正在阅读的文本绝不动:段落没有视差,不会使用在滚动到之前隐藏内容的滚动揭示效果。
- 演示,而非装饰。 能展示产品如何工作的动效(状态序列、分解视图、前后对比)才值得投入成本。仅仅表明“这个页面有动画”的动效,不值得。
在编写任何动效之前,先阅读 references/foundations.md。其中包含了时长、缓动函数以及那些看起来像生成式模式的列表,以及如何处理它们。
为页面匹配实现方案
实现方案附加在现有页面上,不会重新设置其样式。
- 由
landing-skills:landing-build构建的静态页面为每个意图中提到的动效时刻留下了占位符:一个海报图片或一个带有最终尺寸标注的占位符。如果构建过程中没有标记,请用data-moment="<name>"(名称来自Motion and 3D intent)标记该元素,并将实现方案附加到它上面:向该元素添加实现方案的容器类,或通过属性选择它。 - 每个实现方案的代码部分都以一行文字开头,说明它添加的新类(作为此技能的新增项),以及它保持不变使用的构建中的类。添加新类;永远不要重新定义构建自身的类(如
.hero、.hero__title、.button、.section、.split等)。如果实现方案需要布局,而构建的元素的布局不支持,则将其包裹在你自己的新元素中。 - 使用构建的 token(
--color-*、--space-*、--radius-control)为实现方案所需的任何颜色或尺寸赋值,绝不使用新的字面量值。
选择实现方案
选择能实现效果的最低层级:CSS,然后是小型脚本,然后是 GSAP 或 Motion,最后才是 WebGL。每个实现方案都包含“何时使用”、“何时避免”、“代码”、“减少动效”和“代价”;3D 方案还包含“回退方案”。
| 需求 | 阅读内容 |
|---|---|
| 时长、缓动函数、弹簧、交错、什么是生成式模式 | references/foundations.md |
| 英雄区入场、拆分文本标题、裁剪路径或蒙版揭示、计数器 | references/entrances-text.md |
| 滚动进度、与滚动关联的入场、粘性叙事、固定或水平区块、平滑滚动 | references/scroll.md |
| 随滚动变化的景深层、指针景深、图片或视频视差、React 中的视差 | references/parallax.md |
| 悬停和按下时的时序、表单提交反馈、磁性按钮、光标跟随器、倾斜、拖拽、步进旋钮、视图过渡 | references/interaction.md |
| 可旋转的 3D 对象、随滚动展开的分解视图、一个用于两个分离阶段的上下文、glTF 模型、React Three Fiber 岛屿模式 | references/webgl-3d.md |
| 导入和排除的内容、构建中未使用的解码器文件、制作海报、模型压缩和纹理 | references/webgl-assets.md |
| 随滚动运动的摄像机路径、着色器背景、粒子、图像失真、WebGPU | references/webgl-effects.md |
| 使用哪个库、其许可协议和体积、CSS 何时足够 | references/libraries.md |
| 减少动效的变体、WebGL 回退方案、暂停、预算、保护英雄区 | references/safety.md |
对于任何 3D 或 WebGL 工作,请先阅读 references/safety.md(场景方案会导入其辅助函数),然后是 references/webgl-3d.md 中的“任何场景之前”,最后只读你需要的实现方案。
安全护栏
以下内容适用于所有效果。references/safety.md 包含相关代码。
- 英雄区无需 JavaScript 即可渲染。 标题、引导语和行动号召按钮都在 HTML 中,并在首次绘制时可见。不要将标题或英雄区图片的 opacity 设为 0:opacity 为 0 的元素在显示出来之前不能成为“最大内容绘制”的候选,因此长时间入场动效会延迟 LCP。在 load 事件之后加载 3D 代码,并在绘制出第一帧之前,用海报图片占据其位置。
- 减少,而非删除。 指示文档自身关于减少动效的声明优先;以下描述的是默认行为。在
prefers-reduced-motion: reduce下,移除视差、滚动式动画(scrubbed scroll animation)、自动播放循环和大范围移动。保留反馈动效和短时间的淡入淡出。3D 场景仅在它是静态的且由用户驱动时才加载;跳过场景并显示海报是最简单正确的选择。根据效果编写减少动效的变体,并监听页面打开时偏好的变化。一个将所有动效时长归零的全局规则本身就是一种被识别出来的特征。 - WebGL 是可选的。 在下载任何 3D 代码之前检查上下文。在 React 中,将 canvas 包裹在错误边界内。处理上下文丢失。回退方案是一个真实的图片,绝不是一个空盒子。
- 仅一个 canvas。 第二个 WebGL 上下文会使内存和 GPU 工作量翻倍。将相关的 3D 动效放在一个粘性 canvas 中。
- 离开视口则停止运行。 Canvas、视频和循环在离开视口或标签页隐藏时停止。
- 滚动绝不重新渲染框架。 在帧循环中读取滚动位置,或者让 CSS 驱动它。每次滚动事件或每帧都不调用
setState。 - 仅对
transform和opacity进行动画。 绝不使用top、left、width或height。 - 自托管所有资产。 模型、解码器、环境贴图和字体都来自你自己的源站。一些辅助函数默认使用第三方 CDN;请覆盖它们。
- 交互需要键盘路径。 指针可以旋转、拖拽或切换的任何内容,键盘也能实现。
完成度定义
在浏览器中检查每一项。最好使用浏览器工具;如果没有,使用 landing-skills:landing-review 的截图脚本,并说明你无法执行哪些检查。
- 在
Motion and 3D intent中提到的每一个动效时刻都存在,并且除了反馈状态外没有添加其他内容。 - 在禁用 JavaScript 的情况下:所有文案和转化操作都存在。
- 在模拟减少动效的情况下:页面完整且可读,没有自动播放,没有视差,没有滚动式动画;反馈状态仍然有响应。
- 在禁用 WebGL 的情况下(Chromium 标志
--disable-webgl):在应该显示 3D 场景的位置显示海报或静态图片,英雄区文本和行动号召按钮未被触及。 - 英雄区文本在任何 3D 代码加载完成之前就已可见(可通过限制网络速度来检查)。
- 默认情况下,没有两个区块共享相同的入场动画;只有标志性动效是大型的。
- Canvas 在滚动离开视口时停止绘制(通过 Performance 面板,或像
references/safety.md中那样的绘制调用计数器)。 - 网络面板显示没有对第三方主机发起的 3D 资产请求。
- 在生产构建中,three.js 和其他 3D 代码处于一个不作为入口 bundle 一部分的 chunk 中。
- 键盘:每个旋转、拖拽和切换功能都能用按键操作;焦点保持可见。
特征检测工具 detect-tells.mjs 属于 landing-skills:landing-review,是一个可选辅助工具。如果它可用,在页面上运行它;它会标记模式级别的特征,例如常见的滚动揭示属性和减少动效的“kill switch”。必要的检查是人工完成的:在开启动效和减少动效的情况下各滚动一次整个页面,并确认每个正在移动的元素都具有你之前为其写下的角色。
最后为用户提供一个简短总结:添加的每个动效时刻及其用途、添加的库及其许可证、仍然需要的资产(例如,用于替换原始占位符的真实模型、海报图片),以及任何你未能执行的检查。