跳转到正文

选择器

默认情况下,Glaze 会查找带有 data-animate 属性的元素,并根据该属性的值构建动画。本页介绍三个用于更改 Glaze 读取哪些元素的选项:dataAttribute、className 和 element,以及用于将动画指向其他元素的方括号选择器。字符串中的实用工具详见语法。

如何查找元素

glaze() 运行时,以及每次 refresh() 或监听模式重建时,都会遍历根元素内的所有元素,并保留带有已配置属性的元素,或者在类模式下保留带有已配置前缀类的元素。如果根元素本身带有相应属性或类,它也会被计入。元素按文档顺序读取。

以这种方式找到的每个元素都会获得自己的时间线,除非它位于 tl 元素内,或通过 tl:<id> 链接到该元素。在这种情况下,它会被添加到该时间线中。有关分组方式,请参阅时间线。

自定义属性

使用其他数据属性:

JavaScript
glaze({
  lib: { gsap: { core: gsap } },
  dataAttribute: "data-move",
})

现在 Glaze 会查找 data-move,而不是 data-animate:

HTML
<div data-move="from:opacity-0"></div>

该选项会替换属性,而不是添加属性。使用上面的设置时,仍带有 data-animate 的元素会被忽略。如果页面上的其他脚本已经读取 data-animate,或者你希望标记使用与你的项目一致的属性名称,请使用此选项。

在 监视模式下,Glaze 会监视配置的属性,因此更改元素上 data-move 的值会触发重建。

基于类的语法

相比数据属性,你更喜欢使用类吗?启用类模式:

JavaScript
glaze({
  lib: { gsap: { core: gsap } },
  className: "animate",
})

现在你可以将动画写成类:

HTML
<div class="animate-from:opacity-0|duration-1"></div>

如果你已经在使用实用类优先的 CSS,并希望动画风格与之相似,这种方式就很合适。如果模板系统允许你为元素添加类,却不允许添加任意属性,类模式也很实用。

Glaze 会读取所有以此前缀加连字符开头的类(此处为 animate-),并移除此前缀。没有此前缀的类会保留,因此动画类可以与样式类并列应用于同一元素。你可以将一个动画拆分到多个类中:

HTML
<div class="card animate-from:opacity-0 animate-from:y-24"></div>

响应式类允许将断点放在前缀之后或之前。只有 lg 与 断点匹配时,这两种写法才会生效:

HTML
<div class="animate-@lg:from:opacity-0"></div>
<div class="@lg:animate-from:opacity-0"></div>

预设在类中的用法相同,例如 animate-preset-fadeIn。

类模式不会关闭数据属性。元素同时包含两者时,Glaze 会将它们合并为一个字符串:先放属性值,再按前缀类在 class 属性中的顺序排列。

HTML
<div
  class="animate-from:opacity-0 animate-@lg:from:y-50"
  data-animate="from:duration-1"
></div>

此元素在任何尺寸下都会在一秒内从 opacity: 0 开始动画;当 lg 匹配时,还会从 y: 50 开始动画。由于这些字符串会合并,因此适用与单个字符串相同的规则:当两部分设置了相同属性时,后面的部分优先。此处,类值会覆盖属性值中的 x:

HTML
<div class="animate-to:x-100" data-animate="to:x-50|y-20"></div>

此元素会动画到 x: 100 和 y: 20。

在 class 模式下启用 watch 后,Glaze 也会监听 class 的变化。为元素添加 animate- 类,或更改 Glaze 正在读取或播放动画的元素的类,都会安排重建。在带有相对选择器的元素内部,其后代元素的类发生变化时也会触发重建,因为这可能改变选择器的匹配结果。其他元素的类发生变化则不会触发重建,其中也包括动画元素的祖先元素,因此切换 <html> 上的深色模式类或 <body> 上的滚动锁定类,不会影响正在运行的动画。类变化若使某个元素新匹配全局选择器,也不会被检测到;请在此之后调用 refresh()。

默认情况下,Glaze 会搜索整个 document。传入 element 可仅为容器内的元素制作动画:

JavaScript
glaze({
  lib: { gsap: { core: gsap } },
  element: document.querySelector("#app"),
})

element 接受一个 Element 或一个 Document。它会限制以下三项:

  • 只会扫描根元素及其后代中的动画实用类。页面其他位置的元素会被忽略,即使它们带有 data-animate 也是如此。
  • 监视模式只会监视根元素内部的变更。
  • destroy() 只会清理此实例创建的内容,因此页面的其他部分会保留其动画。

因此,在组件框架中,element 是首选项。每个已挂载的组件都使用其根元素创建一个实例,并在组件卸载时调用 destroy(),如刷新与清理中所示。为不同实例指定互不重叠的根元素;位于两个根元素内的元素会同时由两个实例制作动画。

指定其他元素

上面的选项决定 Glaze 会读取哪些元素。片段开头的方括号选择器决定将动画应用于哪些元素。若没有选择器,动画会应用于带有这些实用类的元素。

相对选择器

以 & 开头的选择器会从元素自身开始解析,其中 & 代表该元素。它通过 querySelectorAll 查询,因此可以匹配多个元素:

HTML
<ul data-animate="[&>li]:from:opacity-0|y-20|stagger-0.1">
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
</ul>

[&>li] 会匹配直接的 li 子元素。stagger 值会让它们的开始时间间隔 0.1 秒。若要让一个元素控制列表、网格或一组子元素的动画,而不必为每个子元素添加属性,请使用此方式。

用下划线表示空格。[&_p] 会变成 & p,并匹配元素内任意深度的所有 p:

HTML
<article data-animate="[&_p]:from:opacity-0|stagger-0.2">
  <p>First paragraph</p>
  <div><p>Nested paragraph</p></div>
</article>

选择器中的每个下划线都会转换为空格,因此无法通过这种方式匹配名称中带有下划线的类。

单独使用 [&] 时会解析为元素自身。它主要用作值,例如在 中使用 scrollTrigger.trigger-[&]ScrollTrigger,以及在时间线 默认值中使用。

全局选择器

不带 & 的选择器会作为字符串传递给动画引擎。GSAP 和 Motion 都会在整个文档中解析该选择器,而不是相对于元素或 element 根元素解析:

HTML
<h2 data-animate="[.badge]:from:opacity-0|scale-0.5|duration-0.3">Inbox</h2>
<span class="badge">3</span>

这会为页面上的每个 .badge 制作动画,无论它位于何处。在可复用组件中优先使用相对选择器,因为全局选择器也会匹配页面其他位置的组件副本。

限制

每个元素只能有一个目标。当多个片段带有选择器时,最后一个选择器会应用于该元素的所有状态。此处,from 和 to 都会应用于 p,而不是 h1:

HTML
<div data-animate="[&>h1]:from:opacity-0 [&>p]:to:x-20">
  <h1>Title</h1>
  <p>Text</p>
</div>

若要让两个组分别执行不同动画,请将实用类放在子元素本身上,或将它们分组到一个 时间线中。

选择器会在第一个 ] 处结束,因此不支持包含方括号的选择器,例如属性选择器 [&>[data-item]]。请改用类选择器或元素选择器。

选择器与断点的组合顺序遵循语法中的说明,例如 @lg:[&>div]:from:opacity-0。