Communitygithub.com

滚动动效

使用 GSAP、ScrollTrigger 和 Lenis 为网站添加滚动驱动和入场动画,包括文本揭示、视差效果、固定区块、水平滚动、线条绘制、数字计数和预加载器。

滚动动效 是什么?

本技能为开发者提供一套完整的滚动动效实现方案,基于 GSAP、ScrollTrigger 和 Lenis 构建,适用于希望让网站“更具质感”的任何场景,包括平滑滚动、视差效果、文本揭示、固定滚动区块、水平滚动、动画预加载器等常见需求。它强调动效应服务于结构意图:每个效果都有明确的目的(如宣布新章节、展示内容关联、营造深度感等),而非纯粹装饰。技能提供了从安装、初始化(考虑 prefers-reduced-motion 偏好)、效果选择参考表、到性能优化规则(仅动画 transform 和 opacity、合理的持续时间和缓动)以及移动端适配和调试指导的完整实施方案。同时,它建议对于简单的 fade-up 效果可考虑使用 IntersectionObserver + CSS transition 以节省约 70KB,体现了务实的工具选择思路。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imperfec-t/webcraft/tree/main/skills/scroll-motion

在你喜欢的 AI 中提问

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

文档

滚动动效 是做什么的?

动效应阐明结构:什么内容是新的,哪些内容属于同一组,接下来该看什么。如果动画无法实现这些,那它只是装饰且消耗性能,因此下方每个效果都与其目的紧密关联。

安装

<script defer src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/lenis@1/dist/lenis.min.js"></script>
<script defer src="/js/main.js"></script>

defer 可防止脚本阻塞首次渲染,同时确保它们按顺序执行,因此 main.js(下方代码所在文件)能正常访问 gsap。生产环境中请锁定精确版本(如 [email protected])或自行托管文件。

gsap.registerPlugin(ScrollTrigger);

const reduce = matchMedia("(prefers-reduced-motion: reduce)").matches;
if (!reduce) {
  const lenis = new Lenis({ duration: 1.1, smoothWheel: true });
  lenis.on("scroll", ScrollTrigger.update);
  gsap.ticker.add((t) => lenis.raf(t * 1000));
  gsap.ticker.lagSmoothing(0);
}

将每个动画包裹在 if (!reduce) 中,或使用 gsap.matchMedia()。前庭功能障碍者出于健康考虑设置了该偏好,内容必须在无动效的情况下完全可见。

选择效果

目的效果参考章节
宣布一个新章节遮罩式标题揭示揭示效果
展示内容属于同一组交错淡入上移揭示效果
为图像增加深度感视差、剪贴路径揭示图像
讲述一个序列固定步骤、绘制线条固定效果
展示一系列作品水平滚动固定效果
强调一个数字向上计数细节
覆盖初始加载预加载器细节

每个效果的即用代码位于 references/snippets.md 中。准备实现某个效果时请阅读该文件;规划阶段不需要。

规则

  • 只动画 transform 和 opacity。 动画 top、width、margin 或 box-shadow 会在每一帧触发布局或重绘,在中档手机上造成卡顿。
  • 持续时间: 揭示效果 0.6 至 1.0 秒,悬停效果 0.2 至 0.3 秒。过长会让二次访问感觉缓慢。
  • 缓动函数: 入场用 power3.out,过渡用 power2.inOut,滚动绑定动画用 none(滚动本身提供缓动)。
  • 交错延迟: 0.06 至 0.12 秒。控制总量:12 张卡片时,只交错前 6 张,其余同时出现。
  • 只播放一次。 使用 once: true 或 toggleActions: "play none none none"。每次滚回都重新动效会令人疲惫。
  • 每页一个亮点。 固定区块或水平滚动效果一次令人印象深刻,三次则让人厌烦。
  • 在 JS 而非 CSS 中设置初始状态。 如果脚本加载失败,CSS 隐藏的内容将永远不可见。
  • 布局变化后刷新: 在字体和图片加载完成后调用 ScrollTrigger.refresh(),否则触发位置会发生偏移。
window.addEventListener("load", () => ScrollTrigger.refresh());
document.fonts?.ready.then(() => ScrollTrigger.refresh());

移动端

  • 在 768px 以下使用 gsap.matchMedia() 禁用固定区块和水平滚动;让内容正常堆叠。
  • Lenis 平滑滚动在触屏设备上常与原生动量冲突。除非用户特别要求,否则保持触屏滚动为原生(默认行为)。
  • 在小屏幕上将视差距离减半。

调试

  • 在 ScrollTrigger 中添加 markers: true 可以查看起始和结束标记线。
  • 固定开始时出现跳跃,通常意味着固定元素有 transform 父级或高度发生变化。
  • 动画过早触发:可能是其上方的图像加载较慢。请为图片设置明确的 width 和 height。
  • 无任何动画:检查 GSAP 插件是否已注册以及选择器是否匹配。

不使用 GSAP 的情况

对于小型网站上简单的淡入上移效果,使用 IntersectionObserver 添加一个类并配合 CSS 过渡即可,还能节省约 70KB。详见 references/snippets.md 的最后一部分。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

hero-section

Design and build the hero (first screen) of a website, including headline layout, media treatment, CTA, proof badge, marquee and entrance animation. Use this whenever someone asks for a hero section, a landing page header, "the top of my homepage", a cinematic or animated intro, a video background, a text marquee, or says their first screen looks plain or generic.

homepage-blueprint

Plan the section structure and content slots of a homepage for an agency, freelancer, studio or service business before any design or code. Use this whenever someone asks "what sections should my homepage have", "plan my website", "structure a landing page for my business", wants a wireframe or sitemap for a service site, or starts building a homepage without a clear outline.

responsive-layout

Build page layouts that work from phones to wide desktops using CSS grid, flexbox, container queries and fluid sizing, including card grids, bento grids, split sections, sticky sidebars and navigation that collapses. Use this whenever someone says their site "breaks on mobile", asks for a responsive grid, a bento layout, a mobile menu, fixing horizontal scroll or overflow, or is laying out any multi-column section.

website-workflow

Plan and sequence a whole website build, from structure through design, code, WordPress and launch, by routing each stage to the right webcraft skill. Use this when someone asks to "build me a website", "design my site from scratch", "redo our homepage", wants an end-to-end plan for a marketing, agency, studio or service site, or the request spans more than one of structure, look, layout, motion, CMS and QA.

相关技能