spz-animation 动画

通过 CSS 类驱动的动画控制器，支持可见区域、滚动、点击、鼠标移动及手动触发等多种触发方式

布局

logic

何时使用

需要在元素进入视口时自动播放入场动画，提升页面视觉层次感。
需要通过按钮或其他元素手动触发某个目标元素的动画效果。
需要根据页面滚动位置实时更新动画变量，实现视差或进度动效。

代码演示

基本用法

设置 trigger="visible" 与 animation-class，当目标元素进入视口时自动播放 CSS 动画。

动画元素

<spz-animation
  id="spz-animation-base"
  layout="logic"
  trigger="visible"
  target=".anim-box"
  animation-class="fade-in-up"
></spz-animation>

<div class="anim-demo-wrap">
  <div class="anim-box">动画元素</div>
</div>

使用方法手动触发动画

设置 trigger="manual"，通过调用 run 方法手动触发目标元素的动画。动画播放结束后会触发 finish 事件。

动画元素

点击按钮触发动画

<spz-animation
  id="spz-animation-api"
  layout="logic"
  trigger="manual"
  new-target=".anim-api-box"
  animation-class="bounce"
  @finish="anim-finish-tip.removeAttribute(hidden);anim-idle-tip.setAttribute(hidden,'')"
></spz-animation>

<div class="anim-api-wrap">
  <div class="anim-api-box">动画元素</div>

  <div class="demo-buttons">
    <button @tap="spz-animation-api.run()">执行动画</button>
  </div>

  <div class="anim-status">
    <span id="anim-idle-tip">点击按钮触发动画</span>
    <span id="anim-finish-tip" hidden>动画已完成 ✓</span>
  </div>
</div>

列表顺序动画

配合 set-order 属性，为多个目标元素自动注入 --spzanim-order CSS 变量，可在 CSS 中用于设置 animation-delay 实现错落播放。

卡片一：进入视口时触发动画

卡片二：依次延迟播放

卡片三：通过 set-order 控制顺序

<spz-animation
  id="spz-animation-scroll"
  layout="logic"
  trigger="visible"
  target=".scroll-card"
  animation-class="slide-in"
  set-order
></spz-animation>

<div class="scroll-demo-wrap">
  <div class="scroll-demo-list">
    <div class="scroll-card">
      <div class="scroll-card-icon"></div>
      <div class="scroll-card-text">卡片一：进入视口时触发动画</div>
    </div>
    <div class="scroll-card">
      <div class="scroll-card-icon"></div>
      <div class="scroll-card-text">卡片二：依次延迟播放</div>
    </div>
    <div class="scroll-card">
      <div class="scroll-card-icon"></div>
      <div class="scroll-card-text">卡片三：通过 set-order 控制顺序</div>
    </div>
  </div>
</div>

属性

属性名	说明	类型	默认值	是否必需
trigger	触发方式，可选值：`visible`（进入视口）、`scroll`（滚动）、`click`（点击）、`mousemove`（鼠标移动）、`manual`（手动调用 `run`），多个值用逗号分隔	string	-	否
target	动画目标元素的 CSS 选择器，多个选择器用逗号分隔	string	-	否
animation-class	要添加到目标元素的 CSS 动画类名	string	-	否
once	仅对 `trigger="visible"` 有效，若存在则动画仅触发一次，动画结束后自动移除动画类	-	-	否
ignore-initial	仅对 `trigger="visible"` 有效，若存在则忽略首次进入视口（即页面加载时已在视口内的元素不触发动画）	-	-	否
set-order	若存在，则自动为每个目标元素注入 `--spzanim-order` CSS 变量（从 0 开始的索引），可用于错落延迟动画	-	-	否
order-root	配合 `set-order` 使用，指定分组根元素的 CSS 选择器，每个根元素内的目标元素独立计数	string	-	否
style-variables	`trigger="manual"` 时传递的初始 CSS 变量配置，JSON 对象格式字符串，键为 CSS 变量名（以 `--` 开头）	string	-	否
event-root	`trigger="click"` 或 `trigger="mousemove"` 时，事件监听根元素的 CSS 选择器；未设置则监听 `document`	string	-	否
new-target	若存在，则每次调用 `run` 方法时动态创建一个新目标元素来执行动画，而非操作已有元素	-	-	否
new-target-root	配合 `new-target` 使用，指定动态创建元素的挂载容器选择器；未设置则挂载到 `document.body`	string	-	否

方法

run

手动触发动画。需要配合 trigger="manual" 或将 new-target 属性设置在 spz-animation 上使用。动画播放结束后会触发 finish 事件，并将 args 数据作为事件数据传递。

参数	说明	类型	默认值	是否必须
textContent	动态更新目标元素的文本内容，支持 `${key}` 占位符替换	string	-	否
`--*`	以 `--` 开头的任意参数名均作为 CSS 变量注入目标元素	string	-	否

事件

finish

动画播放结束时触发。trigger="visible" 且配合 once 属性时，动画类移除后触发；trigger="manual" 时，每次 run 执行结束后触发。

属性	说明	类型
args	调用 `run` 方法时传入的参数对象	object