คอมโพเนนต์การนำทางมีภาษาเฉพาะโดเมนที่ใช้ Kotlin หรือ DSL ซึ่งอาศัยเครื่องมือสร้างที่ปลอดภัยต่อประเภทของ Kotlin API นี้ช่วยให้คุณเขียนกราฟในโค้ด Kotlin แบบประกาศได้ แทนที่จะเขียนภายในทรัพยากร XML ซึ่งจะเป็นประโยชน์หากคุณต้องการสร้างการนําทางของแอปแบบไดนามิก ตัวอย่างเช่น แอปของคุณสามารถดาวน์โหลดและแคชการกำหนดค่าการนำทางจากบริการเว็บภายนอก แล้วใช้การกำหนดค่านั้นเพื่อสร้างกราฟการนำทางแบบไดนามิกในฟังก์ชัน onCreate() ของกิจกรรม
ความสัมพันธ์
หากต้องการใช้ Kotlin DSL กับ Fragment ให้เพิ่มทรัพยากร Dependency ต่อไปนี้ลงในไฟล์ 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 โดยในตัวอย่างนี้ เรามีปลายทาง 2 แห่ง ได้แก่ home และ plant_detail ปลายทาง home
จะปรากฏขึ้นเมื่อผู้ใช้เปิดแอปเป็นครั้งแรก ปลายทางนี้จะแสดงรายการต้นไม้จากสวนของผู้ใช้ เมื่อผู้ใช้เลือกต้นไม้ต้นใดต้นหนึ่ง แอปจะไปยังปลายทาง plant_detail
รูปที่ 1 แสดงปลายทางเหล่านี้พร้อมกับอาร์กิวเมนต์ที่ปลายทาง plant_detail ต้องการ และการดำเนินการ to_plant_detail ที่แอปใช้เพื่อไปยังส่วนต่างๆ จาก home ไปยัง plant_detail
home และ plant_detail พร้อมกับการดำเนินการที่เชื่อมต่อปลายทางทั้งสองการโฮสต์กราฟการนำทาง Kotlin DSL
ก่อนที่จะสร้างกราฟการนําทางของแอปได้ คุณต้องมีที่สําหรับโฮสต์กราฟ ตัวอย่างนี้ใช้ Fragment จึงโฮสต์กราฟใน 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 การดำเนินการจะเชื่อมโยงรหัสปลายทางกับอาร์กิวเมนต์อย่างน้อย 1 รายการเข้าด้วยกัน อย่างไรก็ตาม เมื่อใช้ DSL การนําทาง เส้นทางอาจมีอาร์กิวเมนต์เป็นส่วนหนึ่งของเส้นทางได้ ซึ่งหมายความว่าไม่มีแนวคิดเรื่องการดำเนินการเมื่อใช้ DSL
ขั้นตอนถัดไปคือการกำหนดเส้นทางที่คุณจะใช้เมื่อกำหนดกราฟ
สร้างเส้นทางสำหรับกราฟ
ระบบจะแยกวิเคราะห์กราฟการนําทางที่ใช้ XML เป็นส่วนหนึ่งของกระบวนการบิลด์ Android ระบบจะสร้างค่าคงที่ที่เป็นตัวเลขสำหรับแอตทริบิวต์ id แต่ละรายการที่กำหนดไว้ในกราฟ รหัสแบบคงที่ที่สร้างขึ้นในเวลาบิลด์เหล่านี้จะไม่พร้อมใช้งานเมื่อสร้างกราฟการนําทางที่รันไทม์ ดังนั้น DSL การนําทางจึงใช้ประเภทที่ทำให้เป็นอนุกรมได้แทนรหัส แต่ละเส้นทางจะแสดงด้วยประเภทที่ไม่ซ้ำกัน
เมื่อจัดการกับอาร์กิวเมนต์ อาร์กิวเมนต์เหล่านี้จะสร้างขึ้นในประเภทเส้นทาง ซึ่งช่วยให้คุณมีความปลอดภัยในการกำหนดประเภท สำหรับอาร์กิวเมนต์การนำทาง
@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)
}
}
ในตัวอย่างนี้ มีการกำหนดปลายทาง Fragment 2 รายการโดยใช้ฟังก์ชันบิลเดอร์ DSL fragment() ฟังก์ชันนี้ต้องใช้อาร์กิวเมนต์ประเภท 2 รายการ
อันดับแรกคือคลาส Fragment ที่มี UI สำหรับปลายทางนี้ การตั้งค่านี้มีผลเช่นเดียวกับการตั้งค่าแอตทริบิวต์ android:name ในปลายทาง Fragment ที่กำหนดโดยใช้ XML
2. เส้นทาง ซึ่งต้องเป็นประเภทที่ทำให้เป็นอนุกรมได้ซึ่งขยายมาจาก Any โดยควรมีอาร์กิวเมนต์การนำทางที่จะใช้โดยปลายทางนี้และประเภทของอาร์กิวเมนต์
ฟังก์ชันนี้ยังยอมรับ Lambda ที่ไม่บังคับสำหรับการกำหนดค่าเพิ่มเติม เช่น ป้ายกำกับปลายทาง รวมถึงฟังก์ชัน Builder แบบฝังสำหรับอาร์กิวเมนต์ที่กำหนดเองและ Deep Link
การไปยังส่วนต่างๆ ด้วยกราฟ 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 มีการรองรับในตัวสำหรับปลายทาง 3 ประเภท ได้แก่ ปลายทาง Fragment, Activity และ NavGraph ซึ่งแต่ละประเภทมีฟังก์ชันส่วนขยายในบรรทัดของตัวเองสำหรับสร้างและกำหนดค่าปลายทาง
ปลายทางของ Fragment
ฟังก์ชัน DSL fragment() สามารถกำหนดพารามิเตอร์ด้วยคลาส Fragment สำหรับ UI และประเภทเส้นทางที่ใช้เพื่อระบุปลายทางนี้โดยเฉพาะ ตามด้วย Lambda ที่คุณสามารถกำหนดค่าเพิ่มเติมได้ตามที่อธิบายไว้ในส่วนการไปยังส่วนต่างๆ ด้วยกราฟ Kotlin DSL
fragment<MyFragment, MyRoute> {
label = getString(R.string.fragment_title)
// custom argument types, deepLinks
}
จุดหมายปลายทางของกิจกรรม
ฟังก์ชัน DSL activity() จะใช้พารามิเตอร์ประเภทสำหรับเส้นทาง แต่ไม่ได้กำหนดพารามิเตอร์ให้กับคลาสกิจกรรมที่ใช้ แต่คุณจะตั้งค่า activityClass ที่ไม่บังคับใน Lambda ต่อท้ายแทน ความยืดหยุ่นนี้ช่วยให้คุณกำหนดปลายทางของกิจกรรมสำหรับกิจกรรมที่ควรเปิดโดยใช้ Intent โดยนัย ซึ่งคลาสกิจกรรมที่ชัดเจนจะไม่เหมาะสม เช่นเดียวกับปลายทาง Fragment คุณยังสามารถกำหนดค่าป้ายกำกับ อาร์กิวเมนต์ที่กำหนดเอง และ Deep Link ได้ด้วย
activity<MyRoute> {
label = getString(R.string.activity_title)
// custom argument types, deepLinks...
activityClass = MyActivity::class
}
ปลายทางของกราฟการนำทาง
คุณสามารถใช้ฟังก์ชัน DSL navigation() เพื่อสร้างกราฟการนําทางที่ฝังอยู่ได้ ฟังก์ชันนี้ใช้พารามิเตอร์ประเภทสำหรับเส้นทางที่จะกำหนดให้กับกราฟนี้ นอกจากนี้ยังรับอาร์กิวเมนต์ 2 รายการ ได้แก่
เส้นทางของจุดหมายเริ่มต้นของกราฟ และ Lambda เพื่อกำหนดค่ากราฟเพิ่มเติม องค์ประกอบที่ถูกต้อง ได้แก่ ปลายทางอื่นๆ, ประเภทอาร์กิวเมนต์ที่กำหนดเอง, Deep Link และป้ายกำกับที่สื่อความหมายสำหรับปลายทาง
ป้ายกำกับนี้มีประโยชน์สำหรับการเชื่อมโยงกราฟการนำทางกับคอมโพเนนต์ UI โดยใช้ 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 อาร์กิวเมนต์ที่จำเป็นจะกำหนดเป็นประเภทที่ไม่มีค่า Null และอาร์กิวเมนต์ที่ไม่บังคับจะกำหนดด้วยค่าเริ่มต้น
กลไกพื้นฐานสำหรับการแสดงเส้นทางและอาร์กิวเมนต์จะอิงตามสตริง การใช้สตริงเพื่อจำลองเส้นทางช่วยให้สามารถจัดเก็บและกู้คืนสถานะการนำทางจากดิสก์ได้ในระหว่างการเปลี่ยนแปลงการกำหนดค่าและการสิ้นสุดการประมวลผลที่ระบบเริ่มขึ้น ด้วยเหตุนี้ อาร์กิวเมนต์การนําทางแต่ละรายการจึงต้องเป็นแบบอนุกรมได้ กล่าวคือ ควรมีเมธอดที่แปลงการนําเสนอค่าอาร์กิวเมนต์ในหน่วยความจําเป็น String
ปลั๊กอินการแปลงเป็นอนุกรมของ Kotlin จะสร้างเมธอดการแปลงเป็นอนุกรมสำหรับประเภทพื้นฐานโดยอัตโนมัติเมื่อเพิ่มคำอธิบายประกอบ @Serializable ลงในออบเจ็กต์
@Serializable
data class MyRoute(
val id: String,
val myList: List<Int>,
val optionalArg: String? = null
)
fragment<MyFragment, MyRoute>
การระบุประเภทที่กำหนดเอง
สำหรับประเภทอาร์กิวเมนต์ที่กำหนดเอง คุณจะต้องระบุคลาส NavType ที่กำหนดเอง ซึ่งช่วยให้คุณควบคุมวิธีแยกวิเคราะห์ประเภทจากเส้นทางหรือ Deep Link ได้อย่างแม่นยำ
ตัวอย่างเช่น เส้นทางที่ใช้กำหนดหน้าจอการค้นหาอาจมีคลาสที่แสดงพารามิเตอร์การค้นหาดังนี้
@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
Deep Link
คุณสามารถเพิ่ม Deep Link ไปยังปลายทางใดก็ได้ เช่นเดียวกับที่ทำได้ด้วยกราฟการนำทางที่ขับเคลื่อนด้วย XML ขั้นตอนทั้งหมดที่กำหนดไว้ในการสร้าง Deep Link สำหรับปลายทางจะใช้กับกระบวนการสร้าง Deep Link โดยใช้ Kotlin DSL
อย่างไรก็ตาม เมื่อสร้าง Implicit Deep Link คุณจะไม่มีแหล่งข้อมูลการนําทาง XML ที่สามารถวิเคราะห์องค์ประกอบ <deepLink> ได้ ดังนั้น คุณจึงไม่สามารถพึ่งพาการวางองค์ประกอบ <nav-graph> ในไฟล์ AndroidManifest.xml และต้องเพิ่มตัวกรอง Intent ลงในกิจกรรมด้วยตนเองแทน ตัวกรอง Intent ที่คุณระบุควรตรงกับเส้นทางพื้นฐาน การดำเนินการ และประเภท MIME ของ Deep Link ของแอป
ระบบจะเพิ่ม Deep Link ไปยังปลายทางโดยเรียกใช้ฟังก์ชัน deepLink ภายใน Lambda ของปลายทาง โดยจะยอมรับเส้นทางเป็นประเภทที่มีพารามิเตอร์ และพารามิเตอร์ basePath สำหรับเส้นทางฐานของ URL ที่ใช้สำหรับ Deep Link
นอกจากนี้ คุณยังเพิ่มการดำเนินการและประเภท MIME ได้โดยใช้แลมบ์ดาต่อท้าย deepLinkBuilder
ตัวอย่างต่อไปนี้จะสร้าง URI ของ Deep Link สำหรับปลายทาง 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 ของ Deep Link โดยอัตโนมัติจากช่องของเส้นทางโดยใช้กฎต่อไปนี้
- ระบบจะเพิ่มพารามิเตอร์ที่จำเป็นเป็นพารามิเตอร์เส้นทาง (เช่น
/{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}
คุณเพิ่ม Deep Link ได้ไม่จำกัดจำนวน ทุกครั้งที่คุณเรียกใช้
deepLink()
ระบบจะเพิ่ม Deep Link ใหม่ต่อท้ายรายการที่เก็บไว้สำหรับปลายทางนั้น
ข้อจำกัด
ปลั๊กอิน Safe Args เข้ากันไม่ได้กับ Kotlin DSL เนื่องจากปลั๊กอินจะค้นหาไฟล์ทรัพยากร XML เพื่อสร้างคลาส Directions และ Arguments