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

۱. مقدمه

در اندروید ۱۳، ما رابط‌های برنامه‌نویسی (API) اضافه کرده‌ایم که به عنوان پایه و اساس پشتیبانی آتی از ژست حرکتی پیش‌بینی‌کننده‌ی بازگشت عمل می‌کنند.

این ویژگی به کاربر اجازه می‌دهد قبل از تکمیل کامل یک حرکت برگشت، پیش‌نمایشی از نتیجه آن را مشاهده کند - اساساً به او اجازه می‌دهد تصمیم بگیرد که آیا در نمای فعلی بماند یا عمل را تکمیل کند و به صفحه اصلی، یک فعالیت قبلی یا یک صفحه قبلاً بازدید شده در یک WebView بازگردد. در اینجا مثالی از آنچه که به نظر می‌رسد آمده است:

برای پشتیبانی از حرکت پیش‌بینی‌کننده‌ی بازگشت، اندروید ۱۳، رابط برنامه‌نویسی کاربردی (API) پلتفرم OnBackInvokedCallback در سطح پنجره را اضافه می‌کند. این API جایگزین API KeyEvent.KEYCODE_BACK و تمام کلاس‌های پلتفرمی می‌شود که از OnBackPressed استفاده می‌کنند، که قرار است منسوخ شوند و در نسخه اصلی بعدی اندروید پس از ۱۳ نیاز به مهاجرت خواهند داشت. برای جزئیات بیشتر، به مستندات ما مراجعه کنید.

در مورد این آزمایشگاه کد، ما قصد داریم یک قطعه نظرسنجی را که یک WebView را پیاده‌سازی می‌کند، اصلاح کنیم.

هدف این آزمایشگاه کد

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

آنچه خواهید ساخت

در این آزمایشگاه کد، شما از کتابخانه‌های API اندروید ایکس برای مدیریت حرکات برگشت (Back) در برنامه‌ی آفتابگردان (Sunflower) استفاده خواهید کرد.

آنچه یاد خواهید گرفت

• چگونه فراخوانی پشت صحنه برای AndroidX را رهگیری کنیم؟
• نحوه بازگرداندن رویداد Back به سیستم
• گزینه‌های دیگر برای مدیریت حرکات برگشت
• تجربه کاربری جدید در اندروید ۱۳+ که ناوبری با ژست‌های حرکتی پیش‌بینی‌کننده‌تر برای بازگشت را ارائه می‌دهد

آنچه نیاز دارید

• اندروید استودیو
• یک دستگاه اندروید با قابلیت ناوبری اشاره‌ای (Gesture navigation)
• (اختیاری) گیت

۲. پشتیبانی از ژست پیش‌بینی‌کننده‌ی بازگشت را برنامه‌ریزی کنید

ژست پیش‌بینی‌کننده‌ی بازگشت به عقب به‌طور خودکار برای برنامه‌هایی که از پیمایش پیش‌فرض بازگشت به عقب استفاده می‌کنند، پشتیبانی می‌شود. برای فعال کردن آن، فقط باید enableOnBackInvokedCallback را انتخاب کنید، همانطور که در فعال کردن ژست پیش‌بینی‌کننده‌ی بازگشت توضیح داده شده است.

برای پیاده‌سازی این ویژگی از APIهای AndroidX استفاده کنید

این codelab برای برنامه‌هایی طراحی شده است که از قبل از AndroidX استفاده می‌کنند.

شما OnBackPressedDispatcher و OnBackPressedCallback را برای پشتیبانی از پیمایش برگشت پیاده‌سازی خواهید کرد.

گزینه‌های دیگر

بسته به نیازهای مختلفی که برنامه شما ممکن است داشته باشد، گزینه‌های دیگری برای مدیریت این ویژگی داریم:

