Read Original
#Frontend

모바일 웹뷰에서 iOS·Android 가상 키보드 길들이기

모바일 웹뷰에서 iOS·Android 가상 키보드 길들이기
01

Summary

모바일 웹뷰 가상 키보드 화면 밀림, 'VirtualViewport'로 깔끔하게 해결하기

Layout Viewport와 Visual Viewport의 사양 차이부터 크로스 플랫폼 대응 컴포넌트 구현까지

카카오뱅크 신사업클라이언트개발팀에서 채팅형 웹뷰 서비스 개발 중 마주친 iOS/Android 가상 키보드 뷰포트 이슈의 원인을 규명하고 이를 해결한 과정을 공유합니다. OS별로 상이한 비주얼 뷰포트 동작과 이벤트 순서 문제를 극복하기 위해 크로스 플랫폼 호환 가능한 VirtualViewport 컴포넌트를 구현한 실무 노하우를 담았습니다.

  • 01Layout Viewport와 Visual Viewport 사양 차이에 따른 키보드 노출 시 화면 밀림 원인 분석
  • 02Chrome 108 뷰포트 기본 동작 변경 및 Android Edge-to-Edge 도입에 따른 영향도 파악
  • 03CSS opacity 애니메이션 트릭을 이용해 iOS WebKit의 포커스 시 자동 스크롤 현상 방어
  • 04overscroll-behavior와 1px overflow 가상 요소를 결합한 스크롤 체이닝 완전 차단 기법
  • 05focus, blur, resize 이벤트를 통합 추적하는 throttle + trailing debounce 기반 재검사 로직 구축

RECOMMENDATION

모바일 웹뷰 기반의 채팅 서비스나 하단 고정 입력폼을 구현하는 프론트엔드 개발자에게 적극 추천하며, 특히 iOS/Android 간 뷰포트 파편화로 고통받는 팀에 실질적인 해결책을 제시합니다.

The Problem

모바일 웹뷰 환경에서 가상 키보드가 활성화될 때 레이아웃 뷰포트와 비주얼 뷰포트의 처리 방식 차이로 인해 화면 전체가 위로 밀리거나 하단 입력창이 가려지는 레이아웃 깨짐 현상이 발생했습니다. OS 및 브라우저 엔진마다 가상 키보드가 노출될 때 뷰포트 높이를 계산하는 동작 규격이 달라 일관된 사용자 경험을 제공하기 어려웠습니다.

The Solution

Visual Viewport API를 활용해 실제 가시 영역 높이와 동기화되는 VirtualViewport 컴포넌트를 설계하고 Flexbox 구조로 헤더 및 입력창 레이아웃을 고정했습니다. 또한 CSS opacity 애니메이션을 통한 iOS 자동 스크롤 방지, overscroll-behavior 및 1px 가상 요소를 이용한 스크롤 체이닝 차단, resize·focus·blur 이벤트를 단일 재검사 흐름으로 통합하는 스로틀/디바운스 기법을 적용했습니다.

The Result

카카오뱅크 혜택 탭의 'AI 키워드 퀴즈' 채팅형 인터페이스에서 iOS와 Android 양대 OS 모두 화면 흔들림 없이 하단 입력창과 상단 헤더가 고정되는 안정적인 가상 키보드 UX를 구현했습니다.

Trade-off

VirtualKeyboard API 미지원 환경으로 인해 키보드가 완전히 나타나기 전까지의 높이를 사전 계산할 수 없으며, opacity 애니메이션을 활용한 포커스 스크롤 방지는 WebKit 비표준 동작에 의존하므로 OS 업데이트 시 지속적인 검증이 필요합니다.

03

Key Concepts

Concept · 01

Visual Viewport

사용자가 화면에서 실제로 보고 있는 디바이스의 시각적 영역입니다. 핀치 줌이나 가상 키보드 활성화 시 레이아웃 뷰포트 크기는 유지된 채 비주얼 뷰포트의 높이가 동적으로 축소될 수 있습니다.

  • 가상 키보드가 나타날 때 동적으로 변하는 visualViewport.height 값을 추적하여 최상위 컨테이너 높이로 반영함
  • iOS와 Android 공통으로 제공되는 실제 가시 영역 높이를 최상위 레이아웃 계산의 기준으로 삼음
Concept · 02

Initial Containing Block (ICB)

CSS 레이아웃 계산의 기준이 되는 최상위 컨테이닝 블록으로, 스크린 매체에서는 레이아웃 뷰포트 크기를 바탕으로 형성됩니다.

  • position: fixed 요소의 배치 기준이 되나 가상 키보드 노출 시 뷰포트 축소 방식 차이로 레이아웃이 깨지는 원인이 됨
  • VisualViewport 높이에 동기화되는 별도의 VirtualViewport flex 컨테이너를 생성하여 가상의 ICB 역할을 수행하도록 함
Concept · 03

Scroll Chaining

하위 스크롤 컨테이너의 스크롤이 경계에 도달했을 때 상위 문서나 뷰포트로 스크롤 이벤트가 전동되어 전체 페이지가 스크롤되는 현상입니다.

  • overscroll-behavior: none 속성을 본문 영역에 부여하여 불필요한 바깥 문서 스크롤을 제한함
  • 콘텐츠 길이가 짧아 overflow가 발생하지 않는 경우를 대비해 1px 높이의 가상 요소를 더해 스크롤 체이닝을 강제로 방지함