Cuttlefish Docs
  • 简体中文

    • spz-animation

    何时使用

    spz-animation 在各种触发条件下（视口可见、滚动、点击、鼠标移动或手动调用）为一个或多个目标元素应用 CSS 类。

    适用场景：

    • 元素滚动进入视口时播放入场动画
    • 通过 CSS 变量跟踪滚动位置，实现滚动联动效果
    • 点击或悬停时触发动画
    • 使用排序功能协调多个目标的交错动画

    支持布局

    • logic

    代码演示

    滚动进入视口时淡入

    <spz-animation
  layout="logic"
  trigger="visible"
  target=".card"
  animation-class="fade-in"
  once>
</spz-animation>

    滚动联动 CSS 变量

    <spz-animation
  layout="logic"
  trigger="scroll"
  target="#parallax"
  animation-class="scroll-active">
</spz-animation>

    目标元素会收到 CSS 变量 --spzanim-scroll-rect-top，可在 CSS 中使用该变量驱动滚动联动效果。

    点击触发

    <spz-animation
  layout="logic"
  trigger="click"
  target="#ripple"
  animation-class="ripple-active"
  event-root="#button-area">
</spz-animation>

    手动触发

    <spz-animation
  id="my-anim"
  layout="logic"
  trigger="manual"
  target=".box"
  animation-class="highlight">
</spz-animation>
<button @tap="my-anim.run">执行动画</button>

    排序入场

    <spz-animation
  layout="logic"
  trigger="visible"
  target=".list-item"
  animation-class="slide-up"
  set-order
  once>
</spz-animation>

    每个 .list-item 会收到 CSS 变量 --spzanim-order（0, 1, 2, ...），可在 animation-delay 中使用实现交错入场。

    属性

    属性名说明类型是否必需
    trigger逗号分隔的触发类型：visible、manual、scroll、click、mousemovestring否
    target逗号分隔的目标元素 CSS 选择器string否
    animation-class触发动画时应用的 CSS 类名string否
    new-target存在时动态创建新的目标元素boolean否
    new-target-root新目标元素追加到的根容器 CSS 选择器string否
    once存在时动画仅运行一次（用于 visible 触发）boolean否
    ignore-initial存在时忽略初始交叉检查（用于 visible 触发）boolean否
    set-order存在时通过 --spzanim-order 为每个目标设置排序索引boolean否
    order-root计算排序时使用的根元素 CSS 选择器string否
    style-variables设置到目标上的 CSS 变量 JSON 字符串string否
    event-root事件监听根元素的 CSS 选择器（用于 click / mousemove 触发）string否

    CSS 变量

    组件根据触发类型在目标元素上设置以下 CSS 变量：

    变量名触发类型说明
    --spzanim-ordervisible（配合 set-order）目标的排序索引（0, 1, 2, ...）
    --spzanim-scroll-rect-topscroll目标相对于视口的滚动位置
    --spzanim-click-xclick点击 X 坐标（相对视口）
    --spzanim-click-yclick点击 Y 坐标（相对视口）
    --spzanim-mousemove-xmousemove鼠标 X 坐标（相对视口）
    --spzanim-mousemove-ymousemove鼠标 Y 坐标（相对视口）

    Actions

    run

    手动触发动画。通常与 trigger="manual" 配合使用。

    示例：

    <button @tap="my-anim.run">触发</button>

    Events

    事件名说明
    finish动画结束时触发（通过目标元素的 animationend 监听）

    注意事项

    • animation-class 在触发时添加，动画结束后移除（除非 visible 配合 once 使用）。
    • style-variables 支持 ${elementId} 和 $(selector) 元素引用，用于动态计算值。