ScrollMonitor：JavaScript滚动监控库的完整指南 - 如何高效监听元素进入视口

ScrollMonitor：JavaScript滚动监控库的完整指南 - 如何高效监听元素进入视口

【免费下载链接】scrollmonitorA simple and fast API to monitor elements as you scroll项目地址: https://gitcode.com/gh_mirrors/sc/scrollmonitor

ScrollMonitor 是一款轻量级且功能强大的 JavaScript 滚动监控库，它提供了简单快速的 API 来监控元素在滚动过程中的状态变化。无论是实现导航栏吸顶、内容懒加载还是视差滚动效果，ScrollMonitor 都能帮助开发者轻松实现元素与滚动行为的交互逻辑。

📌 核心功能与优势

ScrollMonitor 的核心价值在于其直观的 API 设计和高效的性能表现：

• 实时状态监测：精确追踪元素是否在视口内、进入视口或离开视口
• 灵活的偏移配置：支持自定义元素进入/离开视口的触发阈值
• 轻量级设计：源码仅包含 src/container.ts 和 src/watcher.ts 两个核心文件
• 无依赖：纯原生 JavaScript 实现，可与任何框架配合使用

🚀 快速开始

安装方式

通过 npm 安装：

npm install scrollmonitor

或直接克隆仓库：

git clone https://gitcode.com/gh_mirrors/sc/scrollmonitor

基础使用示例

创建一个滚动监控实例并监听元素：

// 创建监控容器 const container = scrollMonitor.createContainer(document.body); // 监控指定元素 const elementWatcher = container.create(element, { top: 100, // 顶部偏移量 bottom: 200 // 底部偏移量 }); // 状态变化时触发回调 elementWatcher.stateChange(() => { if (elementWatcher.isInViewport) { console.log('元素进入视口'); } else { console.log('元素离开视口'); } });

💡 实用场景案例

1. 导航栏吸顶效果

在 demos/list.html 示例中，ScrollMonitor 被用于实现滚动时的导航栏吸顶效果：

$('section').each(function(index, section) { // 创建监控实例 const sectionWatcher = scrollMonitor.create(section); // 设置底部偏移量（排除标题高度） const sectionMinusBottomHeadline = scrollMonitor.create(section, { bottom: -1 * h2Height }); // 根据滚动状态切换样式 sectionMinusBottomHeadline.stateChange(function() { if (sectionMinusBottomHeadline.isInViewport && sectionMinusBottomHeadline.isAboveViewport) { section.className = 'fixed'; // 固定定位 } else if (sectionMinusBottomHeadline.isAboveViewport) { section.className = 'bottom'; // 底部定位 } else { section.className = ''; // 恢复默认 } }); });

2. 内容懒加载

利用元素进入视口的事件触发图片加载：

const imageWatcher = scrollMonitor.create(imageElement); imageWatcher.enterViewport(() => { // 加载图片 imageElement.src = imageElement.dataset.src; // 只触发一次 imageWatcher.destroy(); });

3. 滚动动画触发

监控元素进入视口后执行动画效果：

const animationWatcher = scrollMonitor.create(animatedElement, { top: 50 // 元素顶部距离视口顶部50px时触发 }); animationWatcher.enterViewport(() => { animatedElement.classList.add('animate-in'); });

📚 API 参考

ScrollMonitorContainer 类

• create(element, options)：创建元素监控器
  • 参数：element(HTMLElement) - 要监控的元素
  • 参数：options(Object) - 可选配置，包含top、bottom、left、right偏移量
  • 返回：ScrollMonitorContainer实例

监控器实例属性

• isInViewport：元素是否在视口内
• isAboveViewport：元素是否在视口上方
• isBelowViewport：元素是否在视口下方
• top：元素顶部相对于视口顶部的位置

监控器实例方法

• stateChange(callback)：状态变化时触发回调
• enterViewport(callback)：元素进入视口时触发回调
• exitViewport(callback)：元素离开视口时触发回调
• destroy()：销毁监控器，释放资源

🧪 测试与演示

项目提供了多个演示案例，展示不同场景下的应用：

• demos/list.html：长列表滚动时的导航栏定位
• demos/fixed.html：固定元素的滚动监控
• demos/stress.html：性能压力测试
• demos/scoreboard.html：计分板滚动效果

要运行演示，只需在浏览器中打开相应的 HTML 文件即可。

🔧 高级配置

自定义监控容器

默认情况下，ScrollMonitor 使用document.body作为监控容器，你也可以创建自定义容器：

const customContainer = new ScrollMonitorContainer(document.getElementById('custom-container')); const elementWatcher = customContainer.create(element);

批量监控元素

通过 NodeList 或元素数组一次性监控多个元素：

const elements = document.querySelectorAll('.item'); const watchers = scrollMonitor.create(elements); watchers.forEach(watcher => { watcher.enterViewport(() => { watcher.element.classList.add('visible'); }); });

📝 总结

ScrollMonitor 凭借其简洁的 API 和高效的性能，成为实现滚动交互效果的理想选择。无论是简单的元素可见性检测，还是复杂的滚动动画控制，它都能提供可靠的支持。通过 src/container.ts 和 src/watcher.ts 两个核心文件的精妙设计，ScrollMonitor 实现了功能与体积的完美平衡。

如果你正在寻找一个轻量级、无依赖的滚动监控解决方案，ScrollMonitor 绝对值得尝试！

【免费下载链接】scrollmonitorA simple and fast API to monitor elements as you scroll项目地址: https://gitcode.com/gh_mirrors/sc/scrollmonitor