רכיב ה-Navigation מספק שפה ספציפית לדומיין (DSL) שמבוססת על Kotlin, ומסתמכת על ה-builders למניעת שגיאות הקלדה של Kotlin. ה-API הזה מאפשר לכם ליצור את התרשים באופן הצהרתי בקוד Kotlin, במקום בתוך משאב XML. זה יכול להיות שימושי אם רוצים ליצור את הניווט באפליקציה באופן דינמי. לדוגמה, האפליקציה יכולה להוריד הגדרת ניווט משירות אינטרנט חיצוני ולשמור אותה במטמון, ואז להשתמש בהגדרה הזו כדי ליצור באופן דינמי תרשים ניווט בפונקציה onCreate() של הפעילות.
פניות קשורות
כדי להשתמש ב-Kotlin DSL עם Fragments, מוסיפים את התלות הבאה לקובץ build.gradle של האפליקציה:
Groovy
dependencies { def nav_version = "2.10.2" api "androidx.navigation:navigation-fragment-ktx:$nav_version" }
Kotlin
dependencies { val nav_version = "2.10.2" api("androidx.navigation:navigation-fragment-ktx:$nav_version") }
יצירת גרף
הנה דוגמה בסיסית שמבוססת על האפליקציה Sunflower. בדוגמה הזו יש שני יעדים: home ו-plant_detail. היעד home מוצג כשהמשתמש מפעיל את האפליקציה בפעם הראשונה. ביעד הזה מוצגת רשימה של צמחים מהגינה של המשתמש. כשהמשתמש בוחר באחד מהצמחים, האפליקציה מנווטת ליעד plant_detail.
באיור 1 מוצגים היעדים האלה, יחד עם הארגומנטים שנדרשים ליעד plant_detail ופעולה, to_plant_detail, שבה האפליקציה משתמשת כדי לנווט מ-home אל plant_detail.
home ו-plant_detail, ופעולה
שמקשרת ביניהם.אירוח של תרשים ניווט ב-Kotlin DSL
לפני שיוצרים את תרשים הניווט של האפליקציה, צריך מקום לארח בו את התרשים. בדוגמה הזו נעשה שימוש בפרגמנטים, ולכן התרשים מתארח ב-NavHostFragment בתוך FragmentContainerView:
<!-- activity_garden.xml -->
<FrameLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto">
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.fragment.app.FragmentContainerView
android:id="@+id/nav_host"
android:name="androidx.navigation.fragment.NavHostFragment"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:defaultNavHost="true" />
</FrameLayout>
שימו לב שהמאפיין app:navGraph לא מוגדר בדוגמה הזו. התרשים לא מוגדר כמשאב בתיקייה res/navigation, ולכן צריך להגדיר אותו כחלק מהתהליך onCreate() בפעילות.
ב-XML, פעולה מקשרת בין מזהה יעד לבין ארגומנט אחד או יותר. עם זאת, כשמשתמשים ב-Navigation DSL, מסלול יכול להכיל ארגומנטים כחלק מהמסלול. כלומר, אין קונספט של פעולות כשמשתמשים ב-DSL.
השלב הבא הוא להגדיר את המסלולים שבהם תשתמשו כשאתם מגדירים את התרשים.
יצירת נתיבים לתרשים
תרשימי ניווט מבוססי-XML מנותחים כחלק מתהליך ה-build של Android. נוצר קבוע מספרי לכל מאפיין id שמוגדר בתרשים. המזהים הסטטיים האלה שנוצרים בזמן ה-build לא זמינים כשיוצרים את תרשים הניווט בזמן הריצה, ולכן ה-DSL של ה-Navigation משתמש בסוגים שניתנים לסריאליזציה במקום במזהים. כל מסלול מיוצג על ידי סוג ייחודי.
כשמדובר בארגומנטים, הם מובנים בסוג המסלול. כך אפשר למנוע שגיאות הקלדה בארגומנטים של הניווט.
@Serializable data object Home
@Serializable data class Plant(val id: String)
יצירת תרשים באמצעות NavGraphBuilder DSL
אחרי שמגדירים את המסלולים, אפשר ליצור את תרשים הניווט.
val navController = findNavController(R.id.nav_host_fragment)
navController.graph = navController.createGraph(
startDestination = Home
) {
fragment<HomeFragment, Home> {
label = resources.getString(R.string.home_title)
}
fragment<PlantDetailFragment, PlantDetail> {
label = resources.getString(R.string.plant_detail_title)
}
}
בדוגמה הזו, שני יעדי מקטעים מוגדרים באמצעות פונקציית ה-DSL builder fragment(). הפונקציה הזו דורשת שני ארגומנטים מסוג type.
קודם כל, מחלקה מסוג Fragment שמספקת את ממשק המשתמש של היעד הזה. להגדרה הזו יש אותה השפעה כמו להגדרת המאפיין android:name ביעדי מקטעים שמוגדרים באמצעות XML.
הדבר השני הוא המסלול. הסוג הזה חייב להיות ניתן לסריאליזציה וצריך להרחיב אותו מ-Any. הוא צריך להכיל את כל הארגומנטים של הניווט שישמשו את היעד הזה, ואת הסוגים שלהם.
הפונקציה גם מקבלת למבדה אופציונלית להגדרות נוספות, כמו תווית היעד, וגם פונקציות של כלי פיתוח מוטמעים לארגומנטים מותאמים אישית ולקישורי עומק.
ניווט באמצעות תרשים Kotlin DSL
לבסוף, אפשר לעבור מ-home אל plant_detail באמצעות קריאות ל-NavController.navigate():
private fun navigateToPlant(plantId: String) {
findNavController().navigate(route = PlantDetail(id = plantId))
}
ב-PlantDetailFragment, כדי לקבל את הארגומנטים של הניווט, צריך לקבל את ה-NavBackStackEntry הנוכחי ולהפעיל בו את toRoute כדי לקבל את המופע של המסלול.
val plantDetailRoute = findNavController().getBackStackEntry<PlantDetail>().toRoute<PlantDetail>()
val plantId = plantDetailRoute.id
אם PlantDetailFragment משתמש ב-ViewModel, צריך לקבל את מופע המסלול באמצעות SavedStateHandle.toRoute.
val plantDetailRoute = savedStateHandle.toRoute<PlantDetail>()
val plantId = plantDetailRoute.id
בהמשך המדריך מתוארים רכיבים נפוצים של תרשים ניווט, יעדים ואיך להשתמש בהם כשיוצרים את התרשים.
יעדים
Kotlin DSL מספק תמיכה מובנית בשלושה סוגי יעדים: יעדי Fragment, Activity ו-NavGraph. לכל אחד מהם יש פונקציית הרחבה מוטבעת משלו, שזמינה לבנייה ולהגדרה של היעד.
יעדים של מקטעים
אפשר להגדיר פרמטרים לפונקציית ה-DSL fragment() באמצעות מחלקת הפרגמנט של ממשק המשתמש וסוג המסלול שמשמש לזיהוי ייחודי של היעד הזה, ואחריהם ביטוי lambda שבו אפשר לספק הגדרות נוספות, כמו שמתואר בקטע ניווט באמצעות תרשים Kotlin DSL.
fragment<MyFragment, MyRoute> {
label = getString(R.string.fragment_title)
// custom argument types, deepLinks
}
יעד הפעילות
הפונקציה activity() ב-DSL מקבלת פרמטר מסוג מסוים בשביל הנתיב, אבל לא מוגדרת עם פרמטרים לאף מחלקת פעילות שמטמיעה אותו. במקום זאת, מגדירים activityClass אופציונלי ב-lambda נגררת. הגמישות הזו מאפשרת לכם להגדיר יעד לפעילות שצריך להפעיל באמצעות כוונה משתמעת, במקרים שבהם אין היגיון להשתמש במחלקת פעילות מפורשת. כמו ביעדים של מקטעים, אפשר גם להגדיר תווית, ארגומנטים בהתאמה אישית וקישורי עומק.
activity<MyRoute> {
label = getString(R.string.activity_title)
// custom argument types, deepLinks...
activityClass = MyActivity::class
}
יעד בתרשים הניווט
אפשר להשתמש בפונקציית ה-DSL navigation() כדי ליצור תרשים ניווט בתצוגת עץ. הפונקציה הזו מקבלת פרמטר מסוג מסלול כדי להקצות אותו לתרשים הזה. היא גם מקבלת שני ארגומנטים: הנתיב של יעד ההתחלה של התרשים, ו-lambda להגדרה נוספת של התרשים. רכיבים חוקיים כוללים יעדים אחרים, סוגי ארגומנטים מותאמים אישית, קישורי עומק ותווית תיאורית ליעד.
התווית הזו יכולה להיות שימושית כדי לקשר את תרשים הניווט לרכיבים של ממשק המשתמש באמצעות NavigationUI.
@Serializable data object HomeGraph
@Serializable data object Home
navigation<HomeGraph>(startDestination = Home) {
// label, other destinations, deep links
}
תמיכה ביעדים בהתאמה אישית
אם אתם משתמשים בסוג יעד חדש שלא תומך ישירות ב-Kotlin DSL, אתם יכולים להוסיף את היעדים האלה ל-Kotlin DSL באמצעות addDestination():
// The NavigatorProvider is retrieved from the NavController
val customDestination = navigatorProvider[CustomNavigator::class].createDestination().apply {
route = Graph.CustomDestination.route
}
addDestination(customDestination)
לחלופין, אפשר גם להשתמש באופרטור הפלוס האונרי כדי להוסיף יעד חדש שנוצר ישירות לתרשים:
// The NavigatorProvider is retrieved from the NavController
+navigatorProvider[CustomNavigator::class].createDestination().apply {
route = Graph.CustomDestination.route
}
מתן ארגומנטים של יעד
אפשר להגדיר את הארגומנטים של היעד כחלק ממחלקת המסלול. אפשר להגדיר אותם באותו אופן שבו מגדירים כל מחלקה ב-Kotlin. ארגומנטים נדרשים מוגדרים כסוגים שלא יכולים להיות ריקים, וארגומנטים אופציונליים מוגדרים עם ערכי ברירת מחדל.
המנגנון הבסיסי לייצוג מסלולים והארגומנטים שלהם מבוסס על מחרוזות. שימוש במחרוזות ליצירת מודלים של מסלולים מאפשר לאחסן את מצב הניווט ולשחזר אותו מהדיסק במהלך שינויים בהגדרות האישיות והשבתת תהליך שהמערכת יזמה. לכן, כל ארגומנט ניווט צריך להיות ניתן לסריאליזציה, כלומר צריכה להיות לו שיטה שממירה את הייצוג בזיכרון של ערך הארגומנט ל-String.
הפלאגין Kotlin serialization יוצר באופן אוטומטי שיטות לסריאליזציה של סוגים בסיסיים כשמוסיפים את ההערה @Serializable לאובייקט.
@Serializable
data class MyRoute(
val id: String,
val myList: List<Int>,
val optionalArg: String? = null
)
fragment<MyFragment, MyRoute>
מתן סוגי לקוחות מותאמים אישית
כדי להשתמש בסוגי ארגומנטים בהתאמה אישית, צריך לספק מחלקת NavType בהתאמה אישית. כך אתם יכולים לשלוט בדיוק באופן שבו הסוג שלכם מנותח מנתיב או מקישור עומק.
לדוגמה, נתיב שמשמש להגדרת מסך חיפוש יכול להכיל מחלקה שמייצגת את הפרמטרים של החיפוש:
@Serializable
data class SearchRoute(val parameters: SearchParameters)
@Serializable
@Parcelize
data class SearchParameters(
val searchQuery: String,
val filters: List<String>
)
אפשר לכתוב NavType בהתאמה אישית כך:
val SearchParametersType = object : NavType<SearchParameters>(
isNullableAllowed = false
) {
override fun put(bundle: Bundle, key: String, value: SearchParameters) {
bundle.putParcelable(key, value)
}
override fun get(bundle: Bundle, key: String): SearchParameters {
return bundle.getParcelable(key) as SearchParameters
}
override fun serializeAsValue(value: SearchParameters): String {
// Serialized values must always be Uri encoded
return Uri.encode(Json.encodeToString(value))
}
override fun parseValue(value: String): SearchParameters {
// Navigation takes care of decoding the string
// before passing it to parseValue()
return Json.decodeFromString<SearchParameters>(value)
}
}
אחר כך אפשר להשתמש בזה ב-Kotlin DSL כמו בכל סוג אחר:
fragment<SearchFragment, SearchRoute>(
typeMap = mapOf(typeOf<SearchParameters>() to SearchParametersType)
) {
label = getString(R.string.plant_search_title)
}
כשמנווטים ליעד, יוצרים מופע של המסלול:
val params = SearchParameters("rose", listOf("available"))
navController.navigate(route = SearchRoute(params))
אפשר לקבל את הפרמטר מהמסלול ביעד:
val searchRoute = navController().getBackStackEntry<SearchRoute>().toRoute<SearchRoute>()
val params = searchRoute.parameters
קישורי עומק
אפשר להוסיף קישורי עומק לכל יעד, בדיוק כמו שאפשר לעשות עם תרשים ניווט מבוסס XML. כל ההליכים שמוגדרים ביצירת קישור עומק ליעד חלים על תהליך היצירה של קישור עומק באמצעות Kotlin DSL.
עם זאת, כשיוצרים קישור עומק מרומז, אין משאב ניווט ב-XML שאפשר לנתח כדי למצוא רכיבי <deepLink>. לכן, אי אפשר להסתמך על הצבת רכיב <nav-graph> בקובץ AndroidManifest.xml, וצריך להוסיף מסנני Intent לפעילות באופן ידני. מסנן ה-Intent שאתם מספקים צריך להתאים לנתיב הבסיס, לפעולה ולסוג ה-MIME של קישורי העומק של האפליקציה.
כדי להוסיף קישורי עומק ליעד, צריך להפעיל את הפונקציה deepLink בתוך פונקציית הלמבדה של היעד. היא מקבלת את המסלול כסוג עם פרמטרים, ופרמטר basePath לנתיב הבסיס של כתובת ה-URL שמשמשת לקישור העומק.
אפשר גם להוסיף פעולה וסוג MIME באמצעות פונקציית הלמבדה הנגררת
deepLinkBuilder
.
בדוגמה הבאה נוצר URI של קישור עומק ליעד Home.
@Serializable data object Home
fragment<HomeFragment, Home>{
deepLink<Home>(basePath = "www.example.com/home"){
// Optionally, specify the action and/or mime type that this destination
// supports
action = "android.intent.action.MY_ACTION"
mimeType = "image/*"
}
}
פורמט ה-URI
פורמט ה-URI של קישור העומק נוצר באופן אוטומטי מהשדות של המסלול לפי הכללים הבאים:
- פרמטרים נדרשים מצורפים כפרמטרים של הנתיב (לדוגמה:
/{id}) - פרמטרים עם ערך ברירת מחדל (פרמטרים אופציונליים) מצורפים כפרמטרים של שאילתה (לדוגמה:
?name={name}) - אוספים מצורפים כפרמטרים של שאילתה (לדוגמה:
?items={value1}&items={value2}) - סדר הפרמטרים תואם לסדר השדות במסלול
לדוגמה, סוג המסלול הבא:
@Serializable data class PlantDetail(
val id: String,
val name: String,
val colors: List<String>,
val latinName: String? = null,
)
פורמט ה-URI שנוצר הוא:
basePath/{id}/{name}/?colors={color1}&colors={color2}&latinName={latinName}
אין הגבלה על מספר קישורי העומק שאפשר להוסיף. בכל פעם שקוראים ל-deepLink(), קישור עומק חדש מתווסף לרשימה שנשמרת בשביל היעד הזה.
מגבלות
הפלאגין Safe Args לא תואם ל-Kotlin DSL, כי הפלאגין מחפש קובצי משאבים ב-XML כדי ליצור מחלקות Directions ו-Arguments.