Communitygithub.com

滾動動畫

使用 GSAP、ScrollTrigger 和 Lenis 為網站添加滾動驅動動畫和進場動畫,包括揭示效果、視差、固定區塊、水平滾動、線條繪製、計數器和載入動畫。每當有人希望網站「感覺高級」、要求流暢滾動、滾動動畫、視差、文字揭示、固定或黏性滾動區塊、動畫載入畫面,或提及 GSAP、ScrollTrigger、Lenis、Locomotive 或 AOS 時,請使用此技能。

滾動動畫 是什麼?

這個「滾動動畫」技能專門為網頁開發者打造,用於建立高品質的滾動驅動動畫和進場動畫,提升網站的視覺層次與「高級感」。它整合了三款強大的 JavaScript 函式庫:GSAP 負責高效能動畫、ScrollTrigger 將動畫綁定到滾動位置、Lenis 則提供流暢的平滑滾動體驗。技能涵蓋多種實用效果,包括文字揭示、視差滾動、固定區塊、水平滾動、線條繪製、數字計數器以及初始載入動畫,每個效果都對應特定的設計目的,例如宣告新區塊、展示項目歸屬或強調數字。技能支援所有主流瀏覽器與裝置,並內建對 `prefers-reduced-motion` 的尊重,確保無障礙性。文件中提供可直接複製的程式碼片段,並包含行動裝置最佳化建議與除錯指引,讓開發者能快速整合並避免常見陷阱。

相容平台~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(由 scrub 提供緩動)。
  • 交錯延遲: 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

對於小型網站上的簡單淡入上移效果,使用 IntersectionObserver 添加類別加上 CSS 過渡就足夠了,而且可以節省約 70 KB。請參閱 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.

相關技能