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، اپل توصیه می‌کند برای هر فیلد متنی در رابط کاربری 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 به بعد، اپل .oneTimeCode را برای کدهای تأیید پیامکی و .shipmentTrackingNumber را برای رهگیری بسته‌ها اضافه کرد. نوع .oneTimeCode به طور خودکار کدهای پیامک را تشخیص می‌دهد و بدون نیاز به باز کردن برنامه Messages در خط QuickType ارائه می‌دهد.

هر نوع با یک ثابت رشته‌ای نمایش داده می‌شود، اما مقایسه آنها باید از طریق عملگر == انجام شود، نه از طریق rawValue. iOS ممکن است در نسخه‌های آینده انواع جدیدی اضافه کند، بنابراین در switch-case همیشه از شاخه default استفاده کنید.

تطبیق صفحه کلید با نوع محتوا

UIKeyboardType و UITextContentType با هم کار می‌کنند: keyboard type چیدمان صفحه کلید را تعیین می‌کند و content type — دکمه‌های اضافی در خط QuickType. اگر content type تعیین شده باشد، iOS می‌تواند keyboard type را برای ورودی بهینه لغو کند. برای مثال، با نوع `.emailAddress` صفحه کلید به طور خودکار نماد @ را در لایه اصلی نشان می‌دهد.

برای فیلد با نوع .telephoneNumber iOS بدون توجه به keyboard type تنظیم‌شده، صفحه کلید را به چیدمان تلفنی تغییر می‌دهد. این رفتار را نمی‌توان غیرفعال کرد — سیستم اولویت content type را بالاتر از تنظیم صریح صفحه کلید می‌داند. توسعه‌دهندگان نیازی به تکرار تنظیمات هر دو ویژگی ندارند.

انواع .URL و .emailAddress به ترتیب دکمه‌های .com و @ را به صفحه کلید اضافه می‌کنند. نوع .decimalPad با content type .creditCardNumber صفحه کلید عددی با جداکننده اعشاری نشان می‌دهد که برای وارد کردن مبالغ و شماره کارت‌ها مناسب است. طبق Apple Human Interface Guidelines، کاربر انتظار دارد که صفحه کلید با نوع داده‌های ورودی مطابقت داشته باشد، نه برعکس.

.oneTimeCode استثناست — این نوع چیدمان صفحه کلید را تغییر نمی‌دهد، اما خط QuickType را با کدهای پیامک فعال می‌کند. کاربر پیشنهاد کد را بالای صفحه کلید می‌بیند و می‌تواند با یک ضربه آن را وارد کند. این مکانیزم فقط برای فیلدهایی کار می‌کند که پس از دریافت پیامک first responder می‌شوند.

تکمیل خودکار و دسته کلید

تکمیل خودکار در iOS از Text Content Type برای مطابقت فیلدهای ورودی با داده‌های iCloud Keychain و ASCredentialProviderViewController استفاده می‌کند. سیستم تمام فیلدهای روی صفحه را تحلیل می‌کند، انواع معنایی آنها را تعیین می‌کند و داده‌های ذخیره‌شده مربوطه را پیشنهاد می‌دهد. بدون انواع مشخص‌شده به درستی، تکمیل خودکار فعال نمی‌شود.

برای کار تکمیل خودکار سه شرط باید برآورده شود. اول — فیلد باید UITextContentType صحیح داشته باشد. دوم — صفحه باید حداقل دو فیلد با انواع متفاوت داشته باشد (مثلاً .username و .password). سوم — برنامه باید از Associated Domains با entitlement webcredentials برای همگام‌سازی با وب‌سایت پشتیبانی کند.

دسته کلید (Keychain) از content type برای طبقه‌بندی Records ذخیره‌شده استفاده می‌کند. اگر فیلد به عنوان .password علامت‌گذاری شده باشد، سیستم مقدار وارد شده را در iCloud Keychain ذخیره می‌کند و در ورود بعدی پیشنهاد می‌دهد. فیلدهای با نوع .creditCardNumber پس از تأیید از طریق Face ID به طور خودکار در Wallet ذخیره می‌شوند.

برای کدهای یکبار مصرف نوع .oneTimeCode، iOS 17 از مکانیزم جدید AutoFill OTP استفاده می‌کند که نیاز به دسترسی مستقیم به پیامک ندارد. سیستم کدهای پیامک را در سطح سیستم عامل رهگیری می‌کند و بدون نیاز به خواندن محتوای پیامک توسط برنامه، از طریق خط QuickType به برنامه منتقل می‌کند.

نمونه‌های استفاده در Swift

پیکربندی پایه Text Content Type در Swift از طریق ویژگی 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
    }
}

برای فیلد ورود کد یکبار مصرف از SMS نوع .oneTimeCode را مشخص کنید. سیستم به طور خودکار پس از دریافت کد، آن را در خط QuickType پیشنهاد می‌دهد. توسعه‌دهنده نیازی به درخواست مجوز خواندن SMS یا پیاده‌سازی تجزیه پیام‌های خود ندارد.

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

برای iOS 17+ نوع .oneTimeCode از تکمیل خودکار بدون فوکوس روی فیلد پشتیبانی می‌کند. اگر کاربر پیامکی با کد دریافت کند، iOS آن را روی صفحه قفل پیشنهاد می‌دهد و پس از باز کردن قفل، کد به طور خودکار در فیلد فعال با content type مربوطه درج می‌شود.

توصیه‌های انتخاب نوع

انتخاب نوع صحیح به طور مستقیم بر نرخ تبدیل فرم و تجربه کاربری تأثیر می‌گذارد. اپل به شدت توصیه می‌کند خاص‌ترین نوع موجود را مشخص کنید. برای مثال، برای فیلد نام از .givenName استفاده کنید، نه .name عمومی — این به سیستم اجازه می‌دهد تکمیل خودکار از مخاطبین با نام صحیح را پیشنهاد دهد.

از خطای رایج — تنظیم .emailAddress برای فیلد username — اجتناب کنید. اگر برنامه از ایمیل به عنوان نام کاربری استفاده می‌کند، انواع .username را برای فیلد نام کاربری و .password را برای فیلد رمز عبور مشخص کنید. نوع .emailAddress صرفاً برای فیلدهای ورود ایمیل به عنوان اطلاعات تماس در نظر گرفته شده است، نه به عنوان شناسه.

برای فرم‌های با چندین فیلد از یک نوع (مثلاً دو آدرس ایمیل) از ویژگی .textContentType برای هر فیلد استفاده کنید، اما شناسه‌های accessibilityIdentifier متفاوت اضافه کنید. این به VoiceOver کمک می‌کند فیلدها را به درستی اعلام کند، هرچند سیستم تکمیل خودکار ممکن است همان گزینه را برای هر دو فیلد پیشنهاد دهد.

تکمیل خودکار را روی دستگاه واقعی با دسته کلید پر شده آزمایش کنید. شبیه‌ساز از iCloud Keychain به طور کامل پشتیبانی نمی‌کند و رفتار تکمیل خودکار ممکن است متفاوت باشد. طبق Apple Developer Forums (2025)، رایج‌ترین مشکلات تکمیل خودکار دقیقاً به دلیل content type نادرست رخ می‌دهد.