ScrollTrigger未生效最常见原因是未正确注册插件,必须显式调用gsap.registerPlugin(ScrollTrigger);触发位置不准源于锚点计算受布局干扰,应调整start/end值或加偏移;滚动回退不恢复需配置toggleActions;框架中需手动kill实例防泄漏。

ScrollTrigger 未生效,页面滚动无反应
最常见原因是没正确注册插件或没调用 gsap.registerPlugin(ScrollTrigger)。GSAP 3.12+ 默认不自动加载 ScrollTrigger,必须显式注册,否则所有 scrollTrigger 配置会被忽略,控制台也无报错。
实操建议:
立即学习“前端免费学习笔记(深入)”;
- 确保在调用
gsap.to()或gsap.from()前已执行gsap.registerPlugin(ScrollTrigger) - 检查脚本加载顺序:先加载 GSAP 核心(
gsap.min.js),再加载ScrollTrigger.min.js,最后注册插件 - 若用 ES 模块,需从
gsap/ScrollTrigger显式导入并注册,不能只 import { gsap } from "gsap" - 确认目标元素存在且非空 ——
document.querySelector(".target")返回null时,ScrollTrigger 不会报错但也不工作
动画触发位置不准,提前或延后触发
根本原因是 start 和 end 的触发锚点默认基于视口(viewport)计算,而实际内容常受 margin、padding、fixed header 等干扰。ScrollTrigger 默认把元素的 top 边缘对齐视口顶部作为 start: "top top",但若页面有 sticky 导航栏,这个“top”就偏高了。
实操建议:
立即学习“前端免费学习笔记(深入)”;
- 用
start: "top center"或start: "center center"替代模糊的"top top",减少布局偏移影响 - 加偏移量修正:如
start: "top bottom+=80"表示元素底部到达视口底部再上移 80px 时触发(适配 80px 高 fixed header) - 避免在
body上直接设overflow-x: hidden—— 这会导致 ScrollTrigger 计算滚动容器失败,改用html或明确指定scroller: "#main-container" - 启用
markers: true临时调试,直观看到触发线位置(上线后务必关掉)
滚动回退时动画不恢复或重复播放
ScrollTrigger 默认行为是「单向触发」,即进入时播放,退出时不自动逆播。如果需要进退都响应,必须显式配置 toggleActions,而不是依赖 scrub 或误以为 refreshPriority 能解决。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
实操建议:
立即学习“前端免费学习笔记(深入)”;
-
toggleActions接收四个字符串:"play pause resume reverse",分别对应 enter、leave、enterBack、leaveBack 四个状态 - 常见组合:
toggleActions: "play none none reverse"(进时播,退时反向播);toggleActions: "restart pause resume reverse"(进时重播,退时反向) - 慎用
scrub: true—— 它让动画随滚动实时插值,但会禁用toggleActions,且对性能敏感,复杂动画易卡顿 - 若用
gsap.set()初始化状态,请确保它在 ScrollTrigger 创建前执行,否则初始态可能被覆盖
React/Vue 中 ScrollTrigger 销毁不干净,导致内存泄漏或重复绑定
框架组件卸载时,ScrollTrigger 实例不会自动销毁,残留监听器会持续响应全局滚动事件,轻则动画错乱,重则拖慢页面。这不是 GSAP 的 bug,而是生命周期管理缺失。
实操建议:
立即学习“前端免费学习笔记(深入)”;
- 每次创建 ScrollTrigger 后保存其引用,例如
const st = ScrollTrigger.create({...}) - 在组件卸载钩子中显式调用
st.kill()(React useEffect cleanup / Vue onUnmounted) - 避免在渲染函数内反复调用
ScrollTrigger.create()—— 每次渲染新建实例,旧实例未 kill 就累积 - 使用
ScrollTrigger.refresh()替代重新创建,适用于 DOM 动态增删后的重计算(如 tab 切换后内容变化)
ScrollTrigger 的核心复杂点不在语法,而在它和滚动生命周期、DOM 存在周期、CSS 布局的耦合。哪怕配置写对了,只要 scroller 元素重绘、父容器 transform 变化、或框架 key 未稳定,都可能让触发线漂移 —— 这时候 markers 和浏览器开发者工具的 layout 面板比文档更管用。


