• برای برنامه‌هایی که نمی‌توانند از AndroidX استفاده کنند - اگر این مشکل شما است، ما شما را پوشش می‌دهیم. از کلاس‌های جدید پلتفرم OnBackInvokedDispatcher و OnBackInvokedCallback که در اندروید ۱۳ معرفی می‌کنیم استفاده کنید، که به شما امکان می‌دهند بدون نیاز به AndroidX از APIهای از پیش تعیین‌شده استفاده کنید. برای جزئیات بیشتر به مستندات مراجعه کنید.
• برای برنامه‌هایی که موقتاً قادر به مهاجرت نیستند - اگر شما هم جزو این دسته هستید، ما شما را نیز تحت پوشش قرار می‌دهیم! اگر در حال حاضر امکان مهاجرت به کتابخانه‌های AndroidX یا APIهای پلتفرم وجود ندارد، می‌توانید از ژست بازگشت پیش‌بینی‌شده انصراف دهید. برای جزئیات بیشتر به مستندات مراجعه کنید.

۳. قبل از شروع

نصب اندروید استودیو

اندروید استودیو و SDK اندروید ۱۳ را نصب کنید.

تهیه یک دستگاه

شما می‌توانید از یک دستگاه اندروید مجازی یا فیزیکی برای اجرای برنامه‌ای که با استفاده از این codelab می‌سازید، استفاده کنید.

فعال کردن ناوبری با اشاره

اگر یک نمونه شبیه‌ساز جدید با سطح API 29 اجرا کنید، ممکن است ناوبری حرکتی به طور پیش‌فرض فعال نباشد. برای فعال کردن ناوبری حرکتی، تنظیمات سیستم > سیستم > ناوبری سیستم > ناوبری حرکتی را انتخاب کنید.

کد را دریافت کنید

کد را از یکی از روش‌های زیر دریافت کنید:

فایل زیپ را دانلود کنید

فایل زیپ (شروع) را دانلود کنید

دانلود از طریق گیت

اگر ترجیح می‌دهید کد را با استفاده از Git دانلود کنید، این مراحل را دنبال کنید:

1. گیت را نصب کنید.
2. برای دریافت برنامه برای این تمرین starter-code یا شاخه main را کلون کنید:

ترمینال

// Get starter app.
git clone --branch starter-code \
https://github.com/android/codelab-handling-back-navigation.git

برنامه را اجرا کنید

مراحل زیر را انجام دهید:

1. برنامه را در اندروید استودیو باز کنید و بسازید.
2. یک دستگاه مجازی جدید ایجاد کنید و Tiramisu را انتخاب کنید. همچنین می‌توانید یک دستگاه فیزیکی که API سطح ۳۳ یا بالاتر را اجرا می‌کند، متصل کنید.
3. برنامه آفتابگردان را اجرا کنید.

در مرحله بعد، یک خط مبنا ایجاد خواهید کرد و یک تجربه ضعیف را که بخشی از برنامه Sunflower است، بررسی خواهید کرد.

۴. یک خط پایه ایجاد کنید

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

نسخه آزمایشی را کاوش کنید

از صفحه اصلی شروع می‌کنیم، بیایید گردش کار اصلی برنامه شما را بررسی کنیم تا تجربه ضعیف با عملکرد WebView را بررسی کنیم.

1. در صفحه پیش‌فرض برنامه آفتابگردان، روی فهرست گیاهان (PLANT LIST) ضربه بزنید.

2. در فهرست گیاهان، روی هر گیاهی ضربه بزنید. (برای این مثال، ما از میوه آووکادو استفاده خواهیم کرد.)

3. در صفحه اطلاعات مربوط به گیاهی که روی آن ضربه زده‌اید، برای امتیازدهی به گیاه، روی نماد شست به بالا (در گوشه بالا سمت راست) ضربه بزنید.

4. شروع به پر کردن پرسشنامه کنید، اما وقتی به سوال شماره ۳ رسیدید، آن را متوقف کنید.

5. برای استفاده از حرکت برگشت، از لبه چپ (یا راست) صفحه به سمت داخل بکشید. توجه داشته باشید که به جای اینکه شما را به سوال شماره ۲ در نظرسنجی ببرد، کشیدن انگشت به عقب شما را به بخش جزئیات گیاه (در این مثال، صفحه اطلاعات آووکادو) می‌برد. این باعث می‌شود پاسخ‌های خود را از دست بدهید و تجربه کاربری ضعیفی ایجاد شود.

