Text Content Type: tipi semantici e UIKit

Cos'è Text Content Type?

Text Content Type (UITextContentType) è una proprietà dei campi di testo UIKit che comunica a iOS quali dati semantici il campo di input si aspetta. Il sistema utilizza queste informazioni per due scopi: selezionare la disposizione della tastiera appropriata e attivare il meccanismo di completamento automatico dal portachiavi (iCloud Keychain).

iOS 5 ha introdotto la prima versione dei tipi semantici, e in iOS 17 l'insieme UITextContentType si è espanso a 34 costanti, includendo nuovi tipi per codici monouso, codici postali e nomi di strade. Ogni costante rappresenta una stringa che il sistema mappa a regole di elaborazione interne.

Il meccanismo funziona a livello di UITextInputTraits, un protocollo ereditato da UITextField, UITextView e UISearchBar. Ciò significa che il content type è disponibile in tutti gli elementi di input standard senza configurazione aggiuntiva.

Secondo la sessione 101 del WWDC 2024, Apple raccomanda di specificare un content type per ogni campo di testo nell'interfaccia, anche se il completamento automatico non è previsto. La marcatura stessa aiuta VoiceOver ad annunciare correttamente lo scopo del campo per gli utenti con disabilità.

Tipi disponibili di UITextContentType

UIKit fornisce una gerarchia di tipi suddivisi in categorie. I gruppi principali includono dati identificativi (nome, cognome, username), informazioni di contatto (email, telefono, indirizzo) e credenziali (password, codice monouso). Ogni gruppo attiva diversi meccanismi di completamento automatico.

Dati di contatto

Il gruppo dei tipi di contatto include `.emailAddress`, `.telephoneNumber`, `.fullStreetAddress` e `.city`. Questi tipi attivano il completamento automatico dai contatti e da iCloud Keychain. Un campo con tipo `.emailAddress` suggerisce automaticamente gli indirizzi email inseriti in precedenza, mentre `.telephoneNumber` suggerisce i numeri di telefono dalla rubrica.

Credenziali

Per i campi di accesso sono destinati .username, .password e .newPassword. Il tipo .username attiva il gestore di password iCloud, che offre le credenziali salvate. Un campo con tipo .newPassword avvia la generazione di una password sicura tramite iCloud Keychain al primo inserimento.

Tipi specializzati iOS 17+

A partire da iOS 17, Apple ha aggiunto .oneTimeCode per i codici di conferma SMS e .shipmentTrackingNumber per il tracciamento dei pacchi. Il tipo .oneTimeCode riconosce automaticamente i codici dai messaggi e li offre nella barra QuickType senza bisogno di aprire l'app Messaggi.

Ogni tipo è rappresentato da una costante stringa, ma devono essere confrontati usando l'operatore ==, non tramite rawValue. iOS potrebbe aggiungere nuovi tipi in versioni future, quindi usa sempre un ramo default nelle istruzioni switch-case.

Adattamento della tastiera al tipo di contenuto

UIKeyboardType e UITextContentType lavorano insieme: il tipo di tastiera determina la disposizione della tastiera, mentre il content type aggiunge pulsanti extra nella barra QuickType. Se un content type è impostato, iOS può sovrascrivere il tipo di tastiera per un input ottimale. Ad esempio, con il tipo `.emailAddress`, la tastiera mostra automaticamente il simbolo @ sul livello principale.

Per un campo con tipo .telephoneNumber, iOS passa la tastiera alla disposizione telefonica indipendentemente dal tipo di tastiera impostato. Questo comportamento non può essere disattivato — il sistema considera la priorità del content type superiore alla configurazione esplicita della tastiera. Gli sviluppatori non devono configurare entrambe le proprietà.

I tipi .URL e .emailAddress aggiungono rispettivamente i pulsanti .com e @ alla tastiera. Il tipo .decimalPad con content type .creditCardNumber mostra una tastiera numerica con separatore decimale, comoda per inserire importi e numeri di carta. Secondo le Apple Human Interface Guidelines, gli utenti si aspettano che la tastiera corrisponda al tipo di dati inseriti, non il contrario.

Un'eccezione è .oneTimeCode — questo tipo non cambia la disposizione della tastiera ma attiva la barra QuickType con i codici dagli SMS. L'utente vede un suggerimento di codice sopra la tastiera e può inserirlo con un tocco. Il meccanismo funziona solo per i campi che diventano first responder dopo aver ricevuto un SMS.

Completamento automatico e portachiavi

Il completamento automatico in iOS utilizza Text Content Type per abbinare i campi di input con i dati di iCloud Keychain e ASCredentialProviderViewController. Il sistema analizza tutti i campi sullo schermo, determina i loro tipi semantici e offre i dati salvati corrispondenti. Senza tipi specificati correttamente, il completamento automatico non viene attivato.

Affinché il completamento automatico funzioni, devono essere soddisfatte tre condizioni. Primo, il campo deve avere un UITextContentType corretto. Secondo, lo schermo deve contenere almeno due campi con tipi diversi (ad esempio, .username e .password). Terzo, l'app deve supportare Associated Domains con l'entitlement webcredentials per la sincronizzazione con un sito web.

Il portachiavi (Keychain) utilizza il content type per classificare i record salvati. Se un campo è marcato come .password, il sistema salva il valore inserito in iCloud Keychain e lo offre al prossimo accesso. I campi con tipo .creditCardNumber vengono automaticamente salvati in Wallet dopo la conferma con Face ID.

Per i codici monouso con tipo .oneTimeCode, iOS 17 utilizza il nuovo meccanismo AutoFill OTP, che non richiede accesso diretto agli SMS. Il sistema intercetta i codici dai messaggi a livello di sistema operativo e li passa all'app tramite la barra QuickType, bypassando la lettura del contenuto dei messaggi da parte dell'app.

Esempi di utilizzo in Swift

La configurazione di base di Text Content Type in Swift viene effettuata tramite la proprietà textContentType nel codice o tramite Interface Builder. Nel codice, l'assegnazione di una costante richiede una riga, mentre in IB il tipo desiderato viene selezionato da un menu a tendina nell'ispettore degli attributi.

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

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

Per la creazione programmatica di un modulo di accesso con completamento automatico, utilizza entrambi i campi con content type diversi. Il sistema li collega automaticamente come login e password. Se l'app supporta l'accesso biometrico, aggiungi un campo con tipo .username per il corretto riconoscimento dell'account.

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

Per un campo di input di codice monouso da SMS, specifica il tipo .oneTimeCode. Il sistema suggerirà automaticamente il codice nella barra QuickType dopo averlo ricevuto. Lo sviluppatore non deve richiedere l'autorizzazione di lettura SMS né implementare un'analisi personalizzata dei messaggi.

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

Per iOS 17+, il tipo .oneTimeCode supporta il riempimento automatico senza focus sul campo. Se l'utente riceve un SMS con un codice, iOS lo offre sulla schermata di blocco e, dopo lo sblocco, il codice viene automaticamente inserito nel campo attivo con il content type corrispondente.

Raccomandazioni per la scelta del tipo

Scegliere il tipo corretto influisce direttamente sulla conversione del modulo e sull'esperienza utente. Apple raccomanda vivamente di specificare il tipo più specifico disponibile. Ad esempio, utilizza .givenName per il campo del nome invece del generico .name — questo permette al sistema di suggerire il completamento automatico dai contatti con il nome corretto.

Evita un errore comune — impostare .emailAddress per un campo username. Se l'app utilizza l'email come login, specifica .username per il campo di login e .password per il campo password. Il tipo .emailAddress è destinato esclusivamente all'inserimento di email come dato di contatto, non come identificatore.

Per moduli con più campi dello stesso tipo (ad esempio, due indirizzi email), imposta la proprietà .textContentType per ogni campo ma aggiungi valori diversi di accessibilityIdentifier. Questo aiuta VoiceOver ad annunciare correttamente i campi, sebbene il sistema di completamento automatico possa suggerire lo stesso valore per entrambi i campi.

Testa il completamento automatico su un dispositivo reale con un portachiavi popolato. Il simulatore non supporta completamente iCloud Keychain e il comportamento del completamento automatico potrebbe differire. Secondo gli Apple Developer Forums (2025), i problemi più comuni di completamento automatico derivano proprio da un content type specificato in modo errato.