Keyboard Avoidance — ماهیت، روش‌های پیاده‌سازی و جابجایی رابط

Keyboard Avoidance چیست

Keyboard Avoidance — مجموعه‌ای از تکنیک‌ها است که هنگام ظاهر شدن صفحه‌کلید سیستمی در iOS، دید فیلد ورودی فعال را تضمین می‌کند. مشکل اساسی: صفحه‌کلید تا ۵۰٪ از صفحه را اشغال می‌کند و نیمه پایینی رابط از جمله فیلدهای متنی، دکمه‌های ارسال و سایر عناصر را می‌پوشاند.

سه رویکرد اصلی برای پیاده‌سازی وجود دارد: مدیریت دستی از طریق Keyboard Notifications (روش کلاسیک، از iOS 3.0 کار می‌کند)، استفاده از UIScrollView با پیمایش خودکار (توصیه شده توسط اپل) و Keyboard Layout Guide (روش مدرن از iOS 15+). انتخاب به حداقل نسخه پشتیبانی شده iOS و پیچیدگی رابط بستگی دارد.

به گفته اپل، عدم وجود Keyboard Avoidance یکی از شایع‌ترین دلایل رد برنامه‌ها در بازبینی است، اگر فیلدهای متنی کاملاً توسط صفحه‌کلید پوشانده شوند. دستورالعمل‌های App Store به وضوح要求 می‌کنند که همه عناصر تعاملی هنگام ورود فعال قابل دسترس باقی بمانند.

چرا iOS این کار را خودکار انجام نمی‌دهد

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

علاوه بر این، برخی برنامه‌ها عمداً محتوا را جابجا نمی‌کنند — برای مثال، ماشین‌حساب‌های صفحه‌کلیدی یا ویرایشگرهایی که صفحه‌کلید بخشی از فضای کاری است. iOS تصمیم را به توسعه‌دهنده واگذار می‌کند و APIهای انعطاف‌پذیری برای هر سناریو ارائه می‌دهد.

Keyboard Frame Notifications

UIKeyboardWillShowNotification — اعلان اصلی که iOS قبل از ظاهر شدن صفحه‌کلید ارسال می‌کند. این اعلان شامل CGRect با موقعیت نهایی صفحه‌کلید در دیکشنری UIResponder.keyboardFrameEndUserInfoKey و همچنین مدت زمان انیمیشن در UIResponder.keyboardAnimationDurationUserInfoKey است.

مدیریت‌کننده اعلان باید همپوشانی بین فیلد متنی فعال و صفحه‌کلید را محاسبه کند، سپس فاصله پایین (contentInset یا frame) ظرف را تغییر دهد. اگر فیلد زیر لبه بالایی صفحه‌کلید قرار دارد، محتوا به اندازه همپوشانی به بالا جابجا می‌شود. هنگام مخفی شدن صفحه‌کلید، فاصله به مقدار اولیه بازمی‌گردد.

@objc func keyboardWillShow(_ notification: Notification) {
    guard let keyboardFrame = notification
        .userInfo?[UIResponder.keyboardFrameEndUserInfoKey]
        as? CGRect else { return }
    
    let keyboardHeight = keyboardFrame.height
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
}

هنگام استفاده از اعلان‌ها، مهم است که انیمیشن را همگام با صفحه‌کلید سیستم انجام دهید. iOS منحنی انیمیشن (UIResponder.keyboardAnimationCurveUserInfoKey) و مدت زمان را منتقل می‌کند. از UIView.animate با این پارامترها استفاده کنید تا محتوا به آرامی و همزمان با ظاهر شدن صفحه‌کلید جابجا شود.

Keyboard Layout Guide در iOS 15+

UIScrollView.keyboardLayoutGuide — یک API مدرن برای Keyboard Avoidance است که در iOS 15 معرفی شده است. این API به طور خودکار موقعیت صفحه‌کلید را ردیابی می‌کند و محدودیت‌های Auto Layout را که قسمت پایین رابط را به لبه بالایی صفحه‌کلید متصل می‌کنند، به‌روزرسانی می‌کند.

برای استفاده، کافی است layout guide را در UIScrollView یا UIStackView فعال کنید و محدودیت پایین محتوا را به آن متصل کنید. هیچ کار دستی با اعلان‌ها، محاسبه ارتفاع و انیمیشن required نیست — سیستم همه چیز را خودکار انجام می‌دهد و انیمیشن را با ظاهر و مخفی شدن صفحه‌کلید همگام می‌کند.

// فعال‌سازی Keyboard Layout Guide (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// متصل کردن محدودیت پایین به بالای صفحه‌کلید
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard — ویژگی‌ای که تعیین می‌کند آیا guide باید به صفحه‌کلیدی که ممکن است از لبه پایین جدا شود (در iPad) واکنش نشان دهد. فقط در صورتی true کنید که رابط به درستی کار می‌کند با صفحه‌کلید شناور. برای iPhone این ویژگی نادیده گرفته می‌شود — صفحه‌کلید همیشه به لبه پایین متصل است.

UIScrollView و صفحه‌کلید

UIScrollView — ظرفی است که اپل توصیه می‌کند به عنوان پایه Keyboard Avoidance استفاده شود. وقتی صفحه‌کلید ظاهر می‌شود، scroll view contentInset.bottom خود را افزایش می‌دهد و امکان پیمایش محتوا به بالا و قابل مشاهده کردن فیلد فعال را فراهم می‌کند.

روش کلیدی — scrollRectToVisible که به صورت برنامه‌ای scroll view را پیمایش می‌کند تا مستطیل مشخص شده (فیلد متنی فعال) در ناحیه قابل مشاهده قرار گیرد. با ترکیب تغییر contentInset با فراخوانی scrollRectToVisible، تضمین می‌کنید که فیلد نه تنها پوشانده نشده، بلکه در قسمت بالای ناحیه قابل مشاهده قرار دارد.

func adjustScrollForKeyboard(
    keyboardHeight: CGFloat,
    activeField: UIView
) {
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
    
    var visibleRect = view.frame
    visibleRect.size.height -= keyboardHeight
    
    if activeField.frame.origin.y > visibleRect.maxY {
        scrollView.scrollRectToVisible(
            activeField.frame, animated: true
        )
    }
}

برای UIViewController با UITableView، اپل استفاده از UITableViewController را توصیه می‌کند که به طور خودکار contentInset را هنگام ظاهر شدن صفحه‌کلید تصحیح می‌کند. اگر از UIViewController با جدول اضافه شده استفاده می‌کنید، باید Keyboard Avoidance را دستی پیاده‌سازی کنید — UITableViewController این رفتار را برای کنترلرهای سفارشی ارائه نمی‌دهد.

Auto Layout و Keyboard Avoidance

Auto Layout امکان پیاده‌سازی Keyboard Avoidance بدون برنامه‌نویسی انیمیشن را فراهم می‌کند — کافی است فعالیت (isActive) یک محدودیت خاص را تغییر دهید یا ثابت آن را در پاسخ به اعلان صفحه‌کلید به‌روزرسانی کنید.

طرح معمول: یک IBOutlet NSLayoutConstraint برای فاصله پایین scroll view یا محتوا ایجاد کنید و در مدیریت‌کننده keyboardWillShow، constraint.constant = keyboardHeight را تنظیم کنید و در keyboardWillHide آن را به 0 بازنشانی کنید. layout را از طریق layoutIfNeeded در داخل بلوک animate برای انتقال روان به‌روزرسانی کنید.

هنگام استفاده از UIStackView، تغییر محدودیت‌های فاصله پایین نیز کار می‌کند: stack view عناصر فرزند را به طور خودکار توزیع می‌کند. با این حال، اگر stack view در داخل UIScrollView قرار دارد، بهتر است contentInset خود scroll view را مدیریت کنید، نه محدودیت‌های داخل آن.

راه‌حل‌های شخص ثالث برای Keyboard Avoidance

IQKeyboardManager — محبوب‌ترین کتابخانه (بیش از ۱۶,۰۰۰ ستاره در GitHub) است که Keyboard Avoidance خودکار را بدون حتی یک خط کد در کنترلر پیاده‌سازی می‌کند. این کتابخانه از method swizzling برای ردیابی فیلدهای متنی استفاده می‌کند و به طور خودکار محتوا را هنگام ظاهر شدن صفحه‌کلید بالا می‌برد.

این کتابخانه تنظیمات انعطاف‌پذیری ارائه می‌دهد: می‌توان فاصله بین فیلد و صفحه‌کلید را مشخص کرد، برای کنترلرهای خاص فعال/غیرفعال کرد، رفتار برای UITextView و input viewهای سفارشی را پیکربندی کرد. با این حال، method swizzling ممکن است با سایر کتابخانه‌ها تداخل داشته باشد و اپل این رویکرد را برای کد تولید به دلیل عوارض جانبی غیرقابل پیش‌بینی توصیه نمی‌کند.

جایگزین‌ها شامل TPKeyboardAvoiding (کتابخانه سبک، ~۲۰۰۰ ستاره) و KeyboardManager از جامعه است. برای پروژه‌های مدرن، اپل استفاده از ابزارهای داخلی iOS 15+ را توصیه می‌کند و برای پروژه‌های با نسخه پایین‌تر — UIScrollView با contentInset که قابل اعتمادترین راه‌حل داخلی است.