توفير تنقل مخصّص إلى الخلف

ينتقل المستخدمون للخلف عبر الشاشات باستخدام التنقّل للخلف. تحتوي معظم أجهزة Android على زر الرجوع، سواء كان زرًا ماديًا أو برنامجيًا أو مستندًا إلى الإيماءات. عادةً، لا يجب إضافة زر الرجوع إلى تطبيقك. ومع ذلك، تستخدم أجهزة Android Automotive System (AAOS) في وضع التوافق زر الرجوع في النظام. وتتولى هذه العناصر عملية التنقّل، لذا ليس عليك إضافة عناصر خاصة بك. لمعرفة التفاصيل، يُرجى الاطّلاع على وضع التوافق مع AAOS.

يحتفظ Android بمجموعة الرجوع للوجهات أثناء تنقّل المستخدم في تطبيقك. يسمح ذلك عادةً لنظام Android بالتنقّل بشكل صحيح إلى الوجهات السابقة عند الضغط على زر الرجوع. ومع ذلك، هناك بعض الحالات التي قد يحتاج فيها تطبيقك إلى تنفيذ سلوك "الرجوع" الخاص به لأجل تقديم أفضل تجربة ممكنة للمستخدم. على سبيل المثال، عند استخدام WebView، قد تحتاج إلى إلغاء السلوك التلقائي لزر الرجوع للسماح للمستخدم بالتنقّل للخلف في سجلّ تصفّح الويب بدلاً من الشاشات السابقة في تطبيقك.

تنفيذ ميزة التنقّل للخلف المخصّصة

ComponentActivity، وهو القاعدة للصفّين FragmentActivity وAppCompatActivity، تسمح لك بالتحكم في سلوك زر الرجوع باستخدام OnBackPressedDispatcher، ويمكنك استرجاعه من خلال استدعاء getOnBackPressedDispatcher().

يتحكّم العنصر OnBackPressedDispatcher في كيفية إرسال أحداث زر الرجوع إلى عنصر OnBackPressedCallback واحد أو أكثر. يأخذ المُنشئ لـ OnBackPressedCallback قيمة منطقية لحالة الالتفاف المفعَّلة الأولية. فقط عند تفعيل ميزة "الاتصال مرة أخرى" (أي isEnabled() يعرض القيمة true) سيطلب المشغِّل من handleOnBackPressed() معالجة حدث زر الرجوع. يمكنك تغيير الحالة المفعّلة من خلال الاتصال بالرقم setEnabled().

تتم إضافة عمليات تسجيل المكالمات من خلال طرق addCallback. ننصحك بشدة باستخدام addCallback() الطريقة التي تستخدِم LifecycleOwner. يضمن ذلك عدم إضافة OnBackPressedCallback إلا عندما يكون LifecycleOwner هو Lifecycle.State.STARTED. يزيل النشاط أيضًا عمليات الاستدعاء المسجّلة عند تدمير LifecycleOwner المرتبط بها، ما يمنع تسرُّب الذاكرة ويجعلها مناسبة للاستخدام في الأجزاء أو مالكي دورة الحياة الآخرين الذين لديهم مدة استخدام قصيرة مقارنةً بالنشاط.

في ما يلي مثال على تنفيذ ردّ الاتصال:

class MyFragment : Fragment() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // This callback will only be called when MyFragment is at least Started.
        val callback = requireActivity().onBackPressedDispatcher.addCallback(this) {
            // Handle the back button event
        }

        // The callback can be enabled or disabled here or in the lambda
    }
    ...
}

public class MyFragment extends Fragment {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // This callback will only be called when MyFragment is at least Started.
        OnBackPressedCallback callback = new OnBackPressedCallback(true /* enabled by default */) {
            @Override
            public void handleOnBackPressed() {
                // Handle the back button event
            }
        };
        requireActivity().getOnBackPressedDispatcher().addCallback(this, callback);

        // The callback can be enabled or disabled here or in handleOnBackPressed()
    }
    ...
}

يمكنك توفير طلبات اتصال متعددة من خلال addCallback(). عند إجراء ذلك، يتمّ استدعاء وظائف الاستدعاء بالترتيب العكسي الذي تمت فيه إضافتها، وتكون وظيفة الاستدعاء التي تمت إضافتها مؤخرًا هي الأولى التي تحصل على فرصة لمعالجة حدث زرّ الرجوع. على سبيل المثال، إذا أضفت ثلاث وظائف استدعاء مُعاد تسميتها one وtwo وthree بالترتيب، سيتمّ استدعاؤها بالترتيب التالي: three وtwo وone، على التوالي.

تتّبع وظائف ردّ المكالمات نمط سلسلة المسؤوليات. لا يتمّ استدعاء كلّ أسلوب استدعاء في السلسلة إلّا إذا لم يكن الأسلوب السابق للاستدعاء مفعّلاً. وهذا يعني أنّه في المثال السابق، لن يتمّ استدعاء طلب معاودة الاتصال two إلا إذا لم يكن طلب معاودة الاتصال three مفعّلاً. ولن يتمّ استدعاء دالة معاودة الاتصال one إلا إذا لم تكن دالة معاودة الاتصال two مفعّلة، وهكذا.

يُرجى العلم أنّه عند الإضافة من خلال addCallback()، لا تتم إضافة دالة الاستدعاء إلى سلسلة المسؤوليات إلى أن يدخل LifecycleOwner الحالة Lifecycle.State.STARTED.

ننصح بشدة بتغيير حالة التفعيل في OnBackPressedCallback للتغييرات المؤقتة لأنّ ذلك يحافظ على الترتيب الموضّح أعلاه، وهو أمر مهم بشكل خاص إذا كانت لديك عمليات استدعاء مسجّلة في عدة أصحاب دورة حياة متداخلة مختلفة.

في الحالات التي تريد فيها إزالة OnBackPressedCallback بالكامل، عليك الاتصال بـ remove(). ومع ذلك، لا يكون هذا الإجراء ضروريًا عادةً لأنّ وظائف الاستدعاء تتم إزالتها تلقائيًا عند إتلاف LifecycleOwner المرتبط بها.

Activity onBackPressed()

إذا كنت تستخدم رمز onBackPressed() لمعالجة أحداث زر الرجوع، ننصحك باستخدام رمز OnBackPressedCallback بدلاً منه. ومع ذلك، إذا لم تتمكّن من إجراء هذا التغيير، تنطبق القواعد التالية:

• يتم تقييم جميع عمليات معاودة الاتصال المسجّلة من خلال addCallback عند الاتصال بالرقم super.onBackPressed().
• في الإصدار 12 من Android (المستوى 32 من واجهة برمجة التطبيقات) والإصدارات الأقدم، يتم دائمًا استدعاء onBackPressed بغض النظر عن أي نُسخ مسجّلة من OnBackPressedCallback.