Cuttlefish Docs
  • 简体中文

    • spz-interact-observer

    何时使用

    spz-interact-observer 监听滚动或鼠标移动交互，并将 CSS 变换效果（视差、吸顶定位、悬停 3D 等）应用到目标元素上。

    适用场景：

    • 创建视差滚动效果（平移、缩放）
    • 实现可堆叠的吸顶 / 吸底栏
    • 在鼠标悬停时添加 3D 倾斜效果
    • 根据滚动距离切换元素的显示/隐藏

    支持布局

    • 支持所有布局

    使用方式

    <!-- 视差：随用户滚动平移目标 -->
<spz-interact-observer
  target-id="hero-image"
  from="translateY:0"
  to="translateY:-100"
  smoothness="20"
  layout="nodisplay">
</spz-interact-observer>

    代码演示

    滚动视差

    <div id="parallax-target">我随滚动移动</div>
<spz-interact-observer
  target-id="parallax-target"
  from="translateY:0;scaleX:1"
  to="translateY:-80;scaleX:1.1"
  smoothness="25"
  layout="nodisplay">
</spz-interact-observer>

    吸顶定位

    <div id="sticky-bar">吸顶栏</div>
<spz-interact-observer
  target-id="sticky-bar"
  to="position:top"
  layout="nodisplay">
</spz-interact-observer>

    依赖另一个吸顶元素

    <div id="primary-header" style="position:sticky;top:0;">顶部导航</div>
<div id="sub-nav">子导航</div>
<spz-interact-observer
  target-id="sub-nav"
  observe-id="primary-header"
  to="position:top"
  layout="nodisplay">
</spz-interact-observer>

    鼠标悬停 3D 倾斜

    <div id="card">悬停我</div>
<spz-interact-observer
  target-id="card"
  interact="mousemove"
  to="rotateX:15;rotateY:15"
  layout="nodisplay">
</spz-interact-observer>

    滚动距离切换（显示/隐藏元素）

    当 from 和 to 不是变换属性而是 元素ID.属性名 对时，组件会根据滚动距离切换这些元素的布尔属性。

    <div id="list">主内容</div>
<div id="list1" hidden>替代内容</div>
<spz-interact-observer
  target-id="list"
  from="list.show;list1.hide"
  to="list.hide;list1.show"
  layout="container">
</spz-interact-observer>

    属性

    属性名说明类型是否必需
    target-id要观察和/或应用变换的目标元素 IDstring是
    interact交互类型。scroll（默认）或 mousemovestring否
    from起始变换属性，分号分隔。示例：translateY:0;scaleX:1。在滚动距离模式下接受 元素ID.属性 对string否
    to结束变换属性，分号分隔。示例：translateY:-100;scaleX:1.2。特殊值 position:top 或 position:bottom 启用吸顶/吸底模式string否
    smoothness插值平滑系数，越大过渡越慢。默认：30number否
    distance滚动距离切换模式的阈值（像素）。默认为目标元素的 clientHeightnumber否
    observe-id用于吸顶堆叠的观察元素 ID。目标元素的位置会根据此元素调整string否
    rely-idobserve-id 的别名，用于依赖定位string否
    rely-sticky存在时，仅在被依赖元素确实处于 sticky 或 fixed 状态时才应用位置调整boolean否
    entry-show存在时，元素在首次进入时即可见（在第一次滚动检查之前）boolean否

    支持的变换属性

    translateX、translateY、translateZ、scaleX、scaleY、rotateX、rotateY、rotateZ

    Actions

    change

    根据 observe-id / rely-id 元素重新计算位置。适用于被观察元素尺寸动态变化的场景。

    示例：

    <button @tap="observer.change">重新计算</button>

    工作原理

    1. 视差模式 — 当 from 和 to 都包含变换属性（如 translateY、scaleX）时，组件会在元素滚动经过视口时对它们进行插值计算。
    2. 吸顶模式 — 当 to 包含 position:top 或 position:bottom 时，组件管理吸顶可见性并与其他吸顶元素堆叠。
    3. 依赖/观察模式 — 设置 observe-id 或 rely-id 时，目标元素的 top/bottom 偏移会根据被观察元素的高度和吸顶状态调整。
    4. 滚动距离模式 — 当 from/to 不是变换属性时，组件根据滚动距离切换引用元素上的布尔属性。
    5. 鼠标移动模式 — 当 interact="mousemove" 时，组件根据光标在目标元素内的位置应用 3D 旋转和平移。

    注意事项

    • 该组件不派发自定义事件。
    • 在鼠标移动模式下，鼠标移出时变换会重置为 none。
    • 在底部吸顶模式下会自动应用 iOS Safari 底部栏补偿。