حالا بیایید شروع به رفع این مشکلات کنیم!

۵. فعال کردن ژست حرکتی پیش‌بینی‌کننده‌ی بازگشت

برنامه ما از قبل از AndroidX استفاده می‌کند، بنابراین شما از APIهای ناوبری Back استفاده خواهید کرد. این APIها از مدل ahead-of-time پشتیبانی می‌کنند.

هدف قرار دادن اندروید ۱۳

در پروژه استودیوی برنامه ما، پیکربندی ساخت برنامه را برای هدف قرار دادن اندروید ۱۳، همانطور که در قطعه کد زیر نشان داده شده است، به‌روزرسانی کنید.

build.gradle (پروژه)

buildscript {
   ext {
       // Sdk and tools
       minSdkVersion = 29
       compileSdkVersion = 33
       targetSdkVersion = 33
   }
...
}

وابستگی‌ها را ارتقا دهید

در build.gradle، appCompatVersion روی 1.6.0 یا بالاتر تنظیم کنید.

build.gradle (پروژه)

buildscript {
   ext {

    // App dependencies
    appCompatVersion = '1.6.0-rc01' // Built original with changes

...
}

به AndroidX Activity 1.6.0 یا بالاتر ارتقا دهید.

build.gradle (ماژول)

dependencies {
    implementation "androidx.activity:activity-ktx:1.6.0"
    ...
}

فعال کردن ژست حرکتی پیش‌بینی‌کننده‌ی بازگشت

برای فعال کردن APIهای پیش‌بینی‌کننده‌ی حرکت برگشت، enableOnBackInvokedCallback در مانیفست روی true تنظیم کنید.

فایل AndroidManifest.xml

<application
   ...
   android:enableOnBackInvokedCallback="true" // Enables this feature.
   ... >
...
</application>

تعریف و ثبت OnBackPressedCallback برای مدیریت حرکات برگشت

یک تابع فراخوانی ایجاد کنید و متد handleOnBackPressed را برای مدیریت حرکات برگشت (Back gestures) بازنویسی کنید. برای مورد استفاده در WebView، بیایید از حرکت برگشت (Back gesture) برای بازگشت به پشته صفحات استفاده کنیم تا زمانی که دیگر صفحاتی وجود نداشته باشند.

SurveyFragment.kt

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
...
  val onBackPressedCallback = object: OnBackPressedCallback(true) {
    override fun handleOnBackPressed() {
      when {
        webView.canGoBack() -> webView.goBack()
      }
    }
  }
  requireActivity().onBackPressedDispatcher
    .addCallback(onBackPressedCallback)
}

آنچه ساخته‌اید را امتحان کنید

حالا باید بررسی کنید که آیا ناوبری WebView به درستی کار می‌کند یا خیر.

1. در اندروید استودیو، برنامه را دوباره بسازید و اجرا کنید.
2. درست مانند اولین اجرای نسخه آزمایشی، روی یک گیاه دلخواه خود ضربه بزنید و سپس روی نماد لایک ضربه بزنید، سپس نظرسنجی را پر کنید تا به سوال شماره ۳ برسید.
3. برای استفاده از حرکت برگشت، از لبه چپ (یا راست) صفحه به سمت داخل بکشید. وب ویو باید شما را به سوال شماره ۲ در نظرسنجی بازگرداند.

این دقیقاً همان رفتاری است که می‌خواهیم. با این حال، ما فقط در نیمه راه هستیم - هنوز کاملاً اصلاح نشده است. بیایید ادامه دهیم تا ببینیم منظورمان چیست:

4. از سوال شماره ۲، به سوال شماره ۱ برگردید، سپس یک بار دیگر به عقب برگردید تا به بخش جزئیات گیاه برگردید.

توجه داشته باشید که نمی‌توانید از سوال شماره ۱ به قطعه جزئیات گیاه برگردید. دلیل این امر این است که:

• وب‌ویو شما با اجتناب از خروج از وب‌ویو هنگام استفاده از ناوبری در حالت بازگشت، ناوبری برگشت را مدیریت می‌کند.
• برنامه شما باید وقتی دیگر به ناوبری برگشت نیاز ندارد، آن را به سیستم برگرداند. بیایید برای رفع این مشکل به بخش بعدی برویم!

