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

پیمایش به عقب روشی است که کاربران ازطریق آن در سابقه صفحه‌هایی که قبلاً بازدید کرده‌اند به عقب حرکت می‌کنند. همه دستگاه‌های 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 12 (سطح میانای برنامه‌سازی کاربردی ۳۲) و پایین‌تر، onBackPressed همیشه فراخوانی می‌شود، صرف‌نظر از هر نمونه ثبت‌شده‌ای از OnBackPressedCallback.