ارائه پیمایش به عقب سفارشی

پیمایش به عقب روشی است که کاربران ازطریق آن در سابقه صفحه‌هایی که قبلاً بازدید کرده‌اند به عقب حرکت می‌کنند. همه دستگاه‌های Android دکمه «برگشت» را برای این نوع پیمایش ارائه می‌دهند، بنابراین دکمه «برگشت» را به میانای کاربر برنامه‌تان اضافه نکنید. بسته به دستگاه Android کاربر، این دکمه ممکن است دکمه‌ای فیزیکی یا دکمه‌ای نرم‌افزاری باشد.

Android با پیمایش کاربر در سراسر برنامه شما، پشته قبلی‌ها از مقصدها را حفظ می‌کند. این کار به Android امکان می‌دهد وقتی دکمه «برگشت» فشار داده می‌شود، به‌درستی به مقصدهای قبلی پیمایش کند. بااین‌حال، در چند مورد ممکن است برنامه‌تان برای ارائه بهترین تجربه کاربری ممکن نیاز به پیاده‌سازی رفتار «برگشت» خودش داشته باشد.

برای مثال، هنگام استفاده از WebView، ممکن است بخواهید رفتار پیش‌فرض دکمه «برگشتن» را لغو کنید تا به کاربر اجازه دهید به‌جای صفحه‌های قبلی در برنامه‌تان، در سابقه مرور وب خود به عقب پیمایش کند.

Android 13 و نسخه‌های بالاتر شامل اشاره برگشت پیش‌گویانه برای دستگاه‌های Android است. برای کسب اطلاعات بیشتر درباره این ویژگی، افزودن پشتیبانی برای اشاره برگشت پیش‌گویانه را بررسی کنید.

پیاده‌سازی پیمایش به عقب سفارشی

ComponentActivity، کلاس پایه برای FragmentActivity و AppCompatActivity، به شما امکان می‌دهد بااستفاده از OnBackPressedDispatcher آن، که می‌توانید با فراخوانی getOnBackPressedDispatcher() آن را بازیابی کنید، رفتار دکمه «برگشت» را کنترل کنید.

OnBackPressedDispatcher نحوه ارسال رویدادهای دکمه «برگشت» به یک یا چند شیء OnBackPressedCallback را کنترل می‌کند. سازنده OnBackPressedCallback یک مقدار بولی برای وضعیت فعال اولیه می‌گیرد. وقتی فراخوانی برگشتی فعال باشد—یعنی isEnabled() true را برمی‌گرداند—توزیع‌کننده handleOnBackPressed() فراخوانی برگشتی را برای رسیدگی به رویداد دکمه «برگشت» فراخوانی می‌کند. می‌توانید با فراخوانی setEnabled()، وضعیت فعال را تغییر دهید.

فراخوانی‌های برگشتی بااستفاده از روش‌های addCallback اضافه می‌شوند. توصیه می‌کنیم از روش addCallback() استفاده کنید که LifecycleOwner می‌گیرد. این کار تضمین می‌کند که OnBackPressedCallback فقط زمانی اضافه می‌شود که LifecycleOwner Lifecycle.State.STARTED باشد. این فعالیت همچنین فراخوان‌های ثبت‌شده را وقتی که LifecycleOwner مرتبط با آن‌ها ازبین می‌رود برمی‌دارد، که این کار از نشت حافظه جلوگیری می‌کند و LifecycleOwner را برای استفاده در قطعه‌ها یا دیگر مالکان چرخه حیات که طول عمر کوتاه‌تری نسبت‌به فعالیت دارند مناسب می‌کند.

در اینجا یک نمونه پیاده‌سازی فراخوانی برگشتی آورده شده است:

class MyFragment : Fragment() {

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

        // This callback is only 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 is only 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() ارزیابی می‌شوند.
• در Android نسخه ۱۲ (سطح میانای برنامه‌سازی کاربردی ۳۲) و پایین‌تر، onBackPressed همیشه فراخوانی می‌شود، صرف‌نظر از اینکه نمونه‌های ثبت‌شده‌ای از OnBackPressedCallback وجود داشته باشد یا نه.