Text Content Type：是什么、语义类型和UIKit

什么是Text Content Type？

Text Content Type (UITextContentType) — 是UIKit文本字段的一个属性，用于告知iOS输入字段期望什么语义数据。系统将此信息用于两个目的：选择合适的键盘布局和从钥匙串（iCloud Keychain）激活自动填充机制。

在iOS 5中引入了第一版语义类型，在iOS 17中UITextContentType集扩展到了34个常量，包括用于一次性代码、邮政编码和街道名称的新类型。每个常量代表一个字符串，系统将其与内部处理规则进行匹配。

该机制在UITextInputTraits级别工作 — 这是UITextField、UITextView和UISearchBar继承的协议。这意味着content type在所有标准输入元素中无需额外配置即可使用。

根据WWDC 2024 Session 101，Apple建议为界面中的每个文本字段指定content type — 即使不打算使用自动填充。标签本身有助于VoiceOver为残障用户正确播报字段的用途。

可用的UITextContentType类型

UIKit提供了按类别划分的类型层次结构。主要组包括身份数据（名字、姓氏、用户名）、联系信息（电子邮件、电话、地址）和账户（密码、一次性代码）。每组激活不同的自动填充机制。

联系信息

联系类型组包括`.emailAddress`、`.telephoneNumber`、`.fullStreetAddress`和`.city`。这些类型从通讯录和iCloud Keychain激活自动填充。类型为`.emailAddress`的字段会自动建议之前输入的电子邮件地址，而`.telephoneNumber`则建议通讯录中的电话号码。

账户

登录字段使用.username、.password和.newPassword。.username类型激活iCloud密码管理器，提供已保存的账户。类型为.newPassword的字段在首次输入时通过iCloud Keychain启动安全密码生成。

iOS 17+专用类型

从iOS 17开始，Apple添加了用于短信确认码的.oneTimeCode和用于包裹追踪的.shipmentTrackingNumber。.oneTimeCode类型自动识别消息中的代码，并在QuickType栏中提供，无需打开Messages应用。

每个类型由一个字符串常量表示，但应通过==运算符进行比较，而不是通过rawValue。iOS可能会在将来版本中添加新类型，因此在switch-case中始终使用default分支。

键盘根据内容类型的自适应

UIKeyboardType和UITextContentType共同工作：keyboard type确定键盘布局，而content type确定QuickType栏中的附加按钮。如果指定了content type，iOS可以覆盖keyboard type以实现最佳输入。例如，使用`.emailAddress`类型时，键盘在主层自动显示@符号。

对于类型为.telephoneNumber的字段，无论设置的keyboard type如何，iOS都会将键盘切换到电话布局。此行为无法关闭 — 系统认为content type的优先级高于显式键盘配置。开发人员无需重复设置这两个属性。

.URL和.emailAddress类型分别向键盘添加.com和@按钮。带有content type .creditCardNumber的.decimalPad类型显示带小数分隔符的数字键盘，便于输入金额和卡号。根据Apple Human Interface Guidelines，用户期望键盘与输入数据的类型匹配，而不是相反。

.oneTimeCode是个例外 — 此类型不改变键盘布局，但激活带有短信代码的QuickType栏。用户可以看到键盘上方的代码建议，并可以通过一次点击插入它。该机制仅对接收短信后成为first responder的字段有效。

自动填充和钥匙串

iOS中的自动填充使用Text Content Type将输入字段与iCloud Keychain和ASCredentialProviderViewController的数据进行匹配。系统分析屏幕上的所有字段，确定其语义类型并提供相应的已存储数据。没有正确指定的类型，自动填充不会激活。

自动填充工作需满足三个条件。第一 — 字段必须具有正确的UITextContentType。第二 — 屏幕必须包含至少两个具有不同类型的字段（例如.username和.password）。第三 — 应用必须支持使用webcredentials entitlement的Associated Domains以与网站同步。

钥匙串（Keychain）使用content type对保存的记录进行分类。如果字段标记为.password，系统将输入的值保存到iCloud Keychain中，并在下次登录时提供。类型为.creditCardNumber的字段在通过Face ID确认后自动保存到Wallet中。

对于.oneTimeCode类型的一次性代码，iOS 17使用新的AutoFill OTP机制，无需直接访问短信。系统在操作系统级别截取消息中的代码，并通过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

要以编程方式创建具有自动填充功能的登录表单，请使用具有不同content type的两个字段。系统会自动将它们关联为用户名和密码。如果应用支持生物识别登录，请添加类型为.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
    }
}

对于来自短信的一次性代码输入字段，请指定.oneTimeCode类型。系统会在收到代码后自动在QuickType栏中建议该代码。开发人员无需请求读取短信的权限或实现自己的消息解析。

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

对于iOS 17+，.oneTimeCode类型支持无需字段焦点的自动填充。如果用户收到带有代码的短信，iOS会在锁定屏幕上提供该代码，解锁后代码会自动插入到具有相应content type的活动字段中。

类型选择建议

选择正确的类型直接影响表单转化率和用户体验。Apple强烈建议指定最具体的可用类型。例如，对于姓名字段，使用.givenName而不是通用的.name — 这将允许系统从通讯录中建议具有正确名称的自动填充。

避免常见错误 — 为username字段设置.emailAddress。如果应用使用电子邮件作为用户名，请为登录字段指定.username类型，为密码字段指定.password类型。.emailAddress类型仅用于作为联系信息输入电子邮件的字段，而不是作为标识符。

对于具有多个相同类型字段的表单（例如两个电子邮件地址），请为每个字段使用.textContentType属性，但添加不同的accessibilityIdentifier标识符。这将帮助VoiceOver正确播报字段，尽管自动填充系统可能会为两个字段建议相同的选项。

在真实设备上使用已填充的钥匙串测试自动填充。模拟器不完全支持iCloud Keychain，自动填充的行为可能有所不同。根据Apple Developer Forums（2025），最常见的自动填充问题正是由不正确指定的content type引起的。