vue-scrollama 是一个专为 Vue 3 开发的滚动驱动交互（Scrollytelling）工具库，它通过封装原生的 Scrollama 框架，让开发者能够以组合式 API 或组件化的方式，轻松在网页中实现随滚动触发的动画和叙事效果。

核心功能

vue-scrollama 提供了灵活的配置选项，其核心功能涵盖了滚动交互的各个生命周期。

1. 支持双重 API 模式：开发者可以选择使用更具声明性的 <Scrollama> 组件，或者使用更具控制力的 useScrollama 组合式函数。
2. 精确的状态追踪，能够捕捉进入（Enter）、离开（Exit）以及实时滚动进度（Progress）等事件。
3. 内置自动尺寸调整功能，能感应窗口或容器的大小变化并自动重绘。
4. 对于使用 Nuxt 或 VitePress 的开发者，它也提供了良好的 SSR/服务端渲染兼容性。

插件安装

要使用最新版的 vue-scrollama，你需要确保 Node.js 版本不低于 20，且 Vue 版本在 3.5.0 以上。你可以通过 npm 或 pnpm 进行安装：

npm add vue-scrollama

组件式 API 示例

组件式 API 是最简单的上手方式，你只需要将滚动步骤作为 <Scrollama> 的直接子元素即可。这种方式会自动处理组件的挂载与销毁逻辑。

<template>
  <Scrollama
    :offset="0.5"
    @step-enter="onStepEnter"
    @step-progress="onStepProgress"
  >
    <!-- 每一个直接子元素都会被视为一个“步骤” -->
    <div v-for="n in 3" :key="n" :data-step="n" class="step">
      <p>这是第 {{ n }} 个滚动步骤</p>
    </div>
  </Scrollama>
</template>
<script setup>
import Scrollama from "vue-scrollama";

function onStepEnter({ element, index, direction }) {
  console.log("进入步骤:", index, "方向:", direction);
  // element 是当前的 DOM 元素，可以根据 data-step 执行特定逻辑
}

function onStepProgress({ element, index, progress }) {
  // progress 是 0 到 1 之间的数值，代表当前步骤在视图中的滚动百分比
  console.log(`步骤 ${index} 进度: ${progress}`);
}
</script>
<style scoped>
.step {
  margin: 50vh 0;
  height: 300px;
  background: #f0f0f0;
  display: flex;
  align-items: center;
  justify-content: center;
}
</style>

进阶用法：组合式 API

如果你需要更细粒度的控制，例如在特定的 DOM 容器内初始化，或者需要手动触发重构（Rebuild），可以使用 useScrollama。

<script setup>
import { ref } from "vue";
import { useScrollama } from "vue-scrollama";

const container = ref(null);

const { isReady, rebuild } = useScrollama({
  container,
  stepSelector: ".my-step",
  offset: 0.3,
  onStepEnter: ({ index }) => {
    console.log("当前激活步骤:", index);
  },
});
</script>
<template>
  <div ref="container" class="scrolly-container">
    <div class="my-step">步骤 A</div>
    <div class="my-step">步骤 B</div>
  </div>
</template>

在 Nuxt / SSR 环境中使用

由于滚动交互高度依赖浏览器端的 DOM API（如 Intersection Observer），在服务端渲染环境中，必须将滚动组件包裹在 <ClientOnly> 标签内。这可以防止在服务器端尝试访问 window 或 document 对象，从而避免水合（Hydration）错误。 GitHub^[1]

<template>
  <ClientOnly>
    <ScrollamaStory />
  </ClientOnly>
</template>

工具地址：https://vue-scrollama.pages.dev/^[2]

References

1. GitHub: https://github.com/vgshenoy/vue-scrollama
2. https://vue-scrollama.pages.dev/: https://vue-scrollama.pages.dev/