روال‌های مطلوب تعامل با نقشه ناوبری

این صفحه روال‌های مطلوب برای تعامل با نقشه «ناوبری» را در برنامه‌تان توضیح می‌دهد.

هرزمان ممکن بود، به‌جای NavigationView از NavigationFragment استفاده کنید

NavigationFragment NavigationView را دربرمی‌گیرد و به‌طور خودکار فراخوانی‌های چرخه حیات آن را مدیریت می‌کند، بنابراین لازم نیست خودتان آن‌ها را مدیریت کنید. این رویکرد کمتر مستعد خطا است و روش توصیه‌شده برای استفاده از پیمایش در برنامه شما است. هنگام استفاده از NavigationFragment، رویدادهای چرخه حیات NavigationView را مستقیماً فراخوانی نکنید.

درصورت استفاده از NavigationView، هنگام فراخوانی روش‌های چرخه حیات از ترتیب دقیق استفاده کنید

NavigationView میزبان نقشه «ناوبری» است و رویدادهای چرخه حیات را به‌عنوان فعالیت‌ها و قطعه‌های Android به‌دقت دنبال می‌کند و هنگام فراخوانی این رویدادهای چرخه حیات، کنش‌های خاصی انجام می‌دهد. ‫NavigationView چندین مقداردهی اولیه را در NavigationView#onCreate و NavigationView#onStart اجرا می‌کند و پاک‌سازی‌ها را در NavigationView#onStop و NavigationView#onDestroy انجام می‌دهد، و همچنین زمانی که رویدادهای چرخه حیات دیگر پردازش می‌شوند.

روش‌های چرخه حیات NavigationView همان معنایی را دارند که برای فعالیت‌ها یا قطعات Android دارند. برای مثال، onCreate از NavigationView تقریباً به فراخوانی‌های برگشت چرخه حیات از فعالیت یا قطعه Android ترجمه می‌شود و باید توسط آن‌ها فراخوانی شود. چون فراخوانی‌های برگشتی چرخه حیات NavigationView براساس فراخوانی‌های برگشتی چرخه حیات Android هستند و به همان ترتیب فراخوانده می‌شوند، ترتیب دقیق این روش‌های NavigationView الزامی است. درغیراین‌صورت، ممکن است با نشت حافظه، خطاهای واسط کاربر، به‌روز نشدن مکان، و مشکلات دیگر مواجه شوید.

برای اطلاعات بیشتر درباره چرخه حیات فعالیت Android، به بخش مفاهیم چرخه حیات فعالیت در اسناد توسعه‌دهنده Android مراجعه کنید.

جدول زیر نشان می‌دهد که چه زمانی باید سایر روش‌های چرخه حیات پس‌از روش‌های چرخه حیات مشخص‌شده فراخوانی شوند:

این روش‌های چرخه حیات را چندین بار بدون فراخوانی روش بستن مربوطه فراخوانی نکنید. علاوه‌براین، به‌خاطر داشته باشید که اگر برخی‌از این فراخوانی‌های چرخه حیات Android توسط خود برنامه مدیریت شوند و NavigationView پس‌از ایجاد یا شروع به قطعه اضافه شود، برنامه باید روش‌های خاص را به‌ترتیب مناسب فراخوانی کند تا Navigation SDK به‌درستی مقداردهی اولیه شود.

برای راهنمایی بیشتر درباره استفاده از این روش‌ها، به برنامه نمایشی Navigation SDK مراجعه کنید.

اگر از NavigationView استفاده می‌کنید، رویدادهای چرخه حیات را از فعالیت یا قطعه فراخوانی کنید، نه هر دو

To keep the strict ordering of the lifecycle methods, invoke these events from either the activity or fragment lifecycle callbacks, which receive these events in order. این رویکرد تضمین می‌کند که برنامه‌ها نیازی به هماهنگی بین تکه‌ها و فعالیت‌ها ندارند و باعث تماس‌های تکراری نمی‌شوند.

به‌روزرسانی از SupportNavigationFragment به NavigationFragment

از Navigation SDK نسخه ۸.۰.۰، NavigationFragment جایگزین SupportNavigationFragment منسوخ‌شده به‌عنوان ظرف قطعه استاندارد برای ناوبری گام‌به‌گام و نمایش نقشه می‌شود.

NavigationFragment برابری کامل میانای برنامه‌سازی کاربردی را با SupportNavigationFragment حفظ می‌کند. برای به‌روزرسانی برنامه، SupportNavigationFragment را با NavigationFragment در فایل‌های طرح‌بندی XML و واردات کد منبع جایگزین کنید. همه امضاهای روش و تماس‌های getSupportFragmentManager() یکسان باقی می‌مانند.

به‌روزرسانی XML چیدمان

SupportNavigationFragment را با NavigationFragment در فایل‌های XML چیدمانتان جایگزین کنید:

قبل‌از (نسخه ۷.x و قدیمی‌تر):

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

بعداز (نسخه ۸.۰.۰ به بالا):

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.NavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

اگر برنامه‌تان از FragmentContainerView (توصیه‌شده برای میزبانی قطعه‌ها) استفاده می‌کند، مشخصه android:name را به‌روز کنید:

<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.NavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

به‌روزرسانی کد برنامه

واردات و تبدیل کلاس‌ها را در کد Java یا Kotlin خود جایگزین کنید. چون هر دو کلاس androidx.fragment.app.Fragment را گسترش می‌دهند، همچنان از getSupportFragmentManager() برای جستجوی قطعه استفاده کنید:

قبل (نسخه ۷.x و قدیمی‌تر):

import com.google.android.libraries.navigation.SupportNavigationFragment;

public class MainActivity extends AppCompatActivity {
  private SupportNavigationFragment mNavFragment;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mNavFragment = (SupportNavigationFragment) getSupportFragmentManager()
        .findFragmentById(R.id.navigation_fragment);
  }
}
    

import com.google.android.libraries.navigation.SupportNavigationFragment

class MainActivity : AppCompatActivity() {
  private lateinit var navFragment: SupportNavigationFragment

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    navFragment = supportFragmentManager
        .findFragmentById(R.id.navigation_fragment) as SupportNavigationFragment
  }
}
    

بعداز (نسخه ۸.۰.۰ به بالا):

import com.google.android.libraries.navigation.NavigationFragment;

public class MainActivity extends AppCompatActivity {
  private NavigationFragment mNavFragment;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mNavFragment = (NavigationFragment) getSupportFragmentManager()
        .findFragmentById(R.id.navigation_fragment);
  }
}
    

import com.google.android.libraries.navigation.NavigationFragment

class MainActivity : AppCompatActivity() {
  private lateinit var navFragment: NavigationFragment

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    navFragment = supportFragmentManager
        .findFragmentById(R.id.navigation_fragment) as NavigationFragment
  }
}
    

برابری میانای برنامه‌سازی کاربردی

لازم نیست تغییرات رفتاری دیگری ایجاد کنید یا ساختار کدتان را تغییر دهید. ‫NavigationFragment از همه روش‌های عمومی، میاناهای شنونده، و کنترل‌های میانای کاربر سفارشی از SupportNavigationFragment با امضاهای روش یکسان (ازجمله getMapAsync()،‏ getNavigator()،‏ setEtaCardEnabled()، و setStylingOptions()) پشتیبانی می‌کند.