ScrollTrigger.batch

返回值 : 数组​

ScrollTrigger 实例的数组

细节​

创建一组协调的 ScrollTriggers（每个目标元素一个），这些 ScrollTriggers 在一定时间间隔内将其回调函数（onEnter、onLeave 等）打包处理，提供一个整洁的数组，使您可以轻松执行类似对同时进入视口的所有元素进行交错动画的操作。它是一个非常好的替代方案，IntersectionObserver因为它具有更广泛的兼容性和更容易操作。每种类型的回调都是单独打包的，因此onEnteronEnteronEnter回调仅与其他 onEnter 回调进行批量处理。

它所解决的问题​

通常情况下，每个 ScrollTrigger 都会在其回调（onEnter、onLeave 等）发生时立即触发，但如果你想协调所有在同一时间段内触发相似回调的元素进行动画操作（例如使用交错效果），该怎么办？这样手动完成可能会显得笨拙。

工作原理​

您可以传入元素（类似的选择器文本".class"或元素数组，如[element1, element2...]），以及包含您希望使用的任何回调的配置详细信息，ScrollTrigger.batch()将为每个这些元素创建 ScrollTrigger，并且批量处理发生在特定时间间隔内的回调（默认情况下大约为一次 requestAnimationFrame，所以几乎是立即的）。例如，假设您为您的批次定义了一个 their callbacks that occur within a certain interval (by default it's roughly one requestAnimationFrame, so almost immediately). For example, let's say you've got an onEnter，一旦其中一个元素的onEnter被触发，则会等待该批次其他目标在此时间间隔内发生的任何其他onEnter调用，并将它们收集到一个数组中，然后将其传递给onEnter您为该批次定义的回调。该回调将接收两个参数：

回调参数​

1. targets [Array]- 一个数组，包含在此时间间隔内触发相关回调的目标元素（即 ScrollTrigger 实例的触发器）。如果定义了batchMax，此数组的大小不会超过指定值。
2. scrollTriggers [Array]- 一个数组，包含在此时间间隔内触发相关回调的 ScrollTrigger 实例。这可能在需要检查其进度或方向或 kill() 它们时非常有用。如果定义了batchMax，此数组的大小不会超过指定值。

注意这些回调的方法签名不同于常规 ScrollTrigger，后者仅接收 ScrollTrigger 实例本身作为唯一参数。因此，批量回调的参数是两个数组。还需注意的是，onRefreshInit是唯一使用标准 ScrollTrigger 回调签名的回调（没有被批量处理），因为 "refreshInit" 事件的本质依赖于它立即执行，此外，它还允许您返回一个gsap.set()调用来仅在刷新期间重置某些状态，以便定位计算基于该状态进行，刷新完成后它会自动恢复该 gsap.set()，所以对onRefreshInit调用进行批量处理是没有意义的。

配置（Configuration）​

这个vars对象可以包含任意标准的 ScrollTrigger 配置属性，如 start、end、once 等，除了直接与动画相关的属性（animation, invalidateOnRefresh, onSnapComplete, onScrubComplete, scrub, snap, toggleActions）trigger（因为目标就是触发器）。另外，它还识别两个额外的可选属性：

• batchMax [Integer | Function]- 每个批次中允许的最大元素数量。当一个批次满时，它将立即触发其回调并开始收集下一个批次；如果新批次也立刻满了，它也将立即触发。例如，如果您设置batchMax: 3并且随后有 9 个元素大致同时进入视口，则会创建 3 个批次，因此 onEnter 回调将在短时间内连续触发 3 次（不等待时间间隔结束）。如果您有一个响应式布局，可能在页面调整大小时需要更改 batchMax 的值，则可以使用一个函数替代，返回一个整数。每次 ScrollTrigger 触发 "refresh"（当视口调整大小、非活动标签变为活动等时）时都会调用该函数。比如batchMax: () => { ...your logic here... return integer }
• interval [数字]- 收集每个批次的最大时间（以秒为单位）。当某一类型的回调被调用后，计时器开始，当经过这段时间或达到batchMax最大数量（batchMax）时，批次完成（哪个条件先满足即生效）。

简单示例​

ScrollTrigger.batch(".box", {
  onEnter: (elements, triggers) => {
    gsap.to(elements, { opacity: 1, stagger: 0.15 });
    console.log(elements.length, "elements entered");
  },
  onLeave: (elements, triggers) => {
    gsap.to(elements, { opacity: 0, stagger: 0.15 });
    console.log(elements.length, "elements left");
  },
});

高级示例​

gsap.set(".box", {y: 100});

ScrollTrigger.batch(".box", {
  interval: 0.1, // time window (in seconds) for batching to occur.
  batchMax: 3,   // maximum batch size (targets). Can be function-based for dynamic values
  onEnter: batch => gsap.to(batch, {opacity: 1, y: 0, stagger: {each: 0.15, grid: [1, 3]}, overwrite: true}),
  onLeave: batch => gsap.set(batch, {opacity: 0, y: -100, overwrite: true}),
  onEnterBack: batch => gsap.to(batch, {opacity: 1, y: 0, stagger: 0.15, overwrite: true}),
  onLeaveBack: batch => gsap.set(batch, {opacity: 0, y: 100, overwrite: true}),
  // you can also define most normal ScrollTrigger values like start, end, etc.
  start: "20px bottom",
  end: "top top"
});

// when ScrollTrigger does a refresh(), it maps all the positioning data which
// factors in transforms, but in this example we're initially setting all the ".box"
// elements to a "y" of 100 solely for the animation in which would throw off the normal
// positioning, so we use a "refreshInit" listener to reset the y temporarily. When we
// return a gsap.set() in the listener, it'll automatically revert it after the refresh()!
ScrollTrigger.addEventListener("refreshInit", () => gsap.set(".box", {y: 0}));

简单示例​

高级示例​