Text Content Type: 의미론적 유형과 UIKit

Text Content Type이란?

Text Content Type(UITextContentType)은 입력 필드가 어떤 의미론적 데이터를 기대하는지 iOS에 알려주는 UIKit 텍스트 필드의 속성입니다. 시스템은 이 정보를 두 가지 목적으로 사용합니다: 적절한 키보드 레이아웃 선택과 키체인(iCloud Keychain)의 자동 완성 메커니즘 활성화입니다.

iOS 5에서 의미론적 유형의 첫 번째 버전이 도입되었고, iOS 17에서는 UITextContentType 세트가 34개의 상수로 확장되어 일회용 코드, 우편번호, 거리 이름에 대한 새로운 유형이 추가되었습니다. 각 상수는 시스템이 내부 처리 규칙에 매핑하는 문자열을 나타냅니다.

이 메커니즘은 UITextInputTraits 수준에서 작동합니다. 이는 UITextField, UITextView 및 UISearchBar가 상속하는 프로토콜입니다. 즉, 콘텐츠 유형은 추가 구성 없이 모든 표준 입력 요소에서 사용할 수 있습니다.

WWDC 2024 세션 101에 따르면, Apple은 인터페이스의 모든 텍스트 필드에 콘텐츠 유형을 지정할 것을 권장합니다. 자동 완성이 예상되지 않는 경우에도 마찬가지입니다. 마크업 자체는 VoiceOver가 장애가 있는 사용자에게 필드의 목적을 올바르게 알리는 데 도움이 됩니다.

사용 가능한 UITextContentType 유형

UIKit은 카테고리로 구분된 유형의 계층 구조를 제공합니다. 주요 그룹에는 식별 데이터(이름, 성, 사용자 이름), 연락처 정보(이메일, 전화번호, 주소) 및 자격 증명(비밀번호, 일회용 코드)이 포함됩니다. 각 그룹은 다른 자동 완성 메커니즘을 활성화합니다.

연락처 데이터

연락처 유형 그룹에는 `.emailAddress`, `.telephoneNumber`, `.fullStreetAddress` 및 `.city`가 포함됩니다. 이러한 유형은 연락처 및 iCloud Keychain에서 자동 완성을 활성화합니다. `.emailAddress` 유형의 필드는 이전에 입력한 이메일 주소를 자동으로 제안하고, `.telephoneNumber`는 주소록에서 전화번호를 제안합니다.

자격 증명

로그인 필드에는 .username, .password 및 .newPassword가 제공됩니다. .username 유형은 저장된 자격 증명을 제공하는 iCloud 비밀번호 관리자를 활성화합니다. .newPassword 유형의 필드는 첫 번째 입력 시 iCloud Keychain을 통해 강력한 비밀번호 생성을 시작합니다.

iOS 17+ 특수 유형

iOS 17부터 Apple은 SMS 확인 코드용 .oneTimeCode와 소포 추적용 .shipmentTrackingNumber를 추가했습니다. .oneTimeCode 유형은 메시지에서 코드를 자동으로 인식하고 메시지 앱을 열 필요 없이 QuickType 바에서 제공합니다.

각 유형은 문자열 상수로 표현되지만 rawValue 대신 == 연산자를 사용하여 비교해야 합니다. iOS는 향후 버전에서 새로운 유형을 추가할 수 있으므로 switch-case 문에서 항상 default 분기를 사용하세요.

콘텐츠 유형에 따른 키보드 적응

UIKeyboardType과 UITextContentType은 함께 작동합니다. 키보드 유형은 키보드 레이아웃을 결정하고, 콘텐츠 유형은 QuickType 바에 추가 버튼을 추가합니다. 콘텐츠 유형이 설정된 경우 iOS는 최적의 입력을 위해 키보드 유형을 재정의할 수 있습니다. 예를 들어 `.emailAddress` 유형의 경우 키보드가 기본 레이어에 @ 기호를 자동으로 표시합니다.

.telephoneNumber 유형의 필드의 경우 iOS는 설정된 키보드 유형에 관계없이 키보드를 전화 레이아웃으로 전환합니다. 이 동작은 비활성화할 수 없습니다. 시스템은 콘텐츠 유형의 우선순위를 명시적 키보드 구성보다 높게 간주합니다. 개발자는 두 속성을 모두 구성할 필요가 없습니다.

.URL 및 .emailAddress 유형은 키보드에 각각 .com 및 @ 버튼을 추가합니다. .creditCardNumber 콘텐츠 유형의 .decimalPad 유형은 소수 구분 기호가 있는 숫자 키보드를 표시하여 금액 및 카드 번호 입력에 편리합니다. Apple Human Interface Guidelines에 따르면, 사용자는 키보드가 입력 중인 데이터 유형과 일치하기를 기대하며 그 반대는 아닙니다.

예외는 .oneTimeCode입니다. 이 유형은 키보드 레이아웃을 변경하지 않지만 SMS의 코드로 QuickType 바를 활성화합니다. 사용자는 키보드 위에 코드 제안을 보고 한 번의 탭으로 삽입할 수 있습니다. 이 메커니즘은 SMS 수신 후 first responder가 되는 필드에만 작동합니다.

자동 완성과 키체인

