Communitygithub.com

滾動驅動的 3D 故事敘述

透過頁面滾動編排 3D 場景:實現滾動連結的鏡頭移動、逐段場景故事敘述、固定英雄區、流暢滾動,以及以滾動進度驅動的著色器與動畫。

滾動驅動的 3D 故事敘述 是什麼?

這項技能「滾動驅動的 3D 故事敘述」提供了一套完整的架構,讓 AI 網站的 3D 場景能夠隨著頁面滾動而展開敘事。其核心設計是將 Canvas 固定定位在 DOM 背景,透過讀取滾動進度值來驅動場景狀態的插值,而非直接劫持滾輪事件。開發者需要事先建立「故事板」,將滾動範圍對應到不同的場景狀態(如英雄區、功能說明、技術展示等),並為每個段落實現 (start, end, apply(t)) 的插值邏輯,以控制鏡頭位置、旋轉角度以及 uniform 數值。此外,此技能強烈推薦使用 Lenis 函式庫來實現流暢的慣性滾動效果,同時保持對原生滾動的支援,以確保無障礙性與 SEO 友善。為了最佳化效能,它還包含了 DPR 上限設定、非活躍分頁的渲染暫停機制,以及針對行動裝置的場景簡化建議。對於偏好減少動畫效果的使用者,技能也提供了 `prefers-reduced-motion` 的替代方案,以及在 WebGL 無法使用時的漸層背景與 DOM 故事備援。這套技能適用於 Claude Code、Cursor 等 AI 代碼助手,協助開發者創建如 Apple、Stripe 等頂尖 AI 網站般的沉浸式滾動敘事體驗。

相容平台~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 場景 講述故事 — 鏡頭滑行、模型組裝、粒子重新形成。這項技能就是實現此架構的方法。

架構:一個固定畫布,滾動驅動一個數值

畫布以 position: fixed 固定在 DOM 後面。滾動從不移動畫布——它移動一個場景用來插值的進度值。其他一切都是實作細節。

// DOM 正常滾動;我們只讀取,從不劫持。
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

在 RAF 迴圈中,根據 scrollProgress 插值場景狀態。這就是全部的重點:先建立一個故事板(如下所示),然後為每個段落編寫一個插值器。

故事板(務必先建立一個)

在寫程式碼之前,用註解或表格將滾動範圍對應到場景狀態:

0.00–0.15  英雄區:   模型漂浮在中央,緩慢旋轉,鏡頭 z=8
0.15–0.35  功能區:   鏡頭橫移至 x=-4,模型分裂成 3 個部分
0.35–0.60  技術區:   鏡頭軌道旋轉 90°,粒子群湧入,線框疊加層淡入
0.60–0.80  證明區:   鏡頭拉遠,場景變暗,DOM 卡片在畫布上淡入
0.80–1.00  行動呼籲區: 模型在中央重新組裝,光暈綻放,鏡頭 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 代替手動進度:仍然保持畫布固定並驅動場景狀態,不要讓 ScrollTrigger 轉換畫布。

鏡頭路徑

對於多段落的移動,可以透過關鍵幀位置定義一個 THREE.CatmullRomCurve3,並根據緩動後的進度對其取樣——這比直接線性插值點對更平滑。注視目標也有自己的曲線。關於緩動/曲線的細節,可參考 threejs-animation 技能。

DOM + 3D 同步

  • 段落文字是正常的 DOM;給它設定 mix-blend-mode 或半透明面板以疊在畫布上。
  • 將段落揭示與場景段落同步:從相同的 scrollProgress 範圍觸發 DOM 動畫(GSAP 或 CSS)——一個單一事實來源。
  • 透過每影格將世界座標投影到螢幕空間來定位 3D 標籤;當它們位於鏡頭後方時隱藏。

效能與行動裝置

  • 將畫布的 DPR 保持在一倍(上限 1.5–2);滾動連結的場景無論滾動與否都會在每影格重新渲染——減少其他每影格的工作。
  • 當分頁或場景遠離螢幕時暫停 RAF 渲染(document.visibilityState,對段落使用 IntersectionObserver)。
  • 行動裝置:減少段落(而不是滾動長度),降低粒子數量,停用後處理(請參閱 threejs-performance 和 threejs-postprocessing 技能)。
  • iOS Safari:網址列調整大小會在中途更改 innerHeight——對調整大小進行反彈處理,如果段落看起來會跳動,優先使用 visualViewport 感知的高度來計算進度。

無障礙與備援

  • 遵守 prefers-reduced-motion:將最終組裝狀態渲染為靜態場景,跳過鏡頭編排;滾動保持正常。
  • 3D 關閉時的備援(GPU 較弱 / failsIf):漸層背景 + 相同的 DOM 故事。故事必須在沒有 WebGL 的情況下也能存在。

常見錯誤

  • 劫持滾動事件或滾輪——這是「高級」網站感覺有問題的第一大原因。
  • 每影格讀取 scrollHeight(佈局抖動)——在調整大小時快取。
  • 將原始的線性進度應用於鏡頭移動——務必使用緩動(慢入慢出),否則感覺很機械。
  • 多個 ScrollTrigger 各自修改相同的場景屬性——它們會互相衝突;透過一個進度值來路由所有事情。
  • 忘記在迴圈中呼叫 lenis.raf(time) → 滾動感覺卡死。

相關技能

  • threejs-animation — 緩動、曲線、變形
  • ai-website-aesthetics — 段落的視覺外觀
  • threejs-postprocessing — 段落之間的光暈漸變
  • 3d-hero-interactions — 英雄段落的點擊/懸停行為

相關技能