Text Content Type: tipos semânticos e UIKit

O que é Text Content Type?

Text Content Type (UITextContentType) é uma propriedade dos campos de texto do UIKit que informa ao iOS quais dados semânticos o campo de entrada espera. O sistema usa esta informação para dois propósitos: selecionar o layout de teclado adequado e ativar o mecanismo de preenchimento automático do chaveiro (iCloud Keychain).

O iOS 5 introduziu a primeira versão dos tipos semânticos, e no iOS 17 o conjunto de UITextContentType expandiu-se para 34 constantes, incluindo novos tipos para códigos de uso único, códigos postais e nomes de ruas. Cada constante representa uma string que o sistema mapeia para regras de processamento internas.

O mecanismo funciona ao nível de UITextInputTraits — um protocolo herdado por UITextField, UITextView e UISearchBar. Isto significa que o content type está disponível em todos os elementos de entrada padrão sem configuração adicional.

De acordo com a sessão 101 da WWDC 2024, a Apple recomenda especificar um content type para cada campo de texto na interface — mesmo que o preenchimento automático não seja esperado. A própria marcação ajuda o VoiceOver a anunciar corretamente o propósito do campo para utilizadores com deficiências.

Tipos disponíveis de UITextContentType

O UIKit fornece uma hierarquia de tipos divididos em categorias. Os grupos principais incluem dados de identificação (nome, sobrenome, username), informações de contacto (email, telefone, endereço) e credenciais (senha, código de uso único). Cada grupo ativa diferentes mecanismos de preenchimento automático.

Dados de contacto

O grupo de tipos de contacto inclui `.emailAddress`, `.telephoneNumber`, `.fullStreetAddress` e `.city`. Estes tipos ativam o preenchimento automático a partir de contactos e iCloud Keychain. Um campo com tipo `.emailAddress` sugere automaticamente endereços de email introduzidos anteriormente, enquanto `.telephoneNumber` sugere números de telefone da agenda de contactos.

Credenciais

Para campos de início de sessão, destinam-se .username, .password e .newPassword. O tipo .username ativa o gestor de senhas do iCloud, que oferece credenciais guardadas. Um campo com tipo .newPassword inicia a geração de uma senha forte através do iCloud Keychain na primeira entrada.

Tipos especializados iOS 17+

A partir do iOS 17, a Apple adicionou .oneTimeCode para códigos de confirmação SMS e .shipmentTrackingNumber para rastreamento de encomendas. O tipo .oneTimeCode reconhece automaticamente os códigos das mensagens e oferece-os na barra QuickType sem necessidade de abrir a aplicação Mensagens.

Cada tipo é representado por uma constante de string, mas devem ser comparados usando o operador ==, não através de rawValue. O iOS pode adicionar novos tipos em versões futuras, por isso use sempre um ramo default nas declarações switch-case.

Adaptação do teclado ao tipo de conteúdo

UIKeyboardType e UITextContentType trabalham juntos: o tipo de teclado determina o layout do teclado, enquanto o content type adiciona botões extras na barra QuickType. Se um content type for definido, o iOS pode substituir o tipo de teclado para entrada ótima. Por exemplo, com o tipo `.emailAddress`, o teclado mostra automaticamente o símbolo @ na camada principal.

Para um campo com tipo .telephoneNumber, o iOS muda o teclado para o layout telefónico independentemente do tipo de teclado definido. Este comportamento não pode ser desativado — o sistema considera a prioridade do content type superior à configuração explícita do teclado. Os programadores não precisam de configurar ambas as propriedades.

Os tipos .URL e .emailAddress adicionam botões .com e @ ao teclado respetivamente. O tipo .decimalPad com content type .creditCardNumber mostra um teclado numérico com separador decimal, o que é conveniente para introduzir quantias e números de cartão. De acordo com as Apple Human Interface Guidelines, os utilizadores esperam que o teclado corresponda ao tipo de dados que estão a introduzir, não o contrário.