iOS의 자동 완성은 Text Content Type을 사용하여 입력 필드를 iCloud Keychain 및 ASCredentialProviderViewController의 데이터와 매칭합니다. 시스템은 화면의 모든 필드를 분석하고, 의미론적 유형을 결정하며, 해당 저장 데이터를 제공합니다. 유형이 올바르게 지정되지 않으면 자동 완성이 활성화되지 않습니다.

자동 완성이 작동하려면 세 가지 조건이 충족되어야 합니다. 첫째, 필드에 올바른 UITextContentType이 있어야 합니다. 둘째, 화면에 다른 유형의 필드가 두 개 이상 있어야 합니다(예: .username 및 .password). 셋째, 앱이 웹사이트와 동기화하기 위해 webcredentials 자격과 함께 Associated Domains를 지원해야 합니다.

키체인(Keychain)은 저장된 레코드를 분류하기 위해 콘텐츠 유형을 사용합니다. 필드가 .password로 표시된 경우 시스템은 입력된 값을 iCloud Keychain에 저장하고 다음 로그인 시 제공합니다. .creditCardNumber 유형의 필드는 Face ID 확인 후 자동으로 Wallet에 저장됩니다.

.oneTimeCode 유형의 일회용 코드의 경우 iOS 17은 새로운 AutoFill OTP 메커니즘을 사용하며, 이는 직접적인 SMS 액세스가 필요하지 않습니다. 시스템은 운영 체제 수준에서 메시지의 코드를 가로채고, 앱이 메시지 내용을 읽지 못하도록 하면서 QuickType 바를 통해 앱에 전달합니다.

Swift 사용 예제

Swift에서 Text Content Type의 기본 구성은 코드의 textContentType 속성을 통해 또는 Interface Builder를 통해 수행됩니다. 코드에서는 상수를 할당하는 데 한 줄이 필요하고, IB에서는 속성 관리자의 드롭다운에서 원하는 유형을 선택합니다.

let emailField = UITextField()
emailField.textContentType = .emailAddress
emailField.placeholder = "example@domain.com"

let passwordField = UITextField()
passwordField.isSecureTextEntry = true
passwordField.textContentType = .newPassword

자동 완성과 함께 프로그래밍 방식 로그인 양식 작성의 경우 다른 콘텐츠 유형이 있는 두 필드를 모두 사용하세요. 시스템이 자동으로 로그인과 비밀번호로 연결합니다. 앱이 생체 인식 로그인을 지원하는 경우 올바른 계정 인식을 위해 .username 유형의 필드를 추가하세요.

class LoginViewController: UIViewController {

    @IBOutlet var usernameField: UITextField!
    @IBOutlet var passwordField: UITextField!

    override func viewDidLoad() {
        super.viewDidLoad()
        usernameField.textContentType = .username
        passwordField.textContentType = .password
        passwordField.autocorrectionType = .no
    }
}

SMS에서 일회용 코드 입력 필드의 경우 .oneTimeCode 유형을 지정하세요. 시스템은 코드를 받은 후 QuickType 바에 코드를 자동으로 제안합니다. 개발자는 SMS 읽기 권한을 요청하거나 사용자 지정 메시지 구문 분석을 구현할 필요가 없습니다.

let otpField = UITextField()
otpField.textContentType = .oneTimeCode
otpField.keyboardType = .numberPad
otpField.placeholder = "Code from SMS"

iOS 17+의 경우 .oneTimeCode 유형은 필드 포커스 없이 자동 채우기를 지원합니다. 사용자가 코드가 포함된 SMS를 받으면 iOS는 잠금 화면에 코드를 표시하고, 잠금 해제 후 코드는 해당 콘텐츠 유형이 있는 활성 필드에 자동으로 삽입됩니다.

유형 선택 권장 사항

올바른 유형 선택은 양식 전환율과 사용자 경험에 직접적인 영향을 미칩니다. Apple은 사용 가능한 가장 구체적인 유형을 지정할 것을 강력히 권장합니다. 예를 들어, 이름 필드에는 일반 .name 대신 .givenName을 사용하세요. 이렇게 하면 시스템이 연락처에서 올바른 이름으로 자동 완성을 제안할 수 있습니다.

일반적인 실수를 피하세요. 사용자 이름 필드에 .emailAddress를 설정하는 것입니다. 앱이 이메일을 로그인으로 사용하는 경우 로그인 필드에는 .username을, 비밀번호 필드에는 .password를 지정하세요. .emailAddress 유형은 식별자가 아닌 연락처 데이터로서의 이메일 입력 전용입니다.

동일한 유형의 여러 필드가 있는 양식의 경우(예: 두 개의 이메일 주소), 각 필드에 .textContentType 속성을 설정하되 다른 accessibilityIdentifier 값을 추가하세요. 이렇게 하면 VoiceOver가 필드를 올바르게 알리는 데 도움이 되지만, 자동 완성 시스템은 두 필드에 동일한 값을 제안할 수 있습니다.

데이터가 채워진 키체인으로 실제 기기에서 자동 완성을 테스트하세요. 시뮬레이터는 iCloud Keychain을 완전히 지원하지 않으며 자동 완성 동작이 다를 수 있습니다. Apple Developer Forums(2025)에 따르면, 가장 일반적인 자동 완성 문제는 잘못 지정된 콘텐츠 유형으로 인해 발생합니다.