۶. رفع مشکل ژست برگشت

در مرحله قبل، برنامه ما بدون اینکه آن را به قطعه جزئیات گیاه در مراحل قبلی برگرداند، حرکت برگشت را متوقف کرد. در نتیجه، کاربران ما نمی‌توانند برنامه را ترک کنند و با یک تجربه کاربری ضعیف در WebView گیر می‌کنند.

فعال یا غیرفعال کردن پیمایش برگشت با OnBackPressedCallback

1. برای تعیین اینکه آیا ناوبری برگشت باید قطع شود یا خیر، متد doUpdateVisitedHistory را بازنویسی کنید. منطق مدیریت ناوبری برگشت به شرح زیر است:
   • اگر صفحات بیشتری برای بازگشت به WebView وجود دارد ( webView.canGoBack() )، متد OnBackPressedCallback باید فعال شود.
   • برعکس، اگر صفحات بیشتری برای بازگشت به آنها در WebView وجود نداشته باشد، متد OnBackPressedCallback باید غیرفعال شود. در نتیجه، ژست Back به بالاترین قطعه در پشته پشتی برمی‌گردد.

SurveyFragment.kt

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
  ...
  requireActivity().onBackPressedDispatcher
    .addCallback(onBackPressedCallback)

  disableOnBackPressedCallback(webView, onBackPressedCallback)
  }
}

private fun disableOnBackPressedCallback(webView: WebView, onBackPressedCallback: OnBackPressedCallback) {
  webView.webViewClient = object: WebViewClient() {
    override fun doUpdateVisitedHistory(view: WebView?, url: String?, isReload: Boolean) {
      // Disable the on-back press callback if there are no more questions in the
      // WebView to go back to, allowing us to exit the WebView and go back to
      // the fragment.
      onBackPressedCallback.isEnabled = webView.canGoBack()

    }
  }
}

2. برای آزمایش مجدد وب‌ویو، یک بار دیگر نظرسنجی را پر کنید تا به سوال شماره ۳ برسید.
3. با استفاده از حرکات برگشت، به نمای جزئیات گیاه برگردید. باید بتوانید این کار را بدون مشکل انجام دهید.

توجه داشته باشید که اکنون می‌توانیم از WebView خارج شویم و بدون گیر کردن، به بررسی قطعه جزئیات گیاه برگردیم.

در اینجا مثالی از چگونگی وضعیت همه اینها پس از رفع مشکل آورده شده است:

پیش‌نمایش انیمیشن جدید ژست بازگشت به خانه

در نسخه‌های بعدی اندروید، همانطور که در انیمیشن زیر نشان داده شده است، حرکت پیش‌بینی‌کننده‌ی بازگشت را تجربه خواهید کرد. اکیداً توصیه می‌کنیم که در اسرع وقت اجرای این تغییرات را شروع کنید!

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

۷. تبریک

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

آنچه ما پوشش داده‌ایم

• چگونه برنامه خود را برای شروع استفاده از APIهایی که از حرکت پیش‌بینی‌کننده‌ی بازگشت پشتیبانی می‌کنند، فعال کنیم؟
• نحوه‌ی رهگیری فراخوانی در پشت صحنه برای AndroidX
• نحوه بازگرداندن ناوبری برگشت به سیستم
• گزینه‌های دیگر برای مدیریت حرکات برگشت
• تجربه کاربری جدید در اندروید ۱۳، ژست حرکتی پیش‌بینی‌کننده‌تری برای بازگشت ارائه می‌دهد.

آزمایشگاه کد تکمیل شده

فایل زیپ را دانلود کنید (تکمیل شده)

// Get completed app.
git clone --branch main \
https://github.com/android/codelab-handling-back-navigation.git

مواد اضافی

• راهنمای توسعه‌دهنده

اسناد مرجع

• OnBackPressedDispatcher و OnBackPressedCallback
• OnBackInvokedDispatcher و OnBackInvokedCallback