Uma exceção é .oneTimeCode — este tipo não altera o layout do teclado mas ativa a barra QuickType com códigos de SMS. O utilizador vê uma sugestão de código acima do teclado e pode inseri-lo com um toque. O mecanismo funciona apenas para campos que se tornam first responder após receber um SMS.

Preenchimento automático e chaveiro

O preenchimento automático no iOS usa Text Content Type para associar campos de entrada com dados do iCloud Keychain e ASCredentialProviderViewController. O sistema analisa todos os campos no ecrã, determina os seus tipos semânticos e oferece os dados guardados correspondentes. Sem tipos especificados corretamente, o preenchimento automático não é ativado.

Para que o preenchimento automático funcione, três condições devem ser cumpridas. Primeiro, o campo deve ter um UITextContentType correto. Segundo, o ecrã deve conter pelo menos dois campos com tipos diferentes (por exemplo, .username e .password). Terceiro, a aplicação deve suportar Associated Domains com a permissão webcredentials para sincronização com um site.

O chaveiro (Keychain) usa o content type para classificar os registos guardados. Se um campo estiver marcado como .password, o sistema guarda o valor introduzido no iCloud Keychain e oferece-o no próximo início de sessão. Campos com tipo .creditCardNumber são automaticamente guardados na Wallet após confirmação com Face ID.

Para códigos de uso único com tipo .oneTimeCode, o iOS 17 usa o novo mecanismo AutoFill OTP, que não requer acesso direto a SMS. O sistema interceta códigos de mensagens ao nível do sistema operativo e passa-os à aplicação através da barra QuickType, evitando a leitura do conteúdo das mensagens pela aplicação.

Exemplos de uso em Swift

A configuração básica de Text Content Type em Swift é feita através da propriedade textContentType em código ou através do Interface Builder. Em código, atribuir uma constante leva uma linha, enquanto no IB o tipo desejado é selecionado a partir de uma lista suspensa no inspetor de atributos.

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

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

Para a criação programática de um formulário de início de sessão com preenchimento automático, use ambos os campos com diferentes content types. O sistema liga-os automaticamente como login e senha. Se a aplicação suportar início de sessão biométrico, adicione um campo com tipo .username para reconhecimento correto da conta.

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
    }
}

Para um campo de entrada de código de uso único de SMS, especifique o tipo .oneTimeCode. O sistema sugerirá automaticamente o código na barra QuickType após recebê-lo. O programador não precisa solicitar permissão de leitura de SMS nem implementar uma análise de mensagens personalizada.

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

Para iOS 17+, o tipo .oneTimeCode suporta preenchimento automático sem foco no campo. Se o utilizador receber um SMS com um código, o iOS oferece-o no ecrã de bloqueio e, após desbloquear, o código é automaticamente inserido no campo ativo com o content type correspondente.

Recomendações para escolher um tipo

Escolher o tipo correto afeta diretamente a conversão do formulário e a experiência do utilizador. A Apple recomenda fortemente especificar o tipo mais específico disponível. Por exemplo, use .givenName para o campo de nome em vez do genérico .name — isto permite que o sistema sugira preenchimento automático de contactos com o nome correto.

Evite um erro comum — definir .emailAddress para um campo de username. Se a aplicação usar o email como login, especifique .username para o campo de login e .password para o campo de senha. O tipo .emailAddress destina-se exclusivamente à entrada de email como dado de contacto, não como identificador.

Para formulários com múltiplos campos do mesmo tipo (por exemplo, dois endereços de email), defina a propriedade .textContentType para cada campo, mas adicione valores diferentes de accessibilityIdentifier. Isto ajuda o VoiceOver a anunciar corretamente os campos, embora o sistema de preenchimento automático possa sugerir o mesmo valor para ambos os campos.

Teste o preenchimento automático num dispositivo real com um chaveiro preenchido. O simulador não suporta iCloud Keychain na totalidade, e o comportamento do preenchimento automático pode diferir. De acordo com os Apple Developer Forums (2025), os problemas mais comuns de preenchimento automático surgem precisamente de um content type especificado incorretamente.