Keyboard Avoidance — 본질, 구현 방법 및 인터페이스 오프셋

Keyboard Avoidance란

Keyboard Avoidance는 iOS에서 시스템 키보드가 나타날 때 활성 입력 필드의 가시성을 보장하는 일련의 기술입니다. 기본 문제: 키보드는 화면의 최대 50%를 차지하며 텍스트 필드, 제출 버튼 및 기타 요소를 포함한 인터페이스의 하단 절반을 가립니다.

구현에는 세 가지 주요 접근 방식이 있습니다: Keyboard Notifications를 통한 수동 관리(클래식 방식, iOS 3.0부터 작동), 자동 스크롤이 있는 UIScrollView 사용(Apple 권장), Keyboard Layout Guide(iOS 15+의 현대적 방식). 선택은 최소 지원 iOS 버전과 인터페이스 복잡성에 따라 달라집니다.

Apple에 따르면, Keyboard Avoidance의 부재는 텍스트 필드가 키보드로 완전히 가려진 경우 검토 중 앱 거부의 가장 일반적인 원인 중 하나입니다. App Store Guidelines는 활성 입력 중에 모든 대화형 요소에 액세스할 수 있어야 한다고 명시적으로 요구합니다.

iOS가 자동으로 수행하지 않는 이유

iOS는 인터페이스의 의미를 알지 못하기 때문에 어떤 요소가 계속 표시되어야 하는지 자동으로 결정할 수 없습니다. 하나의 텍스트 필드가 있는 간단한 양식에서는 전체 화면을 위로 이동하는 것으로 충분합니다. 사용자 정의 패널, 플로팅 버튼 및 여러 섹션이 있는 복잡한 인터페이스에서는 다른 동작 로직이 필요합니다.

또한 일부 앱은 의도적으로 콘텐츠를 이동하지 않습니다. 예를 들어 키보드가 작업 영역의 일부인 키보드 계산기나 편집기 등이 있습니다. iOS는 결정을 개발자에게 맡기고 모든 시나리오에 대해 유연한 API를 제공합니다.

키보드 프레임 알림

UIKeyboardWillShowNotification은 iOS가 키보드가 나타나기 전에 보내는 주요 알림입니다. 여기에는 UIResponder.keyboardFrameEndUserInfoKey 사전에 키보드의 최종 위치가 포함된 CGRect와 UIResponder.keyboardAnimationDurationUserInfoKey의 애니메이션 지속 시간이 포함됩니다.

알림 핸들러는 활성 텍스트 필드와 키보드 사이의 겹침을 계산한 다음 컨테이너의 하단 여백(contentInset 또는 frame)을 변경해야 합니다. 필드가 키보드의 상단 가장자리 아래에 있으면 콘텐츠가 겹침만큼 위로 이동합니다. 키보드가 사라지면 여백이 원래 값으로 돌아갑니다.

@objc func keyboardWillShow(_ notification: Notification) {
    guard let keyboardFrame = notification
        .userInfo?[UIResponder.keyboardFrameEndUserInfoKey]
        as? CGRect else { return }
    
    let keyboardHeight = keyboardFrame.height
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
}

알림을 사용할 때는 시스템 키보드와 동기화하여 애니메이션을 처리하는 것이 중요합니다. iOS는 애니메이션 곡선(UIResponder.keyboardAnimationCurveUserInfoKey)과 지속 시간을 제공합니다. 이러한 매개변수와 함께 UIView.animate를 사용하여 키보드가 나타남과 동시에 콘텐츠가 부드럽게 이동하도록 합니다.

iOS 15+의 Keyboard Layout Guide

UIScrollView.keyboardLayoutGuide는 iOS 15에서 도입된 Keyboard Avoidance를 위한 최신 API입니다. 키보드 위치를 자동으로 추적하고 인터페이스 하단을 키보드 상단 가장자리에 연결하는 Auto Layout 제약 조건을 업데이트합니다.

사용하려면 UIScrollView 또는 UIStackView에서 layout guide를 활성화하고 하단 콘텐츠 제약 조건을 연결하기만 하면 됩니다. 알림, 높이 계산 또는 애니메이션에 대한 수동 작업이 필요하지 않습니다 — 시스템이 모든 것을 자동으로 수행하며 키보드 표시 및 숨김과 애니메이션을 동기화합니다.

