Keyboard Avoidance — الجوهر، طرق التطبيق وإزاحة الواجهة

ما هو Keyboard Avoidance

Keyboard Avoidance هو مجموعة من التقنيات التي تضمن رؤية حقل الإدخال النشط عند ظهور لوحة المفاتيح النظامية على iOS. المشكلة الأساسية: تشغل لوحة المفاتيح ما يصل إلى 50% من الشاشة وتغطي النصف السفلي من الواجهة، بما في ذلك حقول النص وأزرار الإرسال والعناصر الأخرى.

هناك ثلاث طرق رئيسية للتطبيق: الإدارة اليدوية عبر Keyboard Notifications (الطريقة التقليدية، تعمل منذ iOS 3.0)، استخدام UIScrollView مع التمرير التلقائي (موصى به من Apple)، و Keyboard Layout Guide (الطريقة الحديثة مع iOS 15+). يعتمد الاختيار على الحد الأدنى من إصدار iOS المدعوم وتعقيد الواجهة.

وفقاً لـ Apple، فإن عدم وجود Keyboard Avoidance هو أحد أكثر أسباب رفض التطبيقات شيوعاً أثناء المراجعة إذا كانت حقول النص مغطاة بالكامل بلوحة المفاتيح. تشترط App Store Guidelines صراحةً أن تبقى جميع العناصر التفاعلية قابلة للوصول أثناء الإدخال النشط.

لماذا لا يقوم iOS بذلك تلقائياً

لا يمكن لـ iOS تحديد العنصر الذي يجب أن يبقى مرئياً تلقائياً لأنه لا يعرف دلالات الواجهة. في نموذج بسيط بحقل نص واحد، يكفي تحريك الشاشة بأكملها لأعلى. في واجهة معقدة تحتوي على لوحات مخصصة وأزرار عائمة وأقسام متعددة، يلزم منطق سلوك مختلف.

بالإضافة إلى ذلك، بعض التطبيقات لا تزيح المحتوى عمداً — على سبيل المثال، حاسبات لوحة المفاتيح أو المحررات حيث تكون لوحة المفاتيح جزءاً من مساحة العمل. يترك iOS القرار للمطور، مع توفير API مرنة لأي سيناريو.

إشعارات إطار لوحة المفاتيح

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. تتتبع تلقائياً موضع لوحة المفاتيح وتحدث قيود Auto Layout التي تربط الجزء السفلي من الواجهة بالحافة العلوية للوحة المفاتيح.

لاستخدامها، قم بتفعيل layout guide على UIScrollView أو UIStackView وأرفق القيد السفلي للمحتوى به. لا حاجة لعمل يدوي مع الإشعارات أو حساب الارتفاع أو الرسوم المتحركة — يقوم النظام بكل شيء تلقائياً، مع مزامنة الرسوم المتحركة مع ظهور وإخفاء لوحة المفاتيح.

// تفعيل Keyboard Layout Guide (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// تثبيت القيد السفلي للجزء العلوي من لوحة المفاتيح
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard هي خاصية تحدد ما إذا كان يجب أن يستجيب الدليل للوحة مفاتيح يمكن فصلها عن الحافة السفلية (على iPad). عيّنها إلى true فقط إذا كانت الواجهة تعمل بشكل صحيح مع لوحة مفاتيح عائمة. بالنسبة لـ iPhone، يتم تجاهل هذه الخاصية — لوحة المفاتيح مثبتة دائماً على الحافة السفلية.

UIScrollView ولوحة المفاتيح

UIScrollView هو حاوية توصي Apple باستخدامها كأساس لـ 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، توصي Apple باستخدام 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. قم بتحديث التخطيط عبر layoutIfNeeded داخل كتلة animate للحصول على انتقال سلس.

عند استخدام UIStackView، فإن تغيير قيود الهامش السفلي يعمل أيضاً: يقوم stack view بإعادة توزيع العناصر الفرعية تلقائياً. ومع ذلك، إذا كان stack view داخل UIScrollView، فمن الأفضل إدارة contentInset لـ scroll view نفسه، بدلاً من القيود داخله.

حلول الطرف الثالث لـ Keyboard Avoidance

IQKeyboardManager هي المكتبة الأكثر شهرة (أكثر من 16,000 نجمة على GitHub) والتي تنفذ Keyboard Avoidance تلقائياً دون سطر واحد من الكود في وحدة التحكم. تستخدم method swizzling لتتبع حقول النص وترفع المحتوى تلقائياً عند ظهور لوحة المفاتيح.

توفر المكتبة إعدادات مرنة: يمكنك تحديد المسافة بين الحقل ولوحة المفاتيح، تمكين/تعطيل لوحدات تحكم محددة، وتهيئة السلوك لـ UITextView وطرق العرض المخصصة للإدخال. ومع ذلك، قد يتعارض method swizzling مع المكتبات الأخرى، ولا توصي Apple بهذا النهج لكود الإنتاج بسبب الآثار الجانبية غير المتوقعة.

تشمل البدائل TPKeyboardAvoiding (مكتبة خفيفة، ~2000 نجمة) و KeyboardManager من المجتمع. للمشاريع الحديثة، توصي Apple باستخدام الأدوات المدمجة في iOS 15+، وللمشاريع ذات الإصدار الأدنى — UIScrollView مع contentInset، وهو الحل المدمج الأكثر موثوقية.