BSMNT 滚动讲述

BSMNT 滚动讲述是一个用于创建滚动讲述动画的库。它由 GSAP ScrollTrigger 驱动，但抽象了一些内容，使其能更好地与 React 配合使用。

---

👇 新文档在这里！👇

• 💡 核心概念
• 📕 API 参考

---

安装

首先，我们需要 @bsmnt/scrollytelling 包以及必需的对等依赖：GSAP。

yarn add @bsmnt/scrollytelling gsap

为什么

在 basement，我们构建了许多使用滚动动画的网站。多年来，我们面临一些问题，需要在不同项目中复制粘贴解决方案。我们决定构建一个库，与世界分享我们如何构建这些动画。

我们面临的挑战

• 需要深入了解 GSAP 如何与 ScrollTrigger 配合使用。
• 需要谨慎地在 useEffect 中运行动画，然后清理它们。
• 无法从 开始 和 结束 的角度思考滚动动画，因此很难在我们需要的确切滚动进度处触发动画。

是什么

我们旨在将构建滚动动画的方式组件化，以实现：

• ✅ 为滚动动画提供合理的默认值，如 scrub: true 和 ease: 'linear'。
• ✅ 处理组件的挂载和卸载。
• ✅ 创建具有由 开始 和 结束 定义的绝对定位的动画，而不是基于时间的 持续时间。

作为额外的好处，采用"基于组件"的方法使我们能够：

• ✅ 提高与 React 服务器组件的兼容性：我们的组件绝对是 'use client'，但不一定是我们组件的父组件或子组件。
• ✅ 在树的每个层级组合动画，因为它都使用 React Context。

这是一个简单的示例，展示了它的工作原理：

导出

• Root：创建时间线和 scrollTrigger，提供 React Context。
• Animation：将动画附加到时间线。接收一个 tween 属性，用于控制动画的行为。
• Waypoint：在时间线的特定点运行回调或 tween。也可以接收 label 属性，在该位置创建 GSAP 标签。
• RegisterGsapPlugins：注册自定义 GSAP 插件，如果您的特定用例需要它们。
• Parallax：创建简单视差效果的辅助工具。
• ImageSequenceCanvas：创建简单图像序列动画的辅助工具。
• useScrollytelling：Context 消费者。返回 timeline。
• useScrollToLabel：滚动到您传递的标签名称。可以使用 Waypoint 组件添加标签。

演示

我们制作了一个小型演示来展示这个库的实际应用。这是了解库在真实场景中如何工作的最佳方式。查看：

• 网站 URL：https://scrollytelling.basement.studio/
• 代码：https://github.com/basementstudio/scrollytelling/blob/main/website/README.md

示例

• 简单补间：https://stackblitz.com/edit/react-ts-8rqm8k?file=App.tsx
• 使用 Lenis 平滑滚动：https://stackblitz.com/edit/react-ts-uuwfed?file=App.tsx
• 分层固定：https://stackblitz.com/edit/react-ts-4dtlww?file=App.tsx
• Three.js 管道：https://codesandbox.io/s/978cns?file=/src/App.js

故障排除

<details> <summary> <b>"我的简单动画在滚动时没有任何反应"</b> </summary>

请检查 Root 组件的 start 和 end 值。典型的问题出现在：

1. 您的动画 "在滚动器的开始碰到视口的开始时开始"，
2. 您的动画 "在滚动器的底部碰到视口的底部时结束"，
3. 您的 Root 包裹的元素只有 100vh 高，所以动画的持续时间为 0。

要解决这个问题，可以增加 Root 包裹元素的高度，或者调整 end 值为类似 bottom start 的值，这意味着"当滚动器的底部碰到视口的开始时"。

</details>

---

GSAP 文件受 GreenSock 的标准许可证约束，可以在 https://greensock.com/standard-license/ 找到