// Keyboard Layout Guide 활성화 (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// 하단 제약을 키보드 상단에 고정
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard는 하단 가장자리에서 분리될 수 있는 키보드(iPad)에 가이드가 응답해야 하는지 결정하는 속성입니다. 인터페이스가 플로팅 키보드에서 올바르게 작동하는 경우에만 true로 설정하세요. iPhone에서는 이 속성이 무시됩니다. 키보드는 항상 하단 가장자리에 고정됩니다.

UIScrollView와 키보드

UIScrollView는 Apple이 Keyboard Avoidance의 기반으로 사용할 것을 권장하는 컨테이너입니다. 키보드가 나타나면 scroll view가 contentInset.bottom을 증가시켜 콘텐츠를 위로 스크롤하고 활성 필드를 표시할 수 있습니다.

핵심 메서드는 scrollRectToVisible로, 지정된 사각형(활성 텍스트 필드)이 표시 영역에 들어오도록 프로그래밍 방식으로 scroll view를 스크롤합니다. contentInset 변경과 scrollRectToVisible 호출을 결합하면 필드가 가려지지 않을 뿐만 아니라 표시 영역의 상단 부분에 위치하게 됩니다.

func adjustScrollForKeyboard(
    keyboardHeight: CGFloat,
    activeField: UIView
) {
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
    
    var visibleRect = view.frame
    visibleRect.size.height -= keyboardHeight
    
    if activeField.frame.origin.y > visibleRect.maxY {
        scrollView.scrollRectToVisible(
            activeField.frame, animated: true
        )
    }
}

UITableView가 있는 UIViewController의 경우 Apple은 키보드가 나타날 때 contentInset을 자동으로 조정하는 UITableViewController 사용을 권장합니다. 추가된 테이블이 있는 UIViewController를 사용하는 경우 수동으로 Keyboard Avoidance를 구현해야 합니다. UITableViewController는 사용자 정의 컨트롤러에 대해 이 동작을 제공하지 않습니다.

Auto Layout과 Keyboard Avoidance

Auto Layout을 사용하면 애니메이션을 프로그래밍하지 않고 Keyboard Avoidance를 구현할 수 있습니다. 특정 제약 조건의 활성화(isActive)를 변경하거나 키보드 알림에 응답하여 상수를 업데이트하기만 하면 됩니다.

일반적인 방식: scroll view 또는 콘텐츠의 하단 여백에 대한 IBOutlet NSLayoutConstraint를 만들고 keyboardWillShow 핸들러에서 constraint.constant = keyboardHeight를 설정하고 keyboardWillHide에서 0으로 재설정합니다. 부드러운 전환을 위해 animate 블록 내에서 layoutIfNeeded를 통해 레이아웃을 업데이트합니다.

UIStackView를 사용할 때 하단 여백 제약 조건을 변경하는 것도 작동합니다. 스택 뷰는 자식 요소를 자동으로 재분배합니다. 그러나 스택 뷰가 UIScrollView 내부에 있는 경우 내부의 제약 조건보다는 scroll view 자체의 contentInset을 관리하는 것이 좋습니다.

Keyboard Avoidance를 위한 타사 솔루션

IQKeyboardManager는 컨트롤러에 코드 한 줄 없이 자동 Keyboard Avoidance를 구현하는 가장 인기 있는 라이브러리입니다(GitHub에서 16,000개 이상의 별). 메서드 스위즐링을 사용하여 텍스트 필드를 추적하고 키보드가 나타날 때 자동으로 콘텐츠를 올립니다.

라이브러리는 유연한 설정을 제공합니다: 필드와 키보드 사이의 거리를 지정하고, 특정 컨트롤러에 대해 활성화/비활성화하고, UITextView 및 사용자 정의 입력 뷰에 대한 동작을 구성할 수 있습니다. 그러나 메서드 스위즐링은 다른 라이브러리와 충돌할 수 있으며, Apple은 예측할 수 없는 부작용으로 인해 프로덕션 코드에 이 접근 방식을 권장하지 않습니다.

대안으로는 TPKeyboardAvoiding(경량 라이브러리, ~2,000개 별) 및 커뮤니티의 KeyboardManager가 있습니다. 최신 프로젝트의 경우 Apple은 iOS 15+의 내장 도구를 사용할 것을 권장하며, 더 낮은 최소 버전의 프로젝트의 경우 contentInset이 있는 UIScrollView(가장 안정적인 내장 솔루션)를 권장합니다.