安全尋幀動畫
HyperFrames 並非播放時間軸,而是「尋幀」:對於每一幀,渲染器將時間軸設為該幀的時間並捕獲頁面。使用 HyperFrames 0.8.x 時,它會透過三個平行工作線程進行,每個線程負責每三幀中的一幀,且每次尋幀會先回退 1 毫秒再向前移動以穩定狀態。因此,每一幀必須是其時間的純函數。任何依賴先前渲染內容、系統時鐘或隨機性的行為,都會在各工作線程中產生不同結果,導致元素在每三幀中遺失一次。
該錯誤在 Studio 預覽(按順序播放)和單張快照中不可見。在實際生產環境中,這是唯一能送到審查員面前的缺陷:開場標題在前七秒「抖動並閃爍」。
優先執行 lint
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video
它會讀取 index.html、src/*.tpl 以及與之相鄰的 *.js(僅內聯腳本),輸出 file:line: severity RULE: why 加上修復建議,並在發現任何錯誤時以狀態碼 1 退出(--strict 會將警告也視為失敗,--json 供工具使用)。在每次編輯時間軸後及每次渲染前執行。此工具為靜態分析:無法看到執行時期計算的變數(會將其標記為「無法檢查」)或兩個重疊的補間動畫。這些情況仍需您自行檢查,搭配下方的重現方法。qa.py(render-qa)也會執行此 lint,並在發現錯誤時使報告失敗。
規則及其存在原因
fromTo的 fromVars 中每個鍵也必須出現在 toVars 中(SS001,錯誤)。當工作線程的幀正好落在補間動畫的起始點時,1 毫秒的回退會將補間狀態還原到開始前,而僅存在於 fromVars 中的鍵將永遠不會再被寫入。標題補間動畫為fromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0}):opacity: 1只存在於 fromVars,因此一個工作線程會讓標題在該補間動畫期間保持不透明度 0。請將{yPercent: 110, opacity: 1}改為{yPercent: 0, opacity: 1},或使用tl.set()後接tl.to()。to()內部的startAt也適用相同規則(SS002)。- 在時間點 0 之後的每個
fromTo上設定immediateRender: false(SS003,警告)。否則補間動畫在時間軸建立時就會寫入其起始值,覆蓋先前補間動畫設定的內容,導致從時間軸中間開始尋幀時狀態錯誤。 - 優先使用
fromTo而非from(SS004,警告)。from()的結束狀態取決於元素在建構時的狀態;一旦先前的補間動畫觸及該元素,不同工作線程的結果就會不一致。 - 永遠不要動畫
display或visibility(SS005,錯誤)。這兩個屬性無法進行插值;它們會在補間動畫的任意時間點突然切換。請改用零持續時間的tl.set()在明確時間點進行切換,並使用opacity或autoAlpha來實現淡入淡出效果。 - 禁止使用時鐘、隨機性和計時器(SS006,錯誤):不可使用
Date、performance.now()、Math.random()、setTimeout、setInterval或requestAnimationFrame來控制任何可見元素。打字抖動或波形效果應使用帶種子的生成器;螢幕上顯示的呼叫計時器應透過時間軸的onUpdate回調中的tl.time()計算。 - 一個暫停的時間軸,已註冊,永不播放(SS007、SS011、SS012)。使用
gsap.timeline({ paused: true })建立時間軸,完全構建完成(如果位置依賴文字度量,則在document.fonts.ready內部構建),然後才賦值window.__timelines["<composition id>"] = tl。在構建完成前註冊空時間軸會導致空白影片;tl.play()會與渲染器的尋幀操作衝突。 - 滾動效果使用帶有明確起始和結束的
fromTo,以便每個工作線程計算相同的偏移量,且偏移量應限制在實際內容範圍內,避免線條或圖示停在邊緣處。 - 永遠不要在同一元素上同時有兩個補間動畫作用於相同屬性。 游標重置若落在下一次移動之內,會導致尋幀後指針位置錯誤。此規則無法透過 lint 檢查:請檢查建構時間表。
- 動畫變形屬性,而非佈局屬性(SS009,警告):使用
x、y、scale、clip-path而非left、top、width、margin。佈局補間動畫會使每一幀發生回流,且hyperframes check會將其標記為gsap_non_transform_motion。若實際產品控制項(如側邊欄展開)需要短暫的寬度變化,在能重現產品行為的前提下可接受。 - 永遠不要對
.clip元素進行補間動畫(SS010,錯誤)。HyperFrames 透過data-start和data-duration控制剪輯的可見性;請改為對剪輯內部的包裝元素進行動畫。 - 有限次數的重複(SS008,警告)。
repeat: -1僅允許在有限的根data-duration下使用;請使用Math.max(0, Math.floor(span / period) - 1)計算重複次數。 - 在時間點 0 明確設定所有初始狀態。 若輔助函數執行
gsap.set(sel, vars),也應執行tl.set(sel, vars, 0),這樣在尋幀回到 0 時才能恢復第一幀,而不是保持工作線程渲染的最後一個狀態。
渲染前重現疑似錯誤
lint 找到的是模式;快照才能證明像素。對於一個從 t0 開始的可疑補間動畫:
npx --yes hyperframes@<pinned> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<pinned> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b
從 t0 + 0.3 開始的幀在 a 和 b 中必須完全相同。如果不同,表示通過補間動畫起始點的尋幀操作改變了狀態。若要精確重現某個工作線程的行為,請依序對 0、3、6、... 等幀拍攝快照,直到超過補間動畫範圍。透過逐步縮小時間範圍來進行二分法,直到只剩一個補間動畫。渲染後,scan_render.py(render-qa)會將相同的錯誤回報為 WORKER PATTERN 執行結果:離群的幀都共享同一個幀索引模 3 的餘數。
參考資料
references/patterns.md:每個規則的前後對比程式碼、保持範本安全的輔助函數(lineIn、init、打字、滾動、游標點擊),以及 lint 能與不能檢查的內容。在編寫新的輔助函數或修正 lint 發現的問題時,請閱讀此文件。