ArkUI Web에서 스크롤 감지: onScroll와 onOverScroll를 활용한 전역 스크롤 및 하단 감지

Source: Dev.to

Requirement Description

ArkUI Web 컴포넌트 내부에 렌더링된 페이지의 스크롤 방향 및 위치를 감지하는 방법을 제공하십시오:

• 위/아래 스크롤을 감지합니다.
• 페이지가 맨 위 또는 맨 아래에 도달했을 때를 감지합니다.

Background Knowledge

• Web.onScroll – 전체 페이지 스크롤 위치를 알려줍니다. 페이지 내부의 로컬(요소 수준) 스크롤에 대해서는 발생하지 않습니다.
  팁: 전체 스크롤을 확인하려면 스크롤 전후의 window.pageYOffset / window.pageXOffset 값을 비교하세요.

• Scroll.onWillScroll – ArkUI Scroll의 사전 스크롤 콜백(ArkUI 스크롤 컨테이너용, Web용이 아님).
  Docs:

• Web.onOverScroll – 위/아래(또는 좌/우) 오버스크롤을 감지합니다. “끝에 도달”했음을 추론하는 데 유용합니다.

Implementation Steps

1. Web 컴포넌트에서 스크롤 이벤트를 활성화하고 전체 페이지 스크롤 감지를 위해 onScroll을 등록합니다.
2. 이전 오프셋을 유지하여 event.yOffset을 비교함으로써 방향(위 vs. 아래)을 추론합니다.
3. **onOverScroll**을 사용해 맨 위(yOffset < 0)와 맨 아래(yOffset > 0) 오버스크롤 상태를 판단합니다.
4. (선택 사항) H5 페이지가 로컬 스크롤 컨테이너(전체가 아닌)를 사용한다면, 작은 JS 브리지나 H5 레이아웃을 조정해 전체 스크롤이 가능하도록 해야 합니다. Web.onScroll은 로컬 스크롤 변화를 받지 못합니다.

Code Snippet / Configuration

Detect global scroll direction with 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');
          }
        });
    }
  }
}

Note: Web.onScroll only reports global scroll. If the site uses an inner scrollable div (local scroll), onScroll won’t fire. For such cases, adjust the page to scroll the window (global) or implement an in‑page JS listener posting messages back to ArkUI via the web controller/JS bridge.

Test Results

• 연속된 yOffset 값을 비교함으로써 위/아래 방향이 올바르게 로그됩니다.
• onOverScroll은 맨 위(yOffset < 0)와 맨 아래(yOffset > 0) 오버스크롤을 안정적으로 보고합니다.

Limitations or Considerations

• H5 내부의 로컬 스크롤 컨테이너는 Web.onScroll을 트리거하지 않습니다. 전체 스크롤로 전환하거나 JS 브리지를 고려하세요.
• 크로스‑사이트 페이지는 삽입된 JS를 제한할 수 있으므로, 가능하면 H5 팀과 협업하는 것이 좋습니다.
• 웨어러블 환경: 로그와 부수 효과를 최소화하고, 스크롤 콜백에서 무거운 작업을 피하세요. 고대비 UI와 레이아웃 지연을 최소화해야 합니다.

Related Documents or Links

• Scroll.onWillScroll (ArkUI container)