[iOS] WKWebView에서의 스크롤∙Bounce∙SafeArea 동작

 

 

 

하이브리드 앱을 개발하다 보면 웹뷰에서 스크롤이 튀거나,
키보드가 올라올 때 레이아웃이 깨지거나,
iOS Safari와 다르게 동작하는 문제를 자주 맞닥뜨리게 된다.

특히 iOS의 WKWebView는 안드로이드 WebView, 브라우저 Safari와 동작 방식이 모두 달라서
기능 하나를 구현하는 데도 많은 주의가 필요하다.

이번 글에서는 WKWebView의 스크롤 동작과 관련해 가장 많이 발생하는 문제들을 정리하려고 한다.

 

 

 

WKWebView 스크롤의 기본 구조

 

webView.scrollView

- WKWebView 자체는 스크롤을 하지 않는다.
- 내부의 UIScrollView가 모든 스크롤∙바운스∙컨텐츠 inset 조정을 담당한다.
- 그래서 대부분의 스크롤 조작∙설정은 이 객체에 대해 이루어진다.

webView.scrollView.bounces = false
webView.scrollView.showsVerticalScrollIndicator = false

 

 

Safe Area와 스크롤 관계: iOS만의 특수 처리

iOS는 노치/홈 인디케이터 때문에 Safe Area가 존재한다.
그런데, WKWebView가 이 Safe Area와 상호작용하면서 의도치 않은 여백이나 튐 현상이 발생할 수 있다.
그래서 아래 속성은 반드시 이해하고 넘어가야한다.

webView.scrollView.contentInsetAdjustmentBehavior = .never

- .automatic: iOS가 Safe Area를 고려해서 자동 조절. 예상치 못한 여백 발생 가능
- .scollableAxes: 스크롤되는 방향만 자동 조절
- .never: Safe Area를 전혀 고려하지 않음
- .always: 무조건 Safe Area 반영

실무적으로 WKWebView에서는 거의 대부분 .never이 정답이다.
왜냐!
SPA 웹앱이 자체적으로 padding-top / padding-bottom을 관리하는 경우가 많기 때문에
중복 inset이 생겨 상단/하단이 밀린 레이아웃이 나타날 수 있기 때문이다.
그래서 WKWebView에서는 .never를 기본값으로 잡고 시작하는 것이 안전하다.

 

 

Overscroll Bounce 비활성화

iOS 웹뷰는 기본적으로
- 스크롤 상단을 당기면 아래로 늘어난다.
- 스크로 하단을 당기면 위로 늘어나는 bounce 효과를 가진다.

이 기능이 의도치 않은 화면 흔들림의 원인이 되기도 한다.

webView.scrollView.bounces = false
webView.scrollView.alwaysBounceVertical = false

근데 난 개인적으로 'bounces = true' 동작이 익숙한 느낌.. 많은 iOS 앱들이 허용해놓을 것 같다.

true, false든 아래 설정을 해주어야 항상 스크롤이 가능해진다.
즉, 이 설정을 해주어야 bounce 설정이 올바르게 반영된다.

webView.scrollView.isScrollEnabled = true

 

 

 

키보드가 올라올 때 스크롤 깨짐 현상

하이브리드 앱에서 가장 자주 발생하는 문제이다.
예를 들면,
- 키보드가 올라오면 웹이 갑자기 위로 튀어 오른다.
- input 클릭 시 content inset이 갑작스럽게 바뀐다.
- 스크롤 위치가 이상하게 이동한다.

위 현상들의 원인은 바로 iOS 키보드가 등장할 때 ScrollView의 SafeAreaInsets / contentInset을 자동으로 조정한다.
바로 여기서 WKWebView에서는 이 자동조정 때문에 웹 내부 레이아웃과 충돌하게 된다.

해결하는 방법은
첫 번째로는 앞서 이야기 한 '자동 inset 조정을 비활성화'하는 것이다.

webView.scrollView.contentInsetAdjustmentBehavior = .never

 

두 번째로는 키보드 알림을 직접 처리하는 것이다.
키보드가 올라갈 때 하단 inset을 직접 맞춰주는 방식이다.

NotificationCenter.default.addObserver(
    forName: UIResponder.keyboardWillChangeFrameNotification,
    object: nil,
    queue: .main
) { [weak self] notification in
    guard
        let info = notification.userInfo,
        let frame = info[UIResponder.keyboardFrameEndUserInfoKey] as? CGRect
    else { return }

    let height = UIScreen.main.bounds.height - frame.origin.y
    self?.webView.scrollView.contentInset.bottom = max(height, 0)
    self?.webView.scrollView.verticalScrollIndicatorInsets.bottom = max(height, 0)
}

이건 실무에서는 반드시 넣어야하는 처리라고 한다.

 

 

 

웹에서 스크롤이 안 먹히는 문제(특히 특정 도메인)

iOS WKWebView는 부모 UIScrollView와 웹 내부 스크롤이 충돌할 수 있다.
대표적으로 아래와 같은 현상들이다.
- 특정 영역이 스크롤 되지 않는다.
- 스크롤이 '딱딱함'이 느껴진다.
- 조금 움직이다가 갑자기 멈춘다.
- position: fixed 요소가 떨린다.

이러한 현상들의 원인은 아래와 같다.

- CSS에서 touch-action 미지원
iOS Safari/WebKit은 여전히 touch-acion: pan-y 등을 제대로 지원하지 않는다.
따라서 CSS 스크롤이 부드럽지 않을수도 있다.

또 아래와 같은 원인도 있다.

- overflow: scroll 영역 이슈
overflow: scroll 또는 overflow: auto를 가진 div 내부는 부모 UIScrollView와 충돌할 수 있다.

iOS에서 momentum scrolling 활성화를 해주어야한다.

.scroll-area {
  -webkit-overflow-scrolling: touch;
}

이 속성이 없으면 모바일 Safari/WKWebView 모두 정상적인 스크롤 모멘텀을 제공하지 않는다.

 

 

 

웹과 네이티브 스크롤이 동시에 있는 경우(이중스크롤)

모바일 웹 프로젝트에서 가장 흔한 문제 중 하나이다.
대표적으로 아래와 같은 현상들을 의미한다.
- 웹 내부 스크롤이 움직이는데 네이티브 WKWebView까지 같이 움직인다.
- 스크롤이 끝났는데 bounce가 두 번 발생한다.
- 상단 고정 헤더가 떨린다.

이러한 문제들을 해결하기 위해서는 아래와 같은 처리가 필요하다.
- WKWebView의 bounce 제거
- 웹 내부 스크롤 영역에 -webkit-overflow-scrolling: touch
- 가능하면 앱에서는 overscroll-behavior 컨드롤을 웹에서 같이 적용

html, body {
  overscroll-behavior: none;
}

 

 

 

Safe Area와 스크롤의 결합 문제

이것 무슨 문제냐.
예를 들어서 웹에서 아래와 같이 Safe Area padding을 적용했다면,

padding-top: env(safe-area-inset-top);

그리고 WKWebView가 아래와 같이 SafeAreaLayoutGuide에 맞춰져있다면,

webView.snp.makeConstraints {
    $0.top.equalTo(view.safeAreaLayoutGuide)
}

(스냅킷 사용 코드임)

이렇게 된다면, 상단 padding이 2번 적용된다. 그리고 헤더가 내려앉아 이상한 여백이 생긴다.


즉, 정리하자면 웹이 SafeArea를 처리한다면? 네이티브는 SafeAreaLayoutGuide를 쓰지 않는다.
만약 네이티브가 Safe Area를 처리한다면? 웹에서 env()를 제거한다.

 

 

---

 

WKWebView는 단순한 웹 컨테이너처럼 보이지만, 실제로는 여러 iOS 고유 동작과 밀접하게 엮여 있다.
특히 스크롤과 Safe Area, 키보드, 바우스처럼 사용자 경험에 직접적으로 영향을 주는 요소들은
네이티브와 웹 레이어가 어덯게 개입하느냐에 따라 전혀 다른 결과가 나온다.

결국 중요한 것은 어떤 계층이 무엇을 책임질지 명확히 결정하는 것이다.
초기 개발 단계에서 웹 개발자와 앱 개발자 사이에 이 원칙이 확실히 정리되어 있으면
대부분의 스크롤∙레이아웃 문제는 예측이 가능해지고,
하이브리드 앱에서도 iOS 네이티브에 가깝고 안정적인 UX를 제공할 수 있다.

기존에는 이미 만들어진 웹앱을 이슈를 해결하거나 유지보수하는 데 집중했다면,
이번에는 웹앱 기반 하이브리드 구조를 처음부터 직접 개발에 참여하면서
iOS의 여러 요소가 생각보다 훨씬 웹과 깊게 연결되어 있다는 점을 새롭게 깨닫게 되었다.

이번 정리가 부족한 부분들도 많겠지만,
이 정리가 처음 웹앱 기반 하이브리드 앱을 경험하는 개발자들에게는
조금이나마 실질적인 도움이 되기를 바란다.

---