דף זה תורגם על ידי Cloud Translation API.

ניווט ליעד

רכיב הניווט מספק דרך ישירה וכללית מנווט ליעד. הממשק הזה תומך במגוון הקשרים וממשק משתמש של מסגרות. לדוגמה, ניתן להשתמש ברכיב הניווט באמצעות 'כתיבה', תצוגות, מקטעים, פעילויות ואפילו מסגרות מותאמות אישית של ממשק המשתמש.

במדריך זה מתואר כיצד להשתמש ברכיב הניווט כדי לנווט אל יעד בהקשרים שונים.

שימוש ב-NavController

סוג המפתח שבו משתמשים כדי לעבור בין יעדים הוא NavController. מידע נוסף על הכיתה עצמה מופיע במאמר איך יוצרים בקר ניווט. ואיך ליצור לו מופע. במדריך הזה מוסבר איך משתמשים בו.

ניווט

בלי קשר למסגרת של ממשק המשתמש שבה משתמשים, יש פונקציה אחת שבה אפשר להשתמש כדי לנווט ליעד: NavController.navigate().

יש הרבה עומסי יתר זמינים עבור navigate(). עומס יתר שצריך בהתאם להקשר המדויק שבחרתם. לדוגמה, צריך להשתמש עומס יתר כשעוברים לתוכן קומפוזבילי ועוד כשמנווטים לתצוגה.

בקטעים הבאים מתוארים חלק מעומסי היתר העיקריים של navigate() שאפשר לשימוש.

ניווט לתוכן קומפוזבילי

כדי לעבור לתוכן קומפוזבילי, צריך להשתמש בפונקציה NavController.navigate<T>. בעומס היתר הזה, navigate() מקבל ארגומנט route יחיד שעבורו להעביר סוג מסוים. היא משמשת כמפתח ליעד.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

כדי לנווט לתוכן קומפוזבילי בתרשים הניווט, צריך להגדיר קודם את NavGraph כך שכל יעד תואם לסוג. עבור תכנים קומפוזביליים, אפשר לעשות זאת באמצעות הפונקציה composable().

חשיפת אירועים מתכנים קומפוזביליים

כשפונקציה קומפוזבילית צריכה לנווט למסך חדש, אסור להעביר הוא מפנה אל NavController כדי שניתן יהיה להתקשר ישירות ל-navigate(). לפי עקרונות זרימת נתונים חד-כיווניים (UDF), במקום זאת, צריך לחשוף אירוע בכינוי NavController.

במילים אחרות, התוכן הקומפוזבילי צריך להכיל פרמטר מסוג () -> Unit. כשמוסיפים יעדים אל NavHost באמצעות composable() מעבירים את הקריאה הקומפוזבילית ל-NavController.navigate().

אפשר לראות דוגמה לכך בקטע המשנה הבא.

דוגמה

לצורך הדגמה של הקטעים הקודמים, הקפידו לשים לב לנקודות האלה קטע הקוד הבא:

כל יעד בתרשים נוצר באמצעות מסלול, אובייקט או סיווג שניתן לבצע בהם סריאליזציה שמתארים את הנתונים שנדרשים על ידי היעד.
התוכן הקומפוזבילי MyAppNavHost מכיל את המכונה NavController.
בהתאם לכך, הקריאות אל navigate() צריכות להתבצע שם ולא בטווח נמוך יותר קומפוזבילי כמו ProfileScreen.
ProfileScreen מכיל לחצן שמנווט את המשתמש אל FriendsList כשלוחצים עליו. עם זאת, הוא לא קורא לפונקציה navigate() עצמה.
במקום זאת, הלחצן מפעיל פונקציה שנחשפה כפרמטר onNavigateToFriends
כאשר MyAppNavHost מוסיף את ProfileScreen לתרשים הניווט, למשך onNavigateToFriends הוא מעביר lambda שקוראת ל-navigate(route = FriendsList).
הדרישה הזו מבטיחה שכאשר המשתמשים ילחצו על הלחצן ProfileScreen, הם ניווט נכון אל FriendsListScreen.

@Serializable
object Profile
@Serializable
object FriendsList

@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),

) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = Profile
    ) {
        composable<Profile> {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate(route = FriendsList) },
                /*...*/
            )
        }
        composable<FriendsList> { FriendsListScreen(/*...*/) }
    }
}

@Composable
fun ProfileScreen(
    onNavigateToFriends: () -> Unit,
    /*...*/
) {
    /*...*/
    Button(onClick = onNavigateToFriends) {
        Text(text = "See friends list")
    }
}

ניווט באמצעות מזהה של מספר שלם

כדי לנווט ליעד עם מספר שלם, מפעילים את הפונקציה navigate(int) עומס יתר. היא לוקחת את מזהה המשאב של פעולה או של יעד. בקטע הקוד הבא מראה איך אפשר להשתמש בעומס היתר כדי לעבור ViewTransactionsFragment:

Kotlin

viewTransactionsButton.setOnClickListener { view ->
  view.findNavController().navigate(R.id.viewTransactionsAction)
}

Java

viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
      Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
  }
});

כשמנווטים באמצעות מזהים, צריך להשתמש בפעולות כשזה אפשרי. פעולות ולספק מידע נוסף בתרשים הניווט, וכך ניתן לראות באופן חזותי היעדים שלכם מקושרים זה לזה.

ניווט באמצעות NavDeepLinkRequest

כדי לנווט אל יעד משתמע של קישור עומק, משתמשים בפונקציה navigate(NavDeepLinkRequest) עומס יתר. קטע הקוד למעקב מספק של השיטה הזו:

Kotlin

val request = NavDeepLinkRequest.Builder
  .fromUri("android-app://androidx.navigation.app/profile".toUri())
  .build()
findNavController().navigate(request)

Java

NavDeepLinkRequest request = NavDeepLinkRequest.Builder
  .fromUri(Uri.parse("android-app://androidx.navigation.app/profile"))
  .build()
NavHostFragment.findNavController(this).navigate(request)

בניגוד לניווט באמצעות מזהי פעולה או מזהי יעד, אפשר לנווט לכל קישור בתרשים, גם אם היעד גלוי וגם אם לא. אפשר לנווט ליעד בתרשים הנוכחי או ליעד תרשים אחר.

פעולות וסוגי MIME

בנוסף ל-Uri, NavDeepLinkRequest תומך גם בקישורי עומק עם פעולות וסוגי MIME. כדי להוסיף פעולה לבקשה, משתמשים fromAction() או setAction(). כדי להוסיף סוג MIME לבקשה: להשתמש ב-fromMimeType() או ב-setMimeType().

כדי ש-NavDeepLinkRequest יתאים כראוי ליעד של קישור עומק מרומז, ה-URI, הפעולה וסוג ה-MIME חייבים להיות תואמים ל-NavDeepLink ב- היעד. מזהי URI חייבים להתאים לדפוס, הפעולות חייבות להיות התאמה מדויקת. וסוגי ה-MIME חייבים להיות קשורים. לדוגמה, image/jpg תואם ל- image/\*

הקשרים נוספים

במסמך הזה מוסבר איך להשתמש ב-NavController.navigate() במקרים נפוצים. אבל לפונקציה יש טווח של עומסי יתר להשתמש בו בהקשרים שונים במקביל לכל מסגרת Ui. לצפייה לקבלת פרטים נוספים על עומסי-היתר האלה.

קריאה נוספת

מידע נוסף זמין בדפים הבאים: