Text Content Type: co to jest, typy semantyczne i UIKit

Co to jest Text Content Type?

Text Content Type (UITextContentType) — to właściwość pól tekstowych UIKit, która informuje iOS, jakie dane semantyczne oczekuje pole wprowadzania. System wykorzystuje te informacje do dwóch celów: doboru odpowiedniego układu klawiatury i aktywacji mechanizmu autouzupełniania z pęku kluczy (iCloud Keychain).

W iOS 5 wprowadzono pierwszą wersję typów semantycznych, a w iOS 17 zestaw UITextContentType rozszerzył się do 34 stałych, w tym nowe typy dla kodów jednorazowych, kodów pocztowych i nazw ulic. Każda stała reprezentuje ciąg znaków, który system dopasowuje do wewnętrznych reguł przetwarzania.

Mechanizm działa na poziomie UITextInputTraits — protokołu, który dziedziczą UITextField, UITextView i UISearchBar. Oznacza to, że content type jest dostępny we wszystkich standardowych elementach wprowadzania bez dodatkowej konfiguracji.

Według WWDC 2024 Session 101, Apple zaleca określanie content type dla każdego pola tekstowego w interfejsie — nawet jeśli autouzupełnianie nie jest przewidziane. Sama etykieta pomaga VoiceOver poprawnie odczytywać przeznaczenie pola dla użytkowników z niepełnosprawnościami.

Dostępne typy UITextContentType

UIKit udostępnia hierarchię typów podzielonych na kategorie. Główne grupy obejmują dane identyfikacyjne (imię, nazwisko, username), informacje kontaktowe (email, telefon, adres) oraz konta (hasło, kod jednorazowy). Każda grupa aktywuje różne mechanizmy autouzupełniania.

Dane kontaktowe

Grupa typów kontaktowych obejmuje `.emailAddress`, `.telephoneNumber`, `.fullStreetAddress` i `.city`. Te typy aktywują autouzupełnianie z kontaktów i iCloud Keychain. Pole z typem `.emailAddress` automatycznie proponuje wcześniej wprowadzone adresy email, a `.telephoneNumber` — numery telefonów z książki adresowej.

Konta

Dla pól logowania przeznaczone są .username, .password i .newPassword. Typ .username aktywuje menedżer haseł iCloud, który oferuje zapisane konta. Pole z typem .newPassword inicjuje generowanie bezpiecznego hasła przez iCloud Keychain przy pierwszym wprowadzeniu.

Wyspecjalizowane typy iOS 17+

Począwszy od iOS 17, Apple dodała .oneTimeCode dla kodów potwierdzających SMS oraz .shipmentTrackingNumber do śledzenia przesyłek. Typ .oneTimeCode automatycznie rozpoznaje kody z wiadomości i oferuje je w wierszu QuickType bez konieczności otwierania aplikacji Messages.

Każdy typ jest reprezentowany przez stałą łańcuchową, ale porównywać je należy przez operator ==, a nie przez rawValue. iOS może dodawać nowe typy w przyszłych wersjach, dlatego w switch-case zawsze używaj gałęzi default.

Dostosowanie klawiatury do typu treści

UIKeyboardType i UITextContentType działają wspólnie: keyboard type określa układ klawiatury, a content type — dodatkowe przyciski w wierszu QuickType. Jeśli określono content type, iOS może zastąpić keyboard type dla optymalnego wprowadzania. Na przykład przy typie `.emailAddress` klawiatura automatycznie pokazuje symbol @ na głównej warstwie.

Dla pola z typem .telephoneNumber iOS przełącza klawiaturę na układ telefoniczny niezależnie od ustawionego keyboard type. Tego zachowania nie można wyłączyć — system uważa priorytet content type za wyższy niż jawna konfiguracja klawiatury. Deweloperzy nie muszą duplikować ustawień obu właściwości.

Typy .URL i .emailAddress dodają do klawiatury przyciski .com i @ odpowiednio. Typ .decimalPad z content type .creditCardNumber pokazuje klawiaturę numeryczną z separatorem dziesiętnym, co jest wygodne przy wprowadzaniu kwot i numerów kart. Według Apple Human Interface Guidelines, użytkownik oczekuje, że klawiatura odpowiada typowi wprowadzanych danych, a nie odwrotnie.

Wyjątkiem jest .oneTimeCode — ten typ nie zmienia układu klawiatury, ale aktywuje wiersz QuickType z kodami z SMS. Użytkownik widzi propozycję kodu nad klawiaturą i może go wstawić jednym dotknięciem. Mechanizm działa tylko dla pól, które stają się first responder po otrzymaniu SMS.

Autouzupełnianie i pęk kluczy

Autouzupełnianie w iOS używa Text Content Type do dopasowywania pól wprowadzania do danych z iCloud Keychain i ASCredentialProviderViewController. System analizuje wszystkie pola na ekranie, określa ich typy semantyczne i oferuje odpowiednie zapisane dane. Bez prawidłowo określonych typów autouzupełnianie nie jest aktywowane.

Do działania autouzupełniania konieczne jest spełnienie trzech warunków. Po pierwsze — pole musi mieć prawidłowy UITextContentType. Po drugie — ekran musi zawierać co najmniej dwa pola z różnymi typami (np. .username i .password). Po trzecie — aplikacja musi obsługiwać Associated Domains z entitlement webcredentials do synchronizacji ze stroną internetową.

Pięk kluczy (Keychain) używa content type do klasyfikacji zapisanych wpisów. Jeśli pole jest oznaczone jako .password, system zapisuje wprowadzoną wartość w iCloud Keychain i oferuje ją przy następnym logowaniu. Pola z typem .creditCardNumber są automatycznie zapisywane w Wallet po potwierdzeniu przez Face ID.

Dla kodów jednorazowych typu .oneTimeCode iOS 17 używa nowego mechanizmu AutoFill OTP, który nie wymaga bezpośredniego dostępu do SMS. System przechwytuje kody z wiadomości na poziomie systemu operacyjnego i przekazuje je do aplikacji przez wiersz QuickType, omijając odczyt treści wiadomości przez aplikację.

Przykłady użycia w Swift

Podstawowa konfiguracja Text Content Type w Swift odbywa się przez właściwość textContentType w kodzie lub przez Interface Builder. W kodzie przypisanie stałej zajmuje jedną linię, a w IB odpowiedni typ wybiera się z listy rozwijanej w inspektorze atrybutów.

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

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

Do programowego tworzenia formularza logowania z autouzupełnianiem użyj obu pól z różnymi content type. System automatycznie powiąże je jako login i hasło. Jeśli aplikacja obsługuje logowanie biometryczne, dodaj pole z typem .username do prawidłowego rozpoznawania konta.

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

Dla pola wprowadzania kodu jednorazowego z SMS określ typ .oneTimeCode. System automatycznie zaproponuje kod w wierszu QuickType po jego otrzymaniu. Deweloper nie musi prosić o pozwolenie na odczyt SMS ani implementować własnego parsowania wiadomości.

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

Dla iOS 17+ typ .oneTimeCode obsługuje automatyczne wypełnianie bez fokusu na polu. Jeśli użytkownik otrzyma SMS z kodem, iOS oferuje go na ekranie blokady, a po odblokowaniu kod jest automatycznie wstawiany do aktywnego pola z odpowiednim content type.

Zalecenia dotyczące wyboru typu

Wybór prawidłowego typu bezpośrednio wpływa na konwersję formularza i doświadczenie użytkownika. Apple zdecydowanie zaleca określanie najbardziej konkretnego typu z dostępnych. Na przykład dla pola imienia używaj .givenName, a nie ogólnego .name — pozwoli to systemowi zaproponować autouzupełnianie z kontaktów z prawidłowym imieniem.

Unikaj częstego błędu — ustawiania .emailAddress dla pola username. Jeśli aplikacja używa email jako loginu, określ typy .username dla pola loginu i .password dla pola hasła. Typ .emailAddress jest przeznaczony wyłącznie dla pól wprowadzania email jako danych kontaktowych, a nie jako identyfikatora.

Dla formularzy z wieloma polami tego samego typu (np. dwa adresy email) używaj właściwości .textContentType dla każdego pola, ale dodaj różne identyfikatory accessibilityIdentifier. Pomoże to VoiceOver poprawnie odczytywać pola, chociaż system autouzupełniania może zaproponować tę samą opcję dla obu pól.

Testuj autouzupełnianie na rzeczywistym urządzeniu z wypełnionym pękiem kluczy. Symulator nie obsługuje iCloud Keychain w pełnym zakresie, a zachowanie autouzupełniania może się różnić. Według Apple Developer Forums (2025), najczęstsze problemy z autouzupełnianiem wynikają właśnie z nieprawidłowo określonego content type.