在 ArkUI Web 中监听滚动：使用 onScroll 与 onOverScroll 实现全局滚动和底部检测

Source: Dev.to

需求描述

提供一种方式来检测在 ArkUI Web 组件内部渲染的页面的 滚动方向和位置：

• 检测 向上/向下 滚动。
• 检测页面何时到达 顶部 或 底部。

背景知识

• Web.onScroll – 通知 全局页面 的滚动位置。它不会在页面内部的 局部（元素级） 滚动时触发。
  提示： 要确认是全局滚动，可比较滚动前后的 window.pageYOffset / window.pageXOffset。

• Scroll.onWillScroll – ArkUI Scroll 的预滚动回调（用于 ArkUI 滚动容器，不适用于 Web）。
  文档：

• Web.onOverScroll – 检测 顶部/底部（或 左侧/右侧）的超滚动，可用于推断“已到达末端”。

实现步骤

1. 在 Web 组件上开启滚动事件并注册 onScroll，用于 全局 页面滚动检测。
2. 保持一个 上一次的偏移量，通过比较 event.yOffset 来推断 方向（向上还是向下）。
3. 使用 onOverScroll 来判断 顶部（yOffset < 0）或 底部（yOffset > 0）的超滚动状态。
4. （可选） 如果你的 H5 页面使用 局部滚动容器（而非全局滚动），考虑添加一个小的 JS 桥接或调整 H5 布局，使其能够进行 全局滚动，因为 Web.onScroll 不会收到局部滚动的变化。

代码片段 / 配置

使用 Web.onScroll 检测全局滚动方向

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebPage {
  controller: webview.WebviewController = new webview.WebviewController();
  // Track last global vertical offset
  private lastYOffset: number = 0;

  build() {
    Column() {
      Web({
        src: 'https://www.example.com',
        controller: this.controller
      })
        .javaScriptAccess(true)
        .domStorageAccess(true)
        .verticalScrollBarAccess(true)
        .onScroll((event) => {
          // event.yOffset is the page's GLOBAL vertical offset
          if (event.yOffset > this.lastYOffset) {
            console.info('Scrolling down');
          } else if (event.yOffset  {
          if (event.yOffset  0) {
            console.info('Reached bottom');
          }
        });
    }
  }
}

注意： Web.onScroll 只报告 全局 滚动。如果站点使用内部可滚动的 div（局部滚动），onScroll 将不会触发。针对这种情况，可将页面改为滚动 window（全局）或实现 页面内 JS 监听器，通过 Web 控制器/JS 桥将消息发送回 ArkUI。

测试结果

• 通过比较连续的 yOffset，能够正确记录上下滚动方向。
• onOverScroll 能可靠地报告顶部（yOffset < 0）和底部（yOffset > 0）的超滚动。

限制或注意事项

• 局部滚动容器 在 H5 中不会触发 Web.onScroll。请考虑全局滚动或使用 JS 桥接。
• 跨站页面可能限制注入的 JS；如有可能，最好与 H5 团队协作。
• 可穿戴设备：保持日志和副作用轻量，避免在滚动回调中执行耗时操作。确保高对比度 UI 并最小化布局卡顿。

相关文档或链接

• Scroll.onWillScroll (ArkUI 容器)