Intersect 插件

Alpine 的 Intersect 插件是 Intersection Observer 的便利封装，允许你轻松地响应元素进入视口的事件。

这对于以下场景非常有用：懒加载图片和其他内容、触发动画、无限滚动、记录内容的"查看"等。

安装

你可以通过 <script> 标签引入或通过 NPM 安装来使用此插件：

通过 CDN

你可以将此插件的 CDN 构建版本作为 <script> 标签引入，只需确保在 Alpine 核心 JS 文件之前引入。

<!-- Alpine 插件 -->
<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/[email protected]/dist/cdn.min.js"></script>

<!-- Alpine 核心 -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

通过 NPM

你可以从 NPM 安装 Intersect 以在打包中使用：

npm install @alpinejs/intersect

然后从你的打包工具中初始化它：

import Alpine from 'alpinejs'
import intersect from '@alpinejs/intersect'

Alpine.plugin(intersect)

...

x-intersect

使用此插件的主要 API 是 x-intersect。你可以将 x-intersect 添加到 Alpine 组件中的任何元素，当该元素进入视口（通过滚动可见）时，提供的表达式将被执行。

例如，在以下代码片段中，shown 将保持 false，直到该元素被滚动到视口中。此时，表达式将执行，shown 将变为 true：

<div x-data="{ shown: false }" x-intersect="shown = true">
    <div x-show="shown" x-transition>
        I'm in the viewport!
    </div>
</div>

Scroll Down 👇

I'm in the viewport!

x-intersect:enter

:enter 后缀是 x-intersect 的别名，工作方式相同：

<div x-intersect:enter="shown = true">...</div>

你可以选择使用它以便在同时使用 :leave 后缀时更清晰。

x-intersect:leave

添加 :leave 可以在元素离开视口时执行你的表达式。

<div x-intersect:leave="shown = true">...</div>

默认情况下，这意味着整个元素不在视口中。使用 x-intersect:leave.full 可以在只有部分元素不在视口中时执行你的表达式。

修饰符

.once

有时只在元素首次进入视口时评估一次表达式很有用，而不是在后续每次进入时都触发。例如，在触发"进入"动画时。在这些情况下，你可以向 x-intersect 添加 .once 修饰符来实现。

<div x-intersect.once="shown = true">...</div>

.half

在交叉阈值超过 0.5 时评估表达式。

对于需要至少显示部分元素的场景很有用。

<div x-intersect.half="shown = true">...</div> // 当元素的 `0.5` 在视口中时

.full

在交叉阈值超过 0.99 时评估表达式。

对于需要显示整个元素的场景很有用。

<div x-intersect.full="shown = true">...</div> // 当元素的 `0.99` 在视口中时

.threshold

允许你控制底层 IntersectionObserver 的 threshold 属性：

该值应在 "0-100" 范围内。值为 "0" 表示：如果元素的任何部分进入视口就触发"交叉"（默认行为）。而值为 "100" 表示：除非整个元素进入视口，否则不触发"交叉"。

介于两者之间的任何值都是这两个极端的百分比。

例如，如果你希望在元素的一半进入页面后触发交叉，可以使用 .threshold.50：

<div x-intersect.threshold.50="shown = true">...</div> // 当元素的 50% 在视口中时

如果你希望仅在元素的 5% 进入视口时触发，可以使用 .threshold.05，以此类推。

.margin

允许你控制底层 IntersectionObserver 的 rootMargin 属性。这实际上调整了视口边界的大小。正值将边界扩展到视口之外，负值将其向内缩小。这些值的工作方式类似 CSS margin：一个值表示所有边；两个值表示上下、左右；或四个值表示上、右、下、左。你可以使用 px 和 % 值，或使用纯数字来获取像素值。

<div x-intersect.margin.200px="loaded = true">...</div> // 当元素在视口 200px 范围内时加载

<div x-intersect:leave.margin.10%.25px.25.25px="loaded = false">...</div> // 当元素距离视口顶部 10% 内或其他三边 25px 内时卸载

<div x-intersect.margin.-100px="visible = true">...</div> // 当元素进入视口超过 100 像素时标记为可见

.parent

默认情况下，x-intersect 针对浏览器视口观察元素。.parent 修饰符将底层 IntersectionObserver 的 root 设置为元素的父元素，因此表达式将基于元素是否在其父元素内可见（而不是整个页面）进行评估。

当元素位于可滚动容器内，或任何你关心相对于父元素的可见性而不是视口时，这非常方便。

<div x-intersect.parent="shown = true">...</div> // 当元素在其父元素内滚动到可见时标记为显示