導覽
最近更新時間 | 穩定版 | 候選版 | Beta 版 | Alpha 版 |
---|---|---|---|---|
2024 年 12 月 11 日 | 2.8.5 | - | - | 2.9.0-alpha04 |
宣告依附元件
如要為 Navigation 新增依附元件,必須將 Google Maven 存放區新增至您的專案。詳情請參閱「Google 的 Maven 存放區」一節。
在應用程式或模組的 build.gradle
檔案中,新增所需構件的依附元件:
Groovy
plugins { // Kotlin serialization plugin for type safe routes and navigation arguments id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.21' } dependencies { def nav_version = "2.8.4" // Jetpack Compose Integration implementation "androidx.navigation:navigation-compose:$nav_version" // Views/Fragments Integration implementation "androidx.navigation:navigation-fragment:$nav_version" implementation "androidx.navigation:navigation-ui:$nav_version" // Feature module support for Fragments implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version" // Testing Navigation androidTestImplementation "androidx.navigation:navigation-testing:$nav_version" // JSON serialization library, works with the Kotlin serialization plugin. implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3" }
Kotlin
plugins { // Kotlin serialization plugin for type safe routes and navigation arguments kotlin("plugin.serialization") version "2.0.21" } dependencies { val nav_version = "2.8.4" // Jetpack Compose integration implementation("androidx.navigation:navigation-compose:$nav_version") // Views/Fragments integration implementation("androidx.navigation:navigation-fragment:$nav_version") implementation("androidx.navigation:navigation-ui:$nav_version") // Feature module support for Fragments implementation("androidx.navigation:navigation-dynamic-features-fragment:$nav_version") // Testing Navigation androidTestImplementation("androidx.navigation:navigation-testing:$nav_version") // JSON serialization library, works with the Kotlin serialization plugin implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3") }
Safe Args
To add Safe Args
to your project, include the following classpath
in your top level build.gradle
file:
Groovy
buildscript { repositories { google() } dependencies { def nav_version = "2.8.5" classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version" } }
Kotlin
buildscript { repositories { google() } dependencies { val nav_version = "2.8.5" classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version") } }
You must also apply one of two available plugins.
To generate Java language code suitable for Java or mixed Java and Kotlin modules, add
this line to your app or module's build.gradle
file:
Groovy
plugins { id 'androidx.navigation.safeargs' }
Kotlin
plugins { id("androidx.navigation.safeargs") }
Alternatively, to generate Kotlin code suitable for Kotlin-only modules add:
Groovy
plugins { id 'androidx.navigation.safeargs.kotlin' }
Kotlin
plugins { id("androidx.navigation.safeargs.kotlin") }
You must have android.useAndroidX=true
in your
gradle.properties
file as per
Migrating to AndroidX.
如要進一步瞭解如何使用 Kotlin 擴充功能,請參閱 ktx 說明文件。
如要進一步瞭解依附元件,請參閱「新增建構依附元件」。
意見回饋
您的意見可協助我們改善 Jetpack。如果您發現新問題,或是有改進這個程式庫的建議,請告訴我們。回報新問題前,請先查看這個程式庫的現有問題。只要按一下星號按鈕,即可投票給現有的問題。
詳情請參閱 Issue Tracker 說明文件。
2.9 版
2.9.0-alpha04 版
2024 年 12 月 11 日
發布 androidx.navigation:navigation-*:2.9.0-alpha04
。2.9.0-alpha04 版包含這些修訂項目。
新功能
- 先前只能透過
reified
方法 (例如composable<YourScreen>
現在有非實體化版本,可直接取用KClass
例項。(Ia7eed、Id2879、Ibf244、I17d79、Id09d2、I54696、Ia47be、I93281、Ic1bf0、Iba4ee、If56a5、Icf969、I67644、I6f788、b/382094941、b/366291612、b/381938808)
下表提供已重新實作的 API 和 KClass API。
reified | KClass |
---|---|
composable<TestClass> { } |
composable(TestClass::class) { } |
navigation<NestedGraph>(startDestination = TestClass::class) |
navigation(route = NestedGraph::class, startDestination = TestClass::class) |
dialog<TestClass> {} |
dialog(TestClass::class) {} |
navDeepLink<TestClass>(baseUri) |
navDeepLink(TestClass::class, baseUri) |
NavDeepLink.Builder.setUriPattern<TestClass>(baseUri) |
NavDeepLink.Builder.setUriPattern(TestClass::class, baseUri) |
NavDestinationBuilder.deepLink<TestDeepLink>(baseUri) { } |
NavDestinationBuilder.deepLink(TestDeepLink::class, baseUri) { } |
navController.getBackStackEntry<TestClass>() |
navController.getBackStackEntry(TestClass::class) |
navController.popBackStack<TestClass>(true) |
navController.popBackStack(TestClass::class, true) |
navController.clearBackStack<TestClass>() |
navController.clearBackStack(TestClass::class) |
NavOptions.setPopUpTo<TestClass>() |
NavOptions.setPopUpTo(TestClass::class) |
navOptions { popUpTo<TestClass> {...} } |
navOptions { popUpTo(TestClass::class) {...} } |
NavGraph.setStartDestination<TestClass>() |
NavGraph.setStartDestination(TestClass::class) |
NavGraph.findNode<TestClass>() |
NavGraph.findNode(TestClass::class) |
backStackEntry.toRoute<TestClass>() |
backStackEntry.toRoute(TestClass::class) |
savedStateHandle.toRoute<TestClass>() |
savedStateHandle.toRoute(TestClass::class) |
API 變更
- 為了確保類型安全性,Kotlin 專用的
NavGraph.setStartDestination
超載會隱藏在 Java 來源中。(Ic640c、b/364634035)。
修正錯誤
- 自 Navigation
2.8.5
起:修正如果返回堆疊彈出至 1 個項目,且在同一幀中觸發系統返回,NavHost
就可能在PredictiveBackHandler
中擲回例外狀況的問題。(I1a429、b/375343407)。 - 自 Navigation
2.8.5
起:修正更新圖表startDestination
時的NavDestination
NullPointerException
問題。(I99421、b/361560785)。
2.9.0-alpha03 版
2024 年 11 月 13 日
發布 androidx.navigation:navigation-*:2.9.0-alpha03
。2.9.0-alpha03 版包含這些修訂項目。
新功能
- 導覽類型安全性現在支援值類別做為路徑或路徑的引數類型。(I9344a、b/374347483)。
修正錯誤
- 修正
ConcurrentModificationException
問題:當附加至NavBackStackEntry
的LifecycleObserver
在主機LifecycleOwner
(例如包含的活動或 Fragment) 變更生命週期狀態時觸發返回堆疊變更時,可能會發生此問題。(Ia9494)。
2.9.0-alpha02 版
2024 年 10 月 30 日
發布 androidx.navigation:navigation-*:2.9.0-alpha02
。2.9.0-alpha02 版包含這些修訂版本。
外部貢獻
- 新的通用
NavController.handleDeepLink(request: NavDeepLinkRequest)
方法。感謝 Konstantin Tskhovrebov!(I3e228)。
2.9.0-alpha01 版
2024 年 10 月 16 日
發布 androidx.navigation:navigation-*:2.9.0-alpha01
。2.9.0-alpha01 版包含這些修訂版本。
新功能
- 自訂導覽器現在可以將目的地標示為實作
SupportingPane
介面,向NavController
指出這些目的地會與其他目的地一併顯示。例如,您可以使用這個介面同時RESUMED
多個目的地。(Id5559)。 - 自 Navigation
2.8.3
起:為navigation-common
、navigation-runtime
和navigation-compose
模組新增 Lint 檢查,以便找出未正確標示@Serializable
的任何型別安全路徑。這項檢查會套用至所有NavGraphBuilder
和NavDeepLinkBuilder
擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I28bda、b/362725816) - 自 Navigation
2.8.3
起:為navigation-common
、navigation-runtime
和navigation-compose
模組新增 Lint 檢查,以便找出任何具有@Keep
標記不正確的 Enum 引數的型別安全性路徑。這項檢查會套用至所有NavGraphBuilder
和NavDeepLinkBuilder
擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I2b46f、b/358687142)
行為變更
- 嘗試使用先前已
DESTROYED
的NavController
時,現在會導致IllegalStateException
。(I520da、b/369616172)。
修正錯誤
- 更新「找不到列舉類別」例外狀況,建議使用
@Keep
註解,以防列舉類別在經過精簡的版本中遭到刪除。(I90e79、b/358137294)。
已知問題
Navigation 2.8.*
中新增的 Lint 規則有問題,當您嘗試使用 Android Gradle 外掛程式 8.4 以上版本執行 Lint 時,會導致Obsolete custom lint check
錯誤。(b/368070326、b/371463741)
2.8 版本
2.8.5 版
2024 年 12 月 11 日
發布 androidx.navigation:navigation-*:2.8.5
。2.8.5 版包含這些修訂項目。
修正錯誤
- 修正了如果返回堆疊彈出至 1 個項目,且系統返回在同一幀中觸發,
NavHost
就可能在PredictiveBackHandler
中擲回例外狀況的問題。(I1a429、b/375343407)。 - 修正更新圖表
startDestination
時的NavDestination
NullPointerException
問題。(I99421、b/361560785)。 - 修正問題:使用 Navigation Compose 時,在目前動畫結束的同一影格中呼叫 navigate 會導致動畫尺寸發生非預期的縮放動畫問題。(I26cb1、b/353294030)。
- 修正
ConcurrentModificationException
問題:當附加至NavBackStackEntry
的LifecycleObserver
在主機LifecycleOwner
(例如包含的活動或 Fragment) 變更生命週期狀態時觸發返回堆疊變更時,可能會發生此問題。(Ia9494)。
2.8.4 版
2024 年 11 月 13 日
發布 androidx.navigation:navigation-*:2.8.4
。2.8.4 版包含這些修訂項目。
新功能
- Navigation
2.9.0-alpha03
:Navigation 類型安全性現在支援以值類別做為路線或路線的引數類型 (I9344a、b/374347483)
修正錯誤
- 自 Navigation
2.9.0-alpha01
起:嘗試使用先前DESTROYED
的NavController
會導致IllegalStateException
。(I520da、b/369616172)。
2.8.3 版
2024 年 10 月 16 日
發布 androidx.navigation:navigation-*:2.8.3
。2.8.3 版包含這些修訂項目。
新功能
- 為
navigation-common
、navigation-runtime
和navigation-compose
模組新增 Lint 檢查,以便找出任何未正確使用@Serializable
註解的型別安全路徑。這項檢查會套用至所有NavGraphBuilder
和NavDeepLinkBuilder
擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I28bda、b/362725816) - 為
navigation-common
、navigation-runtime
和navigation-compose
模組新增 Lint 檢查,以便找出任何具有型別安全性路徑的列舉引數,這些引數未正確標註@Keep
。這項檢查會套用至所有NavGraphBuilder
和NavDeepLinkBuilder
擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I2b46f、b/358687142)
修正錯誤
- 修正了在嘗試使用 Android Gradle 外掛程式 8.4 以上版本執行 Lint 時,
Navigation 2.8.*
中新增的 Lint 規則會導致Obsolete custom lint check
錯誤的問題。(I1be3d、b/368070326、b/371463741)
已知問題
- 嘗試使用 Lint 16 (AGP 8.7) 以上版本執行 Lint 時,導覽 Lint 會擲回「已淘汰的自訂 Lint 檢查」錯誤。(b/371926651)
2.8.2 版
2024 年 10 月 2 日
發布 androidx.navigation:navigation-*:2.8.2
。2.8.2 版包含這些修訂項目。
新功能
- Navigation Type Safety 現在支援可序列化的類別,其中包含
Double
、Double?
、DoubleArray
、DoubleArray?
、List<Double>
和List<Double>?
,且不需要任何自訂NavType
。(I570eb、Ibc4c0、I37461、I5bed4、b/359245753)
修正錯誤
- 改善了錯誤訊息,當導航功能無法將路線的引數對應至
NavType
時,新錯誤訊息會包含引數名稱、引數完整修飾名稱和路線的完整修飾名稱。(Id8416、b/346264232)。
2.8.1 版
2024 年 9 月 18 日
發布 androidx.navigation:navigation-*:2.8.1
。2.8.1 版包含這些修訂項目。
新功能
- 新增 Lint 規則,確保在嘗試使用型別安全 API 進行
popBackStack
時,使用popBackStack
函式取用已實作的類別類型。(Ief161、b/358095343)。
修正錯誤
- 導覽功能現在要求傳遞至
NavGraph
的startDestination
路徑必須包含所有必要引數的值,包括不可為空值且沒有預設值的引數。(I18e74、b/362594265)。 - Navigation Safe Args 新增了對非空值字串的支援,因此「null」值會解析並原封不動地儲存至套件中。這與現有行為不同,在現有行為中,「null」值會解析為空值物件。這項變更僅適用於非空值字串類型。可為空值的字串則維持不變。(I08b4a、b/348936238)。
- 除非目的地明確新增了深層連結,否則
NavDestination
將無法再連結至深層連結。這也表示您只能使用帶有字串路線的 navigate 函式超載,前往目的地的路線。這項修正可解決安全漏洞,該漏洞會讓深層連結連往可能受保護的目的網頁。(Ie30e6)
依附元件更新
- Navigation Safe Args 現在依附於 Kotlin 1.9.24,而非 Kotlin 2.X,確保開發人員不會被迫更新。(a4129a)
- Navigation Compose 現在依附於 Compose
1.7.2
。
2.8.0 版
2024 年 9 月 4 日
發布 androidx.navigation:navigation-*:2.8.0
。2.8.0 版包含這些修訂版本。
自 2.7.0 版以來的重要異動
Navigation Kotlin DSL 類型安全
- Navigation 現在使用 Kotlin 序列化,為 Kotlin DSL (由 Navigation Compose 使用) 提供類型安全,讓您可以透過類型安全的物件和資料類別,在導覽圖中定義目的地:
// Define a home destination that doesn't take any arguments
@Serializable
object Home
// Define a profile destination that takes an ID
@Serializable
data class Profile(val id: String)
// Now define your NavHost using type safe objects
NavHost(navController, startDestination = Home) {
composable<Home> {
HomeScreen(onNavigateToProfile = { id ->
navController.navigate(Profile(id))
})
}
composable<Profile> { backStackEntry ->
val profile: Profile = backStackEntry.toRoute()
ProfileScreen(profile)
}
}
詳情請參閱 Navigation Compose 與類型安全相遇的網誌文章。
Navigation Compose 預測返回功能
- Navigation Compose 現在透過 compose-animation 提供的新
SeekableTransitionState
API,支援預測的應用程式內返回功能。這樣一來,您就能使用返回手勢,透過自訂轉場效果查看先前的目的地,再決定是否透過完成手勢提交交易或取消。
Navigation Fragment 可組合項
- 新增
navigation-fragment-compose
構件,其中包含NavHostFragment
的ComposableNavHostFragment
替代方案,可讓您將可組合目的地新增至 Navigation XML 檔案。每個composable
目的地都必須以頂層、無引數的@Composable
方法表示,其完整修飾名稱會用於每個目的地的android:name
屬性。當您前往其中一個目的地時,系統會建立包含片段,以便顯示可組合項內容。
// In HomeScreen.kt
@Composable
fun HomeScreen() {
// Your Composable content here
}
// In your navigation.xml
<composable
android:id="@+id/home_screen"
android:name="com.example.HomeScreenKt\$HomeScreen" />
其他變更
- Navigation Compose 現在依附於 Compose 1.7.0。
- Navigation 現在提供新的
CollectionNavType<T>
類別,這是NavType<T>
的子類別,可用於集合型引數,例如清單、陣列、地圖。所有預設NavType
陣列 (IntArrayType
、LongArrayType
、FloatArrayType
、BoolArrayType
和StringArrayType
) 現已繼承自這個新類別。 NavType
現在內建支援 Int、String、Boolean、Float 和 Long 的清單。
2.8.0-rc01 版
2024 年 8 月 21 日
發布 androidx.navigation:navigation-*:2.8.0-rc01
。2.8.0-rc01 版包含這些修訂項目。
修正錯誤
- 修正在將頂層 Enum 類別做為類型安全引數傳遞時,導覽發生當機的問題。(I0ba76、b/358137294)。
- Navigation 2.8 現已可正確搭配 SDK 34 運作,但在 2.9 版與其他 AndroidX 程式庫一併推出前,不會切換至 SDK 35。(b/358798728)
2.8.0-beta07 版
2024 年 8 月 7 日
發布 androidx.navigation:navigation-*:2.8.0-beta07
。2.8.0-beta07 版包含這些修訂版本。
已知問題
- 由於 b/358137294,只有在其他類別中巢狀的 Enums 才支援原生支援。下一個版本將支援頂層列舉。
修正錯誤
- 導航至重複或共用目的地時,系統會優先從圖表中目前位置前往最相符的目的地。(Ic89a4、b/352006850)。
- 安全參數中的導覽功能現在新增了
NavType.EnumType
。也就是說,Enum
類型不再需要自訂NavType
。請注意,Enum
的SerialName
必須是預設的完整名稱。(I66d22、b/346475493)。 - Safe Args 中的導覽功能已新增內建支援,可用於 nullable 引數類型,包括
Int?
、Long?
、Float?
、Boolean?
和Enum<*>?
。(I32d13、I1c580、Ifba66、I978b0、Ide076、b/351994237)。 - 如果傳遞至
NavGraph
的startDestination
路徑與startDestination.route
完全相同,NavGraph
的startDestination
就會使用預設引數值。(I13762、b/354046047)。
2.8.0-beta06 版
2024 年 7 月 24 日
發布 androidx.navigation:navigation-*:2.8.0-beta06
。2.8.0-beta06 版包含這些修訂項目。
修正錯誤
- 修正
WrongStartDestinationType
Lint 檢查功能未檢查傳入類型類別的伴隨物件,導致 Lint 無法偵測錯誤的問題。(I92b09)
2.8.0-beta05 版
2024 年 7 月 10 日
發布 androidx.navigation:navigation-*:2.8.0-beta05
。2.8.0-beta05 版包含這些修訂版本。
修正錯誤
- 修正當巢狀
NavGraphs
共用相同startDestination
路徑時,singleTop
導覽功能異常終止的問題。(I17b94、b/294408596)
2.8.0-beta04 版
2024 年 6 月 26 日
發布 androidx.navigation:navigation-*:2.8.0-beta04
。2.8.0-beta04 版包含這些修訂項目。
修正錯誤
- 導覽功能現在支援在路徑引數中使用空字串進行導覽。(Ic5dbd、b/339481310)。
- 針對直接透過
@Serializable(with =...)
在類別欄位上宣告的自訂序列化器,改善錯誤訊息,以便說明這項功能目前不受支援。(I052b0、b/341319151) SavedStateHandleFactory
測試 API 現在可用於非 Android 測試,但需要 Robolectric 支援使用 Bundle 的引數剖析。(I76cdc、b/340966212)- 修正在 Compose 中使用類型安全導覽功能時,在程序終止後還原狀態時發生的當機問題。(Ia8f38、b/341801005)。
- 修正 Navigation Compose 中的問題:取消預測返回手勢後,使用者返回的
NavBackStackEntry
不會返回RESUMED
生命週期狀態。這也能確保返回的目的地正確地以動畫效果回復,而不是在快速滑動後自動定位。(I97a0c、b/346608857) - 使用 Navigation Compose 的預測返回功能時,彈出的目的地現在會有正確的 z 順序,可在傳入目的地上正確顯示動畫。(I2077b、b/345993681)。
2.8.0-beta03 版
2024 年 6 月 12 日
發布 androidx.navigation:navigation-*:2.8.0-beta03
。2.8.0-beta03 版包含這些修訂項目。
API 變更
CollectionNavType
有新的抽象emptyCollection()
方法。覆寫此方法,以便處理以引數形式傳入的空集合。(Ie4d84、b/341723133)。
修正錯誤
- 已新增
NavType.serializeAsValue
和serializeAsValues
說明文件,強調最終輸出內容應以 Uri 編碼。(Ida6bd、b/344943214)。 - 修正了使用空值
CollectionNavType
引數呼叫toRoute<T>
時發生的異常終止問題。使用空值CollectionNavType
導覽時,輸出引數會是 Serializable 類別中宣告的預設值,如果沒有預設值,則會是emptyCollection()
的傳回值。(I84158、Id630f、b/342672856)。
2.8.0-beta02 版
2024 年 5 月 29 日
發布 androidx.navigation:navigation-*:2.8.0-beta02
。2.8.0-beta02 版包含這些修訂項目。
修正錯誤
- 修正了在使用
NavBackStackEntry.toRoute
搭配可為空值的自訂NavType
時,ClassCastException
發生當機的問題。(I1c29b、b/342239473)。 - 修正導覽返回堆疊狀態還原問題,當您嘗試還原無法透過目前目的地 ID 存取的返回堆疊項目時,就會發生此問題。由於路線由 ID 支援,因此使用路線建構的目的地也受到影響。這也修正了因呼叫具有相同基礎問題的
clearBackStack()
而導致的當機問題。(I423c3、b/339908057)。
2.8.0-beta01 版
2024 年 5 月 14 日
發布 androidx.navigation:navigation-*:2.8.0-beta01
。2.8.0-beta01 版包含這些修訂項目。
API 變更
SavedStateHandle.toRoute()
現在會針對自訂引數類型接收typeMap
參數。(Ie39fb、b/339026523)。- 已將測試 API 新增至
navigation-testing
,以便從 Kotlin 可序列化物件建立SavedStateHandle
。(Id4867、b/339080702)
修正錯誤
- 新增 Navigation Kotlin DSL 函式缺少的參數文件。(I26a36)
2.8.0-alpha08 版本
2024 年 5 月 1 日
發布 androidx.navigation:navigation-*:2.8.0-alpha08
。2.8.0-alpha08 版包含這些修訂項目。
Navigation Compose 中的 Safe Args
- 我們已完成Navigation Compose 和 Navigation Kotlin DSL 使用者 (以 Kotlin 序列化為基礎) 的編譯時間類型安全支援工作,先前實驗性的 API 現已穩定運作。(Iea94d、I0eb0d、I873b7、I3a64b、I6c3a2、I11f0b、Ic3032、I8d394、I95710、Ice060、Id0e55、I45f8b、Idcdaf、If5380、I08b23、Ia5c59、b/188693139)。
這項功能會使用 Kotlin 序列化,讓您透過類型安全的物件和資料類別,在導覽圖中定義目的地:
// Define a home destination that doesn't take any arguments
@Serializable
object Home
// Define a profile destination that takes an ID
@Serializable
data class Profile(val id: String)
// Now define your NavHost using type safe objects
NavHost(navController, startDestination = Home) {
composable<Home> {
HomeScreen(onNavigateToProfile = { id ->
navController.navigate(Profile(id))
})
}
composable<Profile> { backStackEntry ->
val profile: Profile = backStackEntry.toRoute()
ProfileScreen(profile)
}
}
詳情請參閱 Navigation Compose 與類型安全相遇的網誌文章。
新功能
navigation-fragment-compose
構件現在會為ComposableFragment
中的可組合函式提供LocalFragment
組合本機值。(If35e5)NavType
現在內建支援 Int、String、Boolean、Float 和 Long 的清單。(I4b6dd、Ia914c、b/188693139)。
2.8.0-alpha07 版
2024 年 4 月 17 日
發布 androidx.navigation:navigation-*:2.8.0-alpha07
。2.8.0-alpha07 版包含這些修訂項目。
新功能
新增
navigation-fragment-compose
構件,其中包含NavHostFragment
的ComposableNavHostFragment
替代方案,可讓您將composable
目的地新增至 Navigation XML 檔案。每個composable
目的地都必須以頂層、無引數的@Composable
方法表示,其完整修飾名稱會用於每個目的地的android:name
屬性。當您前往其中一個目的地時,系統會建立包含片段,以便顯示可組合項內容。(I0ef2e、b/265480755)// In HomeScreen.kt @Composable fun HomeScreen() { // Your Composable content here }
// In your navigation.xml <composable android:id="@+id/home_screen" android:name="com.example.HomeScreenKt\$HomeScreen" />
API 變更
- 繼續支援在 Navigation Compose 中使用以 Kotlin 序列化為基礎的方法支援 Safe Args。這些 API 尚未完成,並標示為
ExperimentalSafeArgsApi
註解。在日後的版本中,當整個 API 途徑完成後,這項註解就會移除。(Iefd95、I409c8、I5b5ac、I7e753、I960f8、I3eabd、I8ed5a、Ied2c9、I9b73c、I554db、Ib3aba、Ia668d、b/188693139)。
2.8.0-alpha06 版本
2024 年 4 月 3 日
發布 androidx.navigation:navigation-*:2.8.0-alpha06
。2.8.0-alpha06 版包含這些修訂項目。
API 變更
- 我們已開始在 Navigation Compose 中,使用以 Kotlin 序列化為基礎的方法支援 Safe Args。這些 API 尚未完成,並標示為
ExperimentalSafeArgsApi
註解。在日後的版本中,當整個 API 途徑完成後,這項註解就會移除。(I644e7、I98896、I2a1c5、I43a51、I836a1、Ic5eec、I39407、I24e41、If9e14、Ibb13e、If44d3、Icb70f、I8972f、I1d432、Icf32b、I20a14、I262aa、I7de99、I35990、I1033d、b/188693139)。
修正錯誤
NavHost
現在會使用Alignment.TopStart
做為預設的 contentAlignment 引數。這會讓其與AnimatedContent
的預設值一致,並修正從中心轉場時出現的部分異常縮放問題。(I09e72、b/330111602)。- 使用 Navigation Compose 時,如果快速揮動預測返回手勢,
NavHost
現在會正確完成自訂轉場效果,而不會立即結束。(I99017、b/327292110)
2.8.0-alpha05 版
March 20, 2024
發布 androidx.navigation:navigation-*:2.8.0-alpha05
。2.8.0-alpha05 版包含這些修訂項目。
新功能
- 您現在可以在
startDestination
路徑中直接將引數傳遞至NavGraph
的startDestination
,而無須仰賴defaultValue
。這也適用於巢狀NavGraph
startDestinations
。(I0e0b5、b/109505019、b/188693139)。
API 變更
- 新增抽象
CollectionNavType<T>
類別,這是NavType<T>
的子類別,用於集合型引數,例如清單、陣列、地圖。(Ic6d63、b/188693139)。 - 所有預設
NavType
陣列 (IntArrayType
、LongArrayType
、FloatArrayType
、BoolArrayType
和StringArrayType
) 現在都是CollectionNavType
類型 (Idcf79、b/188693139) NavType
現在提供新的開放式valueEquals
API,可判斷兩個相同類型的值是否相等。(I6cb97、b/327229511)
修正錯誤
- 深層連結中的查詢參數現在允許以引數名稱 (即
{argName}
) 為中心,以大括號包圍的值做為字串型NavTypes
的有效值。這項修正可解決以下問題:系統會將此類值視為無效 (或缺少值) 的所有類型。(I18302、b/327274038)。 - 支援路徑的
NavController
函式 (例如navigate
或popBackStack
) 現在可以正確比對填入陣列NavTypes
引數的路徑。(Iea805、b/327229511)。
2.8.0-alpha04 版
2024 年 3 月 6 日
發布 androidx.navigation:navigation-*:2.8.0-alpha04
。2.8.0-alpha04 版包含這些修訂項目。
新功能
- 您現在可以透過定義
SizeTranform
,在 Navigation Compose 中為轉場設定composable
和/或navigation
函式的初始化作業。(I91062、b/296912651)。
修正錯誤
- 修正問題:在沒有手勢的情況下使用系統返回功能時,Compose Navigation 中的
NavHost
無法正確顯示轉場效果。(Iceeae、b/325998468)
2.8.0-alpha03 版
2024 年 2 月 21 日
發布 androidx.navigation:navigation-*:2.8.0-alpha03
。2.8.0-alpha03 版包含以下修訂項目。
API 變更
NavBackStackEntry.savedStateHandle
現已標示為@MainThread
,因為它使用了必須位於主執行緒的程式碼。(Ibb988、b/299523245)。
修正錯誤
- 修正 Navigation 中的問題,該問題會導致
NavGraph
ViewModel 過早DESTROYED
,因為相關聯項目的ViewModel
並非已儲存狀態的一部分。(Ib6bb7、b/317581849)。
依附元件更新
- Navigation Compose 現在依附於 Compose 1.7.0-alpha03。
2.8.0-alpha02 版
2024 年 2 月 7 日
發布 androidx.navigation:navigation-*:2.8.0-alpha02
。查看 2.8.0-alpha02 版的修訂項。
新功能
- Navigation Compose 現在透過 compose-animation 提供的新
SeekableTransitionState
API,支援預測的應用程式內返回功能。這麼一來,您就能使用返回手勢,透過自訂轉場效果查看先前的目的地,再決定是否透過完成手勢提交交易或取消交易。(I8b8e9)。
2.8.0-alpha01 版
2024 年 1 月 24 日
發布 androidx.navigation:navigation-*:2.8.0-alpha01
。查看 2.8.0-alpha01 版的修訂項。
修正錯誤
- 修正
BackStackState
遺漏問題:在目的地上進行多次saveState
呼叫會導致儲存多個狀態,但只有第一個狀態可以還原。(I598b0、b/309559751)。 - 修正問題:使用
NavigationUI
輔助程式填入應用程式列標題時,非字串引數無法正確顯示的問題。(#636、b/316676794)
依附元件更新
- Navigation Compose 現在依附於 Compose
1.7.0-alpha01
,修正可能導致動畫尺寸異常的問題。(b/297258205)
外部貢獻
- 感謝 SimonMarquis 修正使用
NavigationUI
輔助程式填入應用程式列標題時,非字串引數的顯示問題。
2.7.7 版
2.7.7 版
2024 年 2 月 7 日
發布 androidx.navigation:navigation-*:2.7.7
。查看 2.7.7 版的修訂項。
修正錯誤
- 從 Navigation
2.8.0-alpha01
回移:修正BackStackState
外洩問題,在單一NavBackStackEntry
上進行多次saveState()
呼叫會導致儲存多個狀態,但只能還原第一個儲存的狀態。(I598b0、b/309559751)。 - 自 Navigation
2.8.0-alpha01
回移植:修正以下問題:使用NavigationUI
輔助程式填入應用程式列標題時,系統無法正確顯示非字串引數。(#636、b/316676794)
外部貢獻
- 感謝 SimonMarquis 修正使用
NavigationUI
輔助程式填入應用程式列標題時,非字串引數的顯示問題。
2.7.6 版
2.7.6 版
2023 年 12 月 13 日
發布 androidx.navigation:navigation-*:2.7.6
。2.7.6 版包含此連結所列的修訂項目。
修正錯誤
NavGraph
equals()
函式現在會正確考量其他圖表的節點,而非只考量呼叫的節點。這可確保系統不再將含有不同 ID 的節點視為相等 (I401cb、b/311414915)
2.7.5 版
2.7.5 版
2023 年 11 月 1 日
發布 androidx.navigation:navigation-*:2.7.5
。查看 2.7.5 版的修訂項。
效能改善
- 大幅改善比較兩個圖表的效能 (包括時間和分配數量)。這表示
setGraph
等呼叫 (在內部比較新圖表與現有圖表) 的速度會大幅提升,因此跳過的影格也會減少。感謝 Michał Z 進行詳細分析,讓我們得以改善這項功能。(I6ad62)。 NavHost
現在會在第一個組合傳遞作業中算繪起始目的地,而不需要等待第二個傳遞作業讀取更新的狀態。(I439a7、b/304852206)。
修正錯誤
- 修正問題:如果圖形中含有目的地,其中包含連結兩個目的地的動作,而您以相同圖形呼叫
setGraph
超過一次,則返回堆疊會彈出。(Ieaed7) - 快速連續導覽至對話方塊並將其關閉的對話方塊,將不再洩漏至
NavController.visibleEntries
清單。(I67586、b/287969970)。 - 當項目彈出後,如果
saveState
為 false,項目的ViewModel
現在會正確清除。(Idf242、b/298164648)。 - 修正如果在設定變更前,返回堆疊完全為空白,或是只有在傳入的意圖設定
FLAG_ACTIVITY_NEW_TASK
標記時才呼叫setGraph
,NavController
就可能會處理相同的深層連結多次的問題。(I73c7f)。
依附元件更新
- 使用片段的導覽功能現在依附於 Fragment 1.6.2,修正在呼叫
clearBackStack
時,巢狀片段的ViewModel
例項不會清除的問題。
2.7.4 版
2.7.4 版
2023 年 10 月 4 日
發布 androidx.navigation:navigation-*:2.7.4
。2.7.4 版包含此連結所列的修訂項目。
新功能
- 新增支援
popUpTo
使用帶有引數的路徑,以便彈回使用這些確切引數的特定項目,這與popBackStack
中的支援功能相符。(I731f4、b/299255572)。
修正錯誤
- 修正問題:如果使用
popUpTo
中斷另一個導覽,會導致FragmentNavigator
異常終止。(I3c848、b/301887045)。 - 修正系統返回按鈕導致
currentDestination
無法正確更新,無法與顯示的 Fragment 相符的問題。(Id0d6c、b/289877514)。 - 當上方對話方塊關閉時,
DialogFragment
生命週期現在會正確移至RESUMED
狀態。(I88f0d、b/301811387)。
2.7.3 版
2.7.3 版
2023 年 9 月 20 日
發布 androidx.navigation:navigation-*:2.7.3
。查看 2.7.3 版的修訂項。
修正錯誤
- 修正 Navigation with Fragments 的問題,該問題會導致
visibleEntries
清單包含不正確的項目。(I5caa9、b/288520638) - 修正問題:浮動視窗目的地 (例如
Dialogs
、Bottomsheets
等) 無法取得RESUMED
生命週期回呼。(I3b866、b/287505132)。
2.7.2 版
2.7.2 版
2023 年 9 月 6 日
發布 androidx.navigation:navigation-*:2.7.2
。查看 2.7.2 版的修訂項。
修正錯誤
- Navigation 現在依附於 Lifecycle
2.6.2
,修正rememberSaveable
和 Navigation ComposeNavHost
之間的互動,避免在程序終止並重建後,目的地的rememberSaveable
狀態和任何ViewModel
擁有的SavedStateHandle
例項無法正確還原。(b/298059596、b/289436035) - 修正問題:在 Navigation Compose 中同時顯示多個對話方塊時,部分遮蔽的對話方塊 (例如非最上層的對話方塊) 會處於
CREATED
生命週期狀態,而非STARTED
狀態。(aosp/2728520、b/289257213) - 修正問題:在 Navigation Compose 中同時顯示多個對話方塊時,關閉最上層對話方塊會導致新的最上層對話方塊卡在
STARTED
生命週期狀態,而非正確移至RESUMED
。(aosp/2629401、b/286371387)。 - 如果 Navigation Safe Args 未實際執行,就不會急著將其工作例項化。(I0e385、b/260322841)。
依附元件更新
- Navigation Compose 現在依附於 Compose 1.5.1。
2.7.1 版
2.7.1 版
2023 年 8 月 23 日
發布 androidx.navigation:navigation-*:2.7.1
。查看 2.7.1 版的修訂項。
修正錯誤
- 修正 Navigation with Compose 的問題,當使用
Scaffold
時,嘗試存取Lifecycle.State.DESTROYED
ViewModel
可能會發生錯誤。(I1dc11、b/268422136)。
2.7.0 版
2.7.0 版
2023 年 8 月 9 日
發布 androidx.navigation:navigation-*:2.7.0
。查看 2.7.0 版的修訂項。
自 2.6.0 版以來的重要變更
Accompanist 提供的動畫
AnimatedContent
現已穩定,因此我們可以將程式碼從 Accompanist Navigation Animation 移回 Navigation Compose 本身。
也就是說,AnimatedNavHost
中所有可用於設定自訂轉場效果的支援功能,在 NavHost
中也都適用。
我們不會再對 Accompanist Navigation Animation 進行任何變更,並且很快就會正式淘汰此功能,同時提供如何改回 Navigation Compose 的指引,但如果您已使用最新的 Accompanist alpha (0.31.2-alpha
),則不需要進行任何其他 API 變更。b/197140101
修正錯誤
- 即使活動已停止和繼續執行,Navigation Compose 中的 NavHost 現在也能正確攔截系統返回呼叫。(Icb6de、b/279118447)。
依附元件更新
- Navigation 現在依附於 Compose
1.5.0
,並從1.1.0
開始。
2.7.0-rc01 版
2023 年 7 月 26 日
發布 androidx.navigation:navigation-*:2.7.0-rc01
。查看 2.7.0-rc01 版的修訂項。
修正錯誤
- 修正了以下問題:即使
NavHost
已從組合中移除,EnterTransition
和ExitTransition
lambda 仍可能保留在記憶體中。NavHost
(I893d0)。
已知問題
- Navigation 2.6.x 發生問題,使用 popUpTo 導覽時可能會導致
IllegalArgumentException
。您可以透過重構圖表來避免發生這個例外狀況,這類似於這裡提供的建議。(b/287133013)
2.7.0-beta02 版
2023 年 6 月 28 日
發布 androidx.navigation:navigation-*:2.7.0-beta02
。2.7.0-beta02 版包含以下修訂項目。
修正錯誤
- Navigation Compose 現在已為使用
popUpTo
選項的轉場效果提供正確的 z 順序。(/Ib1c3a、b/285153947)
2.7.0-beta01 版
2023 年 6 月 7 日
發布 androidx.navigation:navigation-*:2.7.0-beta01
。查看 2.7.0-beta01 版的修訂項。
修正錯誤
- 即使
Activity
已STOPPED
和RESUMED
,Navigation Compose 中的NavHost
現在仍可正確攔截系統返回呼叫。(Icb6de、b/279118447)。
2.7.0-alpha01 版
2023 年 5 月 24 日
發布 androidx.navigation:navigation-*:2.7.0-alpha01
。查看 2.7.0-alpha01 版的修訂項。
Accompanist 提供的動畫
AnimatedContent
現已穩定,我們可以將程式碼從 Accompanist Navigation Animation 移回 Navigation Compose。
也就是說,AnimatedNavHost
中所有可用於設定自訂轉場效果的支援功能,在 NavHost
中也都適用。
我們不會再對 Accompanist Navigation Animation 進行任何變更,並且很快就會正式淘汰此功能,同時提供如何改回 Navigation Compose 的指引,但如果您已使用最新的 Accompanist alpha (0.31.2-alpha
),則不需要進行任何其他 API 變更。b/197140101
修正錯誤
- 自 Navigation
2.6.0-rc02
起:修正 Fragment 中的 Navigation 問題,如果使用popUpTo
導覽,並在未重新建立其檢視畫面下彈出 Fragment,系統會停止運作。(Ieb8d4、b/281726455)
依附元件更新
- Navigation 現在依附於 Compose
1.5.0-beta01
。
2.6.0 版
2.6.0 版
2023 年 6 月 7 日
發布 androidx.navigation:navigation-*:2.6.0
。查看 2.6.0 版的修訂項。
自 2.5.0 版以來的導覽功能重要變更
NavBackStackEntry
的arguments
和傳送至OnDestinationChangedListener
的arguments
現在只是不可變引數的副本 (您在導覽到目的地時建立了這些引數)。這表示在後續存取arguments
或其他OnDestinationChangedListener
執行個體時不會反映對這些套裝組合所做的任何變更。NavDeepLink
現在支援陣列的預設值,可讓您支援對應到引數的陣列類型的重複查詢參數。NavType
現在也包含預設方法,您可以覆寫該方法以合併兩個剖析值。NavType
的自訂子類別現在可以覆寫serializeAsValue
,以便將值序列化為字串,讓序列化和反序列化程序 (透過parseValue
) 完全封裝在NavType
類別中。StringType
現在會覆寫這個方法,進而在指定的String
上呼叫Uri.encode
。
自 2.5.0 版以來 Navigation Compose 的重要變更
- 使用
NavHost
預覽可組合項時,現在會預設顯示 NavGraph 的startDestination
。 NavController.popBackStack(route)
、NavController.getBackStackEntry(route)
、NavController.clearBackStack(route)
現在都支援填入部分或完整引數的路徑。請注意,引數必須與該項目的引數完全相符。- 現在,如果嘗試使用
navDeepLink
Kotlin DSL 建立空白的NavDeepLink
,會顯示 Lint 警告,表示需要有效的 URI、動作和/或 MIME 類型才能建立深層連結。
自 2.5.0 版以來,Navigation 與 Fragment 的重要變更
NavHostFragment
不再攔截系統返回按鈕本身。這可讓基礎FragmentManager
處理系統回傳。這可讓 Fragment1.7.0-alpha01
以上版本在 Android U 裝置上提供應用程式內預測返回動畫。- 使用 Navigation 與 Fragment 時,如果嘗試手動執行
FragmentTransaction
,將片段新增至FragmentManager
的返回堆疊,現在會擲回IllegalArgumentException
。請一律透過navigate()
API 新增片段。 - 在導覽 XML 檔案的活動元素的
app:data
和app:dataPattern
屬性中將字串${applicationId}
設定為預留位置時,預留位置會在加載後自動填入背景資訊的packageName
。 - 在瀏覽和彈出
NavBackStackEntries
時,FragmentNavigator
現在會使用轉換 API。這表示NavBackStackEntry
Lifecycle
現在會等到進入和離開片段的特效完成後,再移至最終的Lifecycle.State
- 在瀏覽和彈出
NavBackStackEntries
時,DialogFragmentNavigator
現在會使用轉換 API。這表示NavBackStackEntry
Lifecycle
現在會等到DialogFragment
Lifecycle
移至DESTROYED
後,再移至DESTROYED
NavHostFragment
現在允許您在NavHostFragment
附加至FragmentManager
後立即擷取NavController
,而非僅在onCreate()
後才擷取。- Navigation 支援的動態功能模組現在依附於細部化的 Play Feature Delivery 程式庫。
- Navigation Safe Args 現在依附於 Android Gradle 外掛程式 7.3.0 版本。這表示其現已與 7.3.0 以上版本相容。
自 2.5.0 版以來 NavigationUI 的重要變更
- 將導覽圖的 ID 傳送至
AppBarConfiguration
(例如透過Menu
) 時,NavigationUI
現在只會將該導覽圖的起始目的地視為頂層目的地,而不會錯誤地標記圖中每個目的地做為頂層目的地。傳遞個別目的地 ID 的行為則維持不變。您可以在AppBarConfiguration
中透過新的isTopLevelDestination
函式,將同樣的功能提供給自己的程式碼。 NavigationUI
中用於頂端應用程式列的setupWithNavController
整合現在將android:label
中找到的ReferenceType
引數的R.string
值剖析為其字串值,而不是輸出自動產生的資源整數。- 現在如果
NavigationUI
未能透過選定的MenuItem
進行導覽,則會提供記錄。
2.6.0-rc02 版
2023 年 5 月 24 日
發布 androidx.navigation:navigation-*:2.6.0-rc02
。2.6.0-rc02 版包含以下修訂項目。
修正錯誤
- 修正片段中導覽功能的問題:如果使用
popUpTo
導覽,並從返回堆疊彈出片段,但未重新建立其檢視畫面,系統返回功能就會停止運作。(Ieb8d4、b/281726455)
2.6.0-rc01 版
2023 年 5 月 10 日
發布 androidx.navigation:navigation-*:2.6.0-rc01
。查看 2.6.0-rc01 版的修訂項。
修正錯誤
- 修正了 Navigation 與片段相關的問題,在
onResume()
生命週期回呼中,透過popUpTo
以 navigate 移除片段會導致IllegalStateException
。(I21884、b/279644470)。
2.6.0-beta01 版
2023 年 4 月 19 日
發布 androidx.navigation:navigation-*:2.6.0-beta01
。查看 2.6.0-beta01 版的修訂項。
新功能
NavBackStackEntry
現在提供自訂toString
實作項目。(Iff00b)
修正錯誤
- 將 Navigation 與 Fragment 搭配使用時,如果嘗試手動執行
FragmentTransaction
,將片段新增至FragmentManager
的返回堆疊,現在會擲回IllegalArgumentException
。請一律透過navigate()
API 新增片段。(I6d38e) - 當
navigate
在同一個畫面中新增項目,而popBackStack
則移除該項目時,返回堆疊上產生的頂端項目現在會一律傳回至RESUMED
Lifecycle.State
。(Id8067、b/276495952)。
2.6.0-alpha09 版
2023 年 4 月 5 日
發布 androidx.navigation:navigation-*:2.6.0-alpha09
。查看 2.6.0-alpha09 版的修訂項。
修正錯誤
- 修正無效路徑的檢查作業,如果
NavDestination
包含非空值NavArgument
,這個目的地路徑必須包含與非空值NavArgument
同名的引數預留位置。(Ic62bf、b/274697949)。 - 如果導覽作業缺少
Action/MimeType
比對的NavDestination
所需的非空值NavArgument
,則以Action/MimeType
為基礎的深層連結導覽會失敗。(Ibfa17、b/271777424)。 - 當
NavController
設定的圖表與先前的圖表具有相同的路線和目的地時,現在可以正確將目前的圖表節點和返回堆疊目的地,替換為新的例項。這可修正在 Navigation Compose 中使用onLaunchSingleTop
時,未儲存狀態而導致當機的問題。這也修正了導覽至與根圖表建構相關聯的目的地,以及返回堆疊錯誤的問題。(I5bc58、b/275258161、b/275407804)。
2.6.0-alpha08 版
2023 年 3 月 22 日
發布 androidx.navigation:navigation-*:2.6.0-alpha08
。查看 2.6.0-alpha08 版的修訂項。
新功能
NavHostFragment
現在允許您在NavHostFragment
附加至FragmentManager
後立即擷取NavController
,而非僅在onCreate()
後擷取。(Ic6382、b/220186282)。
修正錯誤
- 修正在彈出包含非空值引數的巢狀圖形時,會發生
NullPointerException
的問題。(6b3581、b/249988437)。 - 在使用
popUpTo
進行導覽後使用系統返回鍵時,NavController
的狀態會彈出至正確的項目。(I3a8ec、b/270447657)。 FragmentNavigator
現在會在透過系統返回或popBackStack()
彈出返回堆疊時,正確彈出項目,以及交易是否會為片段使用效果。(I81bdf)- 將片段新增至
FragmentNavigator
的FragmentManager
時,不使用導覽功能,也不會再導致應用程式異常終止。(b17204、b/274167493)
依附元件更新
- Navigation 現在依附於 Lifecycle
2.6.1
。(586fe7) - Navigation 現在依附於 SavedState
1.2.1
。(078e4e) - Navigation 現在依附於 ProfileInstaller
1.3.0
。(512f0c)
2.6.0-alpha07 版
2023 年 3 月 8 日
發布 androidx.navigation:navigation-*:2.6.0-alpha07
。查看 2.6.0-alpha07 版的修訂項目。
修正錯誤
- 採用路線的
getBackStackEntry
、popBackStack
、clearBackStack
API 變化版本,現在會採用具有可為空值的引數和可為空值的查詢參數的路線模式 (I22294、b/269302500) - 修正從
NavController
呼叫clearBackStack()
時,系統不會清除與已清除返回堆疊相關聯的片段管理員中已儲存狀態的問題。(Ic1cce、b/271190202)。 - 修正 2.6.0-alpha06 中導致迴歸的問題,在分頁間使用系統返回功能時,會突顯
BottomNavigationView
中的錯誤MenuItem
。(I634f6、b/270447657)。 - 修正 2.6.0-alpha06 中的迴歸問題,該問題會導致使用
Animation
時,NavBackStackEntry
無法移至 RESUMED 狀態。(Ib3589、b/269646882)。
2.6.0-alpha06 版
2023 年 2 月 22 日
發布 androidx.navigation:navigation-*:2.6.0-alpha06
。查看 2.6.0-alpha06 版的修訂項目。
新功能
- 使用
NavHost
預覽可組合項時,現在預設會顯示 NavGraph 的startDestination
。(I2b89f)。
API 變更
- 所有
NavController
navigate
超載現在都會加上@MainThread
註解,確保這些方法會在主執行緒上呼叫。(I2c0b0、b/263427111)。
修正錯誤
- 修正使用動態 Fragment 導覽時,嘗試導覽時發生的當機問題。(I3ee29、b/268360479)。
- 修正透過系統返回按鈕前往其他片段時,底部列不會更新為正確的所選項目的錯誤 (If559f、b/269044426)
已知問題
- 使用 Navigation 與 Fragment 時,使用
Animation
API 時,NavBackStackEntry
的生命週期無法達到RESUMED
。(b/269646882) - 使用 Navigation 與 Fragment 搭配時,如果您嘗試還原含有多個項目的返回堆疊,
BottomMenuItem
就不會正確更新。BottomNavigation
(b/270447657) - 使用 Navigation 搭配 Fragment 時,還原狀態後,當 Fragment 為
DESTROYED
時,NavBackStackEntry
Lifecycle
不會取得DESTROYED
。(b/270610768)
2.6.0-alpha05 版
2023 年 2 月 8 日
發布 androidx.navigation:navigation-*:2.6.0-alpha05
。查看 2.6.0-alpha05 版的修訂項。
新功能
NavController.popBackStack(route)
、NavController.getBackStackEntry(route)
、NavController.clearBackStack(route)
現在都支援填入部分或完整引數的路徑。請注意,引數必須與該項目的引數完全相符 (Iebd28、Ic678c、I3b37b、b/257514373)。- 在瀏覽和彈出
NavBackStackEntries
時,FragmentNavigator
現在會使用轉換 API。這表示NavBackStackEntry
Lifecycle
現在會等到進入和離開片段的特效完成後,再移至最終的Lifecycle.State
(I3cb19、b/238686802)。 - 在瀏覽和彈出
NavBackStackEntries
時,DialogFragmentNavigator
現在會使用轉換 API。這表示NavBackStackEntry
Lifecycle
現在會等到DialogFragment
Lifecycle
移至DESTROYED
後,再移至DESTROYED
(I53ee5、b/261213893)。
API 變更
NavigatorState
現在提供prepareForTransition
API,可讓Navigator
將NavBackStackEntries
移至中繼Lifecycle.State
(I42c21、b/238686802)。- 現在可以使用
backstack
屬性,存取與NavGraphNavigator
或ComposeNavigator
相關聯的返回堆疊。ComposeNavigator
現在也會揭露onTransitionComplete()
回呼,將執行導覽或popBackStack
作業的NavBackStackEntry
標示為已完成 (I02062、I718db、b/257519195)。
修正錯誤
- 現在使用
push/popWithTransition
API 且項目已開始處理時,導覽器狀態不需人工管理 (Iadbfa、b/261213893)。 - 將
launchSingleTop
與巢狀NavGraph
搭配使用時,從原始目的地到其startDestination
的所有目的地只會正確新增至返回堆疊頂端 (Id4bea、b/253256629)。 - 導覽到相同目的地並將
launchSingleTop
標記設為 true 時,Navigation 現在可以正確取代DialogFragment
例項 (I45b5a、b/149572817)。 - 使用 19 個字元的引數時,Navigation SafeArgs 不會再造成編譯錯誤 (Id60bc、b/257110095)。
2.6.0-alpha04 版
2022 年 11 月 9 日
發布 androidx.navigation:navigation-*:2.6.0-alpha04
。查看 2.6.0-alpha04 版的修訂項。
新功能
NavType
的自訂子類別現在可以覆寫serializeAsValue
,以便將值序列化為字串,讓序列化和反序列化程序 (透過parseValue
) 完全封裝在NavType
類別中。StringType
現在會覆寫這個方法,進而在指定的String
上呼叫Uri.encode
。(Ie5213、b/247637434)- 現在如果
NavigationUI
未能透過選定的MenuItem
進行導覽,則會提供記錄 (I2af5a、b/247730357)
修正錯誤
- 系統現在會延遲剖析 Navigation 深層連結,而不會在圖表初始化時進行剖析,這有助於改善應用程式啟動時的效能。(Iab0ab)
- 修正了透過深層連結前往含有空值預設引數的目的地後,向上導覽所引發的當機問題。(I51c24、b/243183636)。
依附元件更新
- Navigation 支援的動態功能模組現在依附於細部化的 Play Feature Delivery 程式庫。(Ib4ddc)
- Navigation Safe Args 現在依附於 Android Gradle 外掛程式 7.3.0 版本。這表示其現已與 7.3.0 以上版本相容。(I47e49)
2.6.0-alpha03 版本
2022 年 10 月 24 日
發布 androidx.navigation:navigation-*:2.6.0-alpha03
。查看 2.6.0-alpha03 版的修訂項。
修正錯誤
- 自 Navigation
2.5.3
起:當Crossfade
沒有可用於組合的目的地時,NavHost
不會再造成NoSuchElementException
,而只會略過組合作業。(Ieb46e、b/253299416) - 自 Navigation
2.5.3
起:修正目的地從返回堆疊彈出時,系統未忘記及移除已儲存的 Compose 狀態 (例如使用rememberSaveable
的情形) 的問題。(I64949)
依附元件更新
- Navigation 現在依附於 Fragment
1.5.4
。(Icd424)
2.6.0-alpha02 版本
2022 年 10 月 5 日
發布 androidx.navigation:navigation-*:2.6.0-alpha02
。查看 2.6.0-alpha02 版的修訂項。
行為變更
- 將導覽圖的 ID 傳送至
AppBarConfiguration
(例如透過Menu
) 時,NavigationUI
現在只會將該導覽圖的起始目的地視為頂層目的地,而不會錯誤地標記圖中每個目的地做為頂層目的地。傳遞個別目的地 ID 的行為則維持不變。您可以在AppBarConfiguration
中透過新的isTopLevelDestination
函式,將同樣的功能提供給自己的程式碼。(Ie936e、b/238496771)
修正錯誤
navigation:navigation-fragment
元件現在依附於 Fragment 版本1.5.2
。(I00ba4)- 前往
FloatingWindow
目的地 (例如對話方塊) 時,不會再更新所選選單項目。(I4cde8、b/240308330)
2.6.0-alpha01 版本
2022 年 9 月 7 日
發布 androidx.navigation:navigation-*:2.6.0-alpha01
。查看 2.6.0-alpha01 版的修訂項。
新功能
NavigationUI
中用於頂端應用程式列的setupWithNavController
整合現在將android:label
中找到的ReferenceType
引數的R.string
值剖析為其字串值,而不是輸出自動產生的資源整數 (I5f803、b/167959935)。NavDeepLink
現在支援陣列的預設值,可讓您支援對應到引數的陣列類型的重複查詢參數。NavType
現在也包含預設方法,您可以覆寫該方法以合併兩個剖析值 (Id68c3、b/209977108)。- 在導覽 XML 檔案的活動元素的
app:data
和app:dataPattern
屬性中將字串${applicationId}
設定為預留位置時,預留位置會在加載後自動填入背景資訊的packageName
(Iaabde、b/234223561)。 - 現在,如果嘗試使用
navDeepLink
Kotlin DSL 建立空白的NavDeepLink
,會顯示 Lint 警告,表示需要有效的 URI、動作和/或 MIME 類型才能建立深層連結 (I08d2f、b/154038883)。
API 變更
- 新增新的
NavDestination
擴充功能函式,以將含有android:label="{arg}"
格式的引數的動態標籤剖析為字串。將R.string
值剖析為其字串值,以支援ReferenceType
引數 (I07d89、b/236269380)。
行為變更
- NavBackStackEntry 的
arguments
和傳送至OnDestinationChangedListener
的arguments
現在只是不可變引數的副本 (您在導覽到目的地時建立了這些引數)。這表示在後續存取arguments
或其他OnDestinationChangedListener
執行個體時不會反映對這些套裝組合所做的任何變更 (I676f5)。
修正錯誤
- 在 Navigation
2.5.2
中:Dynamic Navigation 現在會先嘗試從其他模組安裝 Activity 目的地,然後再導覽到這些目的地 (Ia2c16、b/240292838)。 - 自 Navigation
2.5.2
起:導覽到相同目的地並將launchSingleTop
標記設為 true 時,Navigation 現在可以正確取代 Fragment 例項 (I5a2f1、b/237374580)。 - 自 Navigation
2.5.2
起:修正了因導覽到雙巢狀結構圖而造成的IllegalStateException
,該結構圖會與新的彈出起始目的地分享父項 (I9f7cb、b/243778589)。
2.5 版本
2.5.3 版本
2022 年 10 月 24 日
發布 androidx.navigation:navigation-*:2.5.3
。查看 2.5.3 版的修訂項。
修正錯誤
- 當
Crossfade
沒有可用於組合的目的地時,NavHost
不會再造成NoSuchElementException
,而只會略過組合作業。(Ieb46e、b/253299416) - 修正目的地從返回堆疊彈出時,系統未忘記及移除已儲存的 Compose 狀態 (例如使用
rememberSaveable
的情形) 的問題。(I64949)
2.5.2 版本
2022 年 9 月 7 日
發布 androidx.navigation:navigation-*:2.5.2
。查看 2.5.2 版的修訂項。
修正錯誤
- Dynamic Navigation 現在會先嘗試從其他模組安裝 Activity 目的地,然後再導覽到這些目的地 (Ia2c16、b/240292838)。
- 導覽到相同目的地並將
launchSingleTop
標記設為 true 時,Navigation 現在可以正確取代 Fragment 例項 (I5a2f1、b/237374580)。 - 修正了因導覽到雙巢狀結構圖而造成的
IllegalStateException
,該結構圖會與新的彈出起始目的地分享父項 (I9f7cb、b/243778589)。
依附元件更新
- Navigation
2.5.2
現在依附於 Fragment1.5.2
(aosp/2178734)。
2.5.1 版本
2022 年 7 月 27 日
發布了 androidx.navigation:navigation-*:2.5.1
。2.5.1 版包含此連結所列的修訂項目。
修正錯誤
- 使用儲存在
Bundle
中的自訂引數類型時,Navigation Safe Args
不會再導致產生類別的淘汰警告。(Id86ed、b/237725966)
依附元件更新
- Navigation 程式庫現在依附於 Lifecycle
2.5.1
(Ib4451)。 - 導覽程式庫現在依附於 Activity
1.5.1
(I3efe8)。 - 導覽程式庫現在依附於 Fragment
1.5.1
(I56177)。
2.5.0 版本
2022 年 6 月 29 日
發布了 androidx.navigation:navigation-*:2.5.0
。2.5.0 版包含此連結所列的修訂項目。
自 2.4.0 版本以來的重要異動
- CreationExtras 整合 -
Navigation
現在可透過 Lifecycle2.5.0
的CreationExtras
提供無狀態ViewModelProvider.Factory
。
Navigation SafeArgs
Navigation Safe Args
已升級Android Gradle Plugin
依附元件以依賴7.0.4
,捨棄7.0
前的 AGP 版本相容性。- 新增 build.gradle 的命名空間屬性支援 (而不是 applicationId)。
其他變更
visibleEntries
API 已不再處於實驗階段,並且提供函式,用於擷取目的地目前可根據NavController
顯示的所有項目。
2.5.0-rc02 版本
2022 年 6 月 15 日
發布了 androidx.navigation:navigation-*:2.5.0-rc02
。查看 2.5.0-rc02 版的修訂項。
修正錯誤
- 修正使用 Navigation Compose
NavHost
時,快速切換底部目的地時會發生的當機問題。(I3979a、b/234054916)。 - 使用不含
applicationId
的applicationIdSuffix
和命名空間,或applicationId
和命名空間不同時,Navigation SafeArgs
不會再當機。(I754b1、b/233119646) NavArgument
現在有自訂的toString()
函式,可顯示引數的內部值。(I900a8)
2.5.0-rc01 版本
2022 年 5 月 11 日
發布 androidx.navigation:navigation-*:2.5.0-rc01
。查看 2.5.0-rc01 版的修訂項。
新功能
- 新增 Lint 規則,以禁止在
navigation.xml
檔案中將<deeplink>
元素放在<activity>
元素中。(Ic15a5、b/178403185)
修正錯誤
- 系統會依照預期順序處理
NavHost
和DialogHost
中的可組合元件範圍;也就是說,系統會先處理內部可組合元件,再處理外部可組合元件。(I157e6) - Navigation SafeArgs 現可透過
ArgumentsGenerationTask
中的PathSensitivity.RELATIVE
允許快取移動位置。這表示您可以在本機版本中重新使用持續整合 (CI) 版本的快取項目。(I5f67c、b/173420454) - 更新
UnrememberedGetBackStackEntryDetector
Lint 規則,確保getBackStackEntry()
呼叫前後的remember
呼叫也會傳入NavBackStackEntry
物件做為索引鍵。(Ib7081、b/227382831)
2.5.0-beta01 版本
2022 年 4 月 20 日
發布 androidx.navigation:navigation-*:2.5.0-beta01
。查看 2.5.0-beta01 版的修訂項。
修正錯誤
DialogNavigator
現在在執行dismiss()
呼叫時會使用popWithTransition
。當您dialog
目的地中使用ViewModel
時,如果使用系統返回機制或輕觸對話方塊外部區域關閉對話方塊,可能會導致IllegalStateException
,這類競爭狀況的問題已獲得修正。(Id7376、b/226552301)
依附元件更新
- Navigation 現在依附於 Lifecycle
2.5.0-beta01
,並修正以下問題:如果使用多個返回堆疊,將非主要底部瀏覽分頁標籤中的一個NavHost
在另一個NavHost
內建立巢狀結構時會發生IllegalStateException
。
2.5.0-alpha04 版本
2022 年 4 月 6 日
發布 androidx.navigation:navigation-*:2.5.0-alpha04
。2.5.0-alpha04 版包含此連結所列的修訂項目。
API 變更
visibleEntries
已不再處於實驗階段 (I4829f、b/225394514)。
修正錯誤
- NavHost 現在取決於
NavController
中的visibleEntries
,以決定要撰寫的項目。這表示在使用巢狀的 NavHost 時,內部的NavHost
現已可正確顯示動畫效果。(I4ba2b、b/225394514) NavController
提供的visibleEntries
StateFlow
現在會以項目的最大生命週期狀態為基準,而非目前的生命週期狀態。也就說,即使navController
的代管生命週期低於 STARTED,可見的項目清單仍會維持不變。(I9e2a8、b/225394514)SavedStateViewFactory
現在支援使用CreationExtras
(即使已透過SavedStateRegistryOwner
初始化也沒問題)。如果提供額外項目,系統將忽略初始化的引數 (I6c43b、b/224844583)NavDeepLink
現在可以在沒有值的狀況下,以單一查詢參數來剖析 URI。(I0efe8、b/148905489)- 現在,系統會將空白字串視為深層連結中的有效引數。(I70a0d、b/217399862)
- 使用命名空間且沒有任何
AndroidManifest.xml
時,Navigation Safe Args
不會再異常終止 (I17ccf、b/227229815)
2.5.0-alpha03 版本
2022 年 2 月 23 日
發布 androidx.navigation:navigation-*:2.5.0-alpha03
。查看 2.5.0-alpha03 版的修訂項。
API 變更
- 現可將
CreationExtras
傳入by navGraphViewModels
以建立ViewModel
(I29217、b/217618359)
修正錯誤
NavDeepLinks
現在可正確支援嵌入路徑/深層連結 URI 中經過編碼的新行字元。(I513d1、b/217815060)。- 現在將
CreationExtras
與NavBackStackEntries
搭配使用時可正確建立 ViewModel。(I69161、b/217617710)。 - Navigation Safe Args 現在支援使用
build.gradle
中定義的命名空間,取代 AndroidManifest 中的套件 (I659ef、b/217414933)
2.5.0-alpha02 版本
2022 年 2 月 9 日
發布 androidx.navigation:navigation-*:2.5.0-alpha02
。查看 2.5.0-alpha02 版的修訂項。
修正錯誤
- 自 Navigation
2.4.1
起:使用含有巢狀結構圖的 viewbinding 時,NavHostFragment
現在可正確設定OnBackPressedDispatcher
(Ifbb51、b/214577959)。 - 自 Navigation
2.4.1
起:透過多個巢狀結構NavGraph
設定深層連結時,返回堆疊現在可正確納入中繼起始目的地。(I504c0、b/214383060)
2.5.0-alpha01 版本
2022 年 1 月 26 日
發布 androidx.navigation:navigation-*:2.5.0-alpha01
。查看 2.5.0-alpha01 版的修訂項。
新功能
NavBackStackEntry
現已整合 ViewModel CreationExtras (先前為 Lifecycle2.5.0-alpha01
的部分元件)。(Ib9fe2、b/207012490)
修正錯誤
- 在 Fragment 的
onCreate()
中存取透過by navGraphViewModels()
建立的ViewModel
時會失敗並導致IllegalStateException
,這個問題已獲得修正。(I8a14d) NavDeepLink
無需再對引數進行兩次不必要的解碼,這表示適當的引數現在會傳遞至最終目的地。(I31b0a、b/210711399)
Safe Args
- Safe Args 現在依附於 Android Gradle 外掛程式 7.0.4 版本。這表示 Navigation Safe Args 將不再支援 Android Studio 7.0 以下版本,但現已支援 Android Gradle 外掛程式 7.1.0 以上版本 (I41c88、b/213086135、b/207670704)
2.4.2 版本
2.4.2 版本
2022 年 4 月 6 日
發布 androidx.navigation:navigation-*:2.4.2
。2.4.2 版包含此連結所列的修訂項目。
修正錯誤
- 從 Navigation
2.5.0-alpha03
向後移植:NavDeepLinks
現可正確支援嵌入路徑/深層連結 URI 中經過編碼的新行字元。(I513d1、b/217815060) - 從 Navigation
2.5.0-alpha03
向後移植:Navigation SafeArgs 現已支援使用build.gradle
中定義的命名空間來取代 AndroidManifest 中的套件。(I659ef、b/217414933) - 從 Navigation
2.5.0-alpha04
向後移植:使用命名空間且沒有AndroidManifest.xml
時Navigation Safe Args
不會再損毀。(I17ccf、b/227229815) - 從 Navigation
2.5.0-alpha04
向後移植:現在會將空白字串視為深層連結中的有效引數。(I70a0d、b/217399862)
2.4.1 版本
2.4.1 版本
2022 年 2 月 9 日
發布 androidx.navigation:navigation-*:2.4.1
。2.4.1 版包含此連結所列的修訂項目。
修正錯誤
- 使用含有巢狀結構圖的 viewbinding 時,
NavHostFragment
現在可正確設定OnBackPressedDispatcher
(Ifbb51、b/214577959)。 - 透過多個巢狀結構
NavGraph
設定深層連結時,返回堆疊現可正確納入中繼起始目的地。(I504c0、b/214383060) - 自 Navigation
2.5.0-alpha01
向後移植:在 Fragment 的onCreate()
中存取透過by navGraphViewModels()
建立的 ViewModel 時會失敗並導致IllegalStateException
,這個問題已獲修正。(I8a14d) - 從 Navigation
2.5.0-alpha01
向後移植:NavDeepLink
無需再對引數進行兩次不必要的解碼,這表示適當的引數現已傳遞至最終目的地。(I31b0a、b/210711399) - 從 Navigation
2.5.0-alpha01
向後移植:Safe Args 現在依附於 Android Gradle 外掛程式 7.0.4 版本。這表示 Navigation Safe Args 將不再支援 Android Studio 7.0 以下版本,但現已支援 Android Gradle 外掛程式 7.1.0 以上版本 (I41c88、b/213086135、b/207670704)
2.4.0 版本
2.4.0 版本
2022 年 1 月 26 日
發布 androidx.navigation:navigation-*:2.4.0
。2.4.0 版包含此連結所列的修訂項目。
2.3.0 版之後的重要異動
- 所有 Navigation 構件都已使用 Kotlin 重新編寫,對於採用一般項目的類別 (例如
NavType
子類別) 改善了其「是否可為空值」的屬性。過去屬於-ktx
構件的所有 Kotlin 擴充功能都已移至各自的主要構件中。-ktx
構件會繼續發布,但不會有任何內容。 navigation-fragment
構件現可透過新的AbstractListDetailFragment
,納入預先建構的雙窗格版面配置實作項目。此片段會使用SlidingPaneLayout
管理清單窗格 (也就是子類別提供的清單) 和詳細資料窗格,其使用NavHostFragment
做為實作方式,如實作範例中所示。NavController
上的currentBackStackEntryAsFlow()
方法提供Flow
,會在每次目前的NavBackStackEntry
變化時發出。您可以將這個流程做為手動管理OnDestinationChangedListener
的替代選項。- NavController 現在提供透過實驗性
visibleEntries
屬性,擷取所有可見NavBackStackEntry
執行個體清單做為StateFlow
的功能。 - 現在可以擴充
NavType
類別來建立自訂 NavType。只有在以程式輔助方式 (例如透過 Navigation Graph Kotlin DSL) 建構導覽圖時才支援自訂類型。 Navigation 現在提供
findStartDestination()
和getHierarchy()
API,可用來實作自訂 NavigationUI。findStartDestination()
是NavGraph
的擴充功能函式,可用來找出前往特定導覽圖時才會顯示的實際起始目的地,即使startDestination
本身就是巢狀結構的NavGraph
也沒問題。getHierarchy()
是NavDestination
上的函式,可用來驗證特定目的地是否位於另一個階層中。val matchingRoute: Boolean = destination.hierarchy.any { it.route == routeToFind }
更新原本接受
BottomNavigationView
的NavigationUI
方法,改為接受 Material1.4.0
中引入的父類別NavigationBarView
。這樣即可將這些方法與NavigationRailView
搭配使用。當透過 XML 加載
<action>
元素時,動畫屬性可使用透過app:enterAnim="?attr/transitionEnter"
語法從主題中擷取的屬性。Safe Args 現在會為每個
NavArgs
類別產生fromSavedStateHandle()
方法。(#122、b/136967621)class HomeViewModel(savedStateHandle: SavedStateHandle) : ViewModel() { // Create a HomeDestinationArgs class with type safe accessors for each argument // defined on your destination private val args = HomeDestinationArgs.fromSavedStateHandle(savedStateHandle) }
導覽路徑和 Kotlin DSL
先前版本的 Navigation 依附於每個具有常數整數 ID 的目的地,該 ID 可用來從同層目的地中識別對應的目的地,並允許直接或透過動作 navigate()
至該目的地。這個做法仍然有效且實用,尤其當您要在 XML 中定義導覽圖,且可以使用自動產生的 R.id
常數或 Safe Args (會在建構時間使用這些常數產生程式碼) 時。然而,當您要在執行階段以程式輔助方式建構完整動態圖形時,這種不重複整數的系統便無法透過 Navigation Kotlin DSL 擷取所需的語意含義和展現方式。
這個版本推出了一個新選項,有助於依照目的地「路徑」在導覽圖明確識別目的地。「路徑」為定義目的地唯一路徑的 String
。過去接受目的地 ID 的所有 Kotlin DSL 方法現已淘汰,替換為接受路徑的同等 API。
每個路徑都應視為定義該目的地的 Uri
的「路徑」部分,例如 home
、profile/{userId}
、profile/{userId}/friends
等。如果目的地識別資訊與特定內容相關聯,這些動態引數應屬於路徑的一部分,並遵循與隱含深層連結相同的規則。
以往只接受 ID 的所有 NavController
API 現在都具有接受路徑 String
的超載,包含 navigate()
、popBackStack()
、popUpTo()
和 getBackStackEntry()
。
這對 API 產生了一些影響:
- Kotlin DSL 上的
popUpTo
Kotlin 屬性已淘汰,請改用popUpToId
。 getStartDestination()
API 已淘汰,並改用getStartDestinationId()
。
與依照 ID 導覽不同的是,依照路徑導覽時會遵循與隱含深層連結相同的規則;您可以直接導覽至任何巢狀圖表中的任何目的地,確保這些路徑可在多模組專案中使用,無須為每個目的地明確加上外部可見的深層連結。
Navigation Compose
navigation-compose
構件可提供 Navigation Component 和 Jetpack Compose 之間的整合功能,並使用 @Composable
函式做為應用程式的目的地。
這個版本提供以下功能:
NavHost
可組合元件,可讓您使用composable
和dialog
目的地透過 Kotlin DSL 建構導覽圖,並支援選用導覽器,例如來自 Accompanist Navigation Material 的導覽器。- 提供目的地之間交叉漸變效果的必要支援。Acomcomistist Navigation Animation 可讓您使用實驗性 Compose API 控制進入與退出的轉場效果。
- 將
Lifecycle
的範圍限定為成各個可組合元件目的地。每個目的地只會在任何進入的轉場效果結束時達到RESUMED
狀態,並且在退出的轉場效果開始時立即降為STARTED
。如此一來,只要在Lifecycle
為RESUMED
狀態時觸發navigate
呼叫,即可避免所有的IllegalStateException
和多點觸控問題。 - 在目的地層級限定
ViewModel
的範圍 (透過 Lifecycle ViewModel Compose2.4.0
的viewModel()
API 或 Hilt Navigation Compose1.0.0
的hiltViewModel()
),提供一個設定變更後仍繼續存在並位於返回堆疊 (當可組合元件內容以其他方式處理時) 的範圍,同時在 ViewModel 的onCleared()
中提供信號,指示系統永久處理及清除與該NavBackStackEntry
相關聯的狀態。 - 在目的地層級限定
rememberSaveable
狀態的範圍,確保系統會自動儲存所有可組合元件的狀態,並在您返回目的地時還原這些狀態。 - 完整支援儲存
NavController
狀態及其目的地的狀態,並在程序死亡及重建後還原這些狀態。 - 自動與系統返回按鈕整合。
支援傳遞引數、將深層連結附加至目的地,以及將結果傳回至之前的目的地。
rememberNavController()
和currentBackStackEntryAsState()
中的特定 Compose 輔助工具,可讓您提升狀態,並將NavController
連接至NavHost
外的可組合元件 (例如底部導覽列)。
val navController = rememberNavController()
Scaffold { innerPadding ->
NavHost(navController, "home", Modifier.padding(innerPadding)) {
composable("home") {
// This content fills the area provided to the NavHost
HomeScreen()
}
dialog("detail_dialog") {
// This content will be automatically added to a Dialog() composable
// and appear above the HomeScreen or other composable destinations
DetailDialogContent()
}
}
}
詳情請參閱 Compose Navigation 指南。
多個返回堆疊
NavController 負責管理目的地的返回堆疊,當您 navigate()
至其堆疊位置時會在返回堆疊中新增目的地,並且在您呼叫 popBackStack()
或觸發系統返回按鈕時移除這些目的地。我們擴展了導覽圖 XML 中現有 NavOptions
類別以及與 <action>
元素的整合功能,以支援儲存及還原返回堆疊的功能。
做為本次異動的一部分,onNavDestinationSelected()
、BottomNavigationView.setupWithNavController()
和 NavigationView.setupWithNavController()
的 NavigationUI
方法現在會自動儲存並還原彈出目的地的狀態,因此無需變更任何程式碼即可支援多個返回堆疊。將 Navigation 與 Fragment 搭配使用時,建議採用這個方法與多個返回堆疊整合。
用於儲存及還原狀態的基礎 API 會透過多個介面公開:
在 Navigation XML 中,
<action>
元素現可使用app:popUpToSaveState
和app:restoreState
的布林值屬性,儲存透過app:popUpTo
彈出的任何目的地狀態,並還原做為app:destination
傳遞的目的地相關聯狀態:<action android:id=”@+id/swap_stack” app:destination=”@id/second_stack” app:restoreState=”true” app:popUpTo=”@id/first_stack_start_destination” app:popUpToSaveState=”true” />
在
navOptions
Kotlin DSL 中,您可以在popUpTo
建構工具中加入restoreState
布林值屬性和saveState
布林值屬性:// Use the navigate() method that takes a navOptions DSL Builder navController.navigate(selectedBottomNavRoute) { launchSingleTop = true restoreState = true popUpTo(navController.graph.findStartDestination().id) { saveState = true } }
透過
NavOptions.Builder
手動構建NavOptions
物件時,可對接受額外saveState
參數的setPopUpTo()
使用setRestoreState()
和新的過載。NavOptions navOptions = new NavOptions.Builder() .setLaunchSingleTop(true) .setRestoreState(true) .setPopUpTo(NavGraph.findStartDestination(navController.getGraph()).getId(), false, // inclusive true) // saveState .build(); navController.navigate(selectedBottomNavId, null, navOptions);
對
popBackStack()
發出的程式輔助呼叫現可包含額外的saveState
參數。您可以使用
clearBackStack()
方法清除透過popBackStack()
或popUpToSaveState
儲存的任何狀態。
在所有情況下,NavController
會儲存及還原每個 NavBackStackEntry
的狀態,包括限定於任何導覽目的地的 ViewModel
執行個體。Navigator
API 已經過更新,可讓每個 Navigator
支援儲存及還原本身的狀態。
行為變更
NavDeepLinkBuilder
現在會將PendingIntent.FLAG_IMMUTABLE
新增至createPendingIntent()
傳回的PendingIntent
中,確保這個 API 在以 Android 12 為目標的環境中能正常運作。- Navigation 現在依附於 Lifecycle
2.3.1
,且現在會將更新NavBackStackEntry
Lifecycle
的setGraph()
、popBackStack()
、navigateUp()
和navigate()
方法標示為@MainThread
,讓 Navigation 與 Lifecycle2.3.0
中引入的主要執行緒強制執行功能保持一致。 - 深層連結現在會驗證
Uri
中是否包含所有必要引數 (不含預設值的引數)。 - 以
NavDeepLink
剖析的引數現在會將英鎊符號與問號一樣視為是路徑片段之間的分隔符,以免引數跨越英鎊符號。 - 產生動作時,Safe Args 產生的 Kotlin 程式碼現在會優先將不含預設值的引數做為參數,然後才使用含有預設值的引數。
- 產生引數時,Safe Args 現在會優先使用不含預設值的參數,然後才使用含有預設值的參數。
- Safe-Args 現在依附於 Android Gradle 外掛程式 4.2.0。如此一來,您不會再收到使用
applicationIdTextResource
的警告。
已知問題
- 修正 Navigation
2.5.0-alpha01
中的問題:從 Fragment 的onCreate()
存取透過by navGraphViewModels()
建立的ViewModel
時會失敗並顯示IllegalStateException
。(b/213504272) - 修正 Navigation
2.5.0-alpha01
中的問題:Safe Args 2.4.0 與 Android Gradle 外掛程式 7.1.0 以上版本不相容。(b/213086135) - 如果深層連結含有多個巢狀結構導覽圖,則無法正確建立完整的返回堆疊。(b/214383060)
2.4.0-rc01 版本
2021 年 12 月 15 日
發布 androidx.navigation:navigation-*:2.4.0-rc01
。查看 2.4.0-rc01 版的修訂項。
行為變更
- 由
NavDeepLink
剖析的引數現在會將英鎊符號與問號一樣視為是引數之間的分隔符。(I21309、b/180042703)
修正錯誤
- 深層連結將不再忽略含有與預留位置名稱相同值的引數。(If8017、b/207389470)
- 還原
NavController
後,NavController
使用轉場效果彈出巢狀結構目的地時將不再發生當機。(I0f7c9、b/205021623) - 使用無效的
startDestination
時,系統顯示的錯誤訊息將預設為起始目的地的路徑 (如有的話)。(I86b9d、b/208041894)
修正 Navigation Compose 錯誤
- 修正問題:使用底部導覽選單項目在起始目的地和其他目的地之間快速切換時可能會導致當機。(Ic8976、b/208887901)
- 在設定變更或程序死亡後,對話方塊目的地現在可以在螢幕頂端正確還原。(I4c0dc、b/207386169)
- 修正問題:對話方塊關閉時,系統嘗試從對話方塊的
NavBackStackEntry
擷取ViewModel
的作業會失敗。(I6b96d、b/206465487) - 修正問題:將
activity
目的地與 Navigation Compose 的NavHost
搭配使用時會導致無限重組情形。(I8f64c) - 修正 Navigation Compose 中的外洩問題:系統在設定變更或程序終止後會保留舊活動的參照。(I4efcb、b/204905432)
修正 Safe Args 錯誤
- 程序停擺後,
SafeArgs
嘗試還原自訂可封裝陣列時不會再發生當機。(I618e8、b/207315994) - 修正 Safe Args 不允許布林值陣列含有
null
值的錯誤 (I8c396、b/174787525)。
2.4.0-beta02 版本
2021 年 11 月 3 日
發布 androidx.navigation:navigation-*:2.4.0-beta02
。查看 2.4.0-beta02 版的修訂項。
API 變更
- 如果導覽至其他導覽圖,系統在處理明確與隱含深層連結時會自動新增
saveState
標記,以確保這類程式碼 (例如NavigationUI.setupWithNavController
和使用多個返回堆疊的程式碼) 能正常運作。(Ic8807)
行為變更
- 深層連結模式現在是在 NavDeepLink 中 (而不是在加載期間) 延遲編譯。這樣可以改善含有深層連結的導覽圖的加載時間。(b8d257、b/184149935)
修正錯誤
- 修正問題:將
NavHost
直接加到活動的setContent()
時,系統會將移至Lifecycle.State.STARTED
後的 NavBackStackEntries 下推至Lifecycle.State.CREATED
。(Ia5ac1、b/203536683) - 在對話方塊中實際顯示前從返回堆疊彈出
DialogFragment
目的地時,實際上不會關閉對話方塊,導致系統在使用者手動關閉錯誤的對話方塊時發生當機,這類競爭狀況已獲得修正。(I687e5) - 修正問題:即使您實際上並未
navigate()
至該導覽圖,NavigationUI
上的onNavDestinationSelected
API 也會傳回true
。現在,該 API 使用的邏輯與setupWithNavController
內部使用的邏輯相同,會採用目的地的hierarchy
,只選擇與目前目的地相關聯的MenuItem
。(I2b053)
2.4.0-beta01 版本
2021 年 10 月 27 日
發布 androidx.navigation:navigation-*:2.4.0-beta01
。查看 2.4.0-beta01 版的修訂項。
新功能
- 您現在可以將
by navGraphViewModel
與路徑搭配使用,做為使用 ID 的替代方案,以便妥善支援使用 Navigation Kotlin DSL 處理 Fragment 的情況。(I901e3、b/201446416)
API 變更
visibleEntries
API 目前處於實驗階段 (I93f6f)
修正錯誤
- 在相同螢幕之間來回切換而中斷轉場效果時,系統將不再刪除 ViewModel (Id52d8、b/200817333)
- 在
NavDestination
中新增深層連結時,可為空值的NavDeepLink
引數不再需要預設值。(I5aad4、b/201320030)。 - 不同 Lifecycle 的 NavBackStackEntries 現已不再視為相等。也就是說,使用 singleTop 進行導覽,以及重新選取底部選單項目時,NavHost 可正確重新組合所有的目的地。(I1b351、b/196997433)
- 修正
AbstractListDetailFragment
的問題:導致onCreateListPaneView()
傳回的清單窗格中的layout_width
和layout_weight
屬性被錯誤處理或遭到忽略。(f5fbf3) - 對話方塊目的地的視覺化狀態現在可正確與
DialogFragmentNavigator
的狀態保持同步。也就是說,如果您手動呼叫DialogFragment
的非同步dismiss()
API,系統現在可正確清除目前現已關閉的對話方塊之上的所有對話方塊目的地。這並不會對您使用popUpTo
或popBackStack()
關閉對話方塊的情況產生任何影響。(I77ba2) AbstractAppBarOnDestinationChangedListener
現在可針對onDestinationChanged()
提供更明確的錯誤訊息。(Ie742d)
2.4.0-alpha10 版本
2021 年 9 月 29 日
發布 androidx.navigation:navigation-*:2.4.0-alpha10
。查看 2.4.0-alpha10 版的修訂項。
新功能
- NavController 現在支援透過
visibleEntries
StateFlow 擷取所有可見NavBackStackEntry
執行個體清單的功能。(Ia964e) rememberNavController()
現在接受可選用的Navigator
執行個體組合;系統會將這個執行個體加到傳回的NavController
,對選用的導覽器 (例如來自 Accompanist Navigation Material 的導覽器) 提供更完善的支援。(I4619e)
修正錯誤
- 重新建立 Activity 時,Dynamic Navigation 不會再發生當機。(Ifa6a3、b/197942869)
- 修正只有在彈回包含
NavHost
的可組合目的地後才會發生的系統返回按鈕問題。(3ed148、b/195668143) - SafeArgs 現在會以適當的參數順序產生
fromBundle()
和fromSavedStateHandle()
的引數。(I824a8、b/200059831)
2.4.0-alpha09 版本
2021 年 9 月 15 日
發布 androidx.navigation:navigation-*:2.4.0-alpha09
。查看 2.4.0-alpha09 版的修訂項。
新功能
- 您現在可以使用
clearBackStack()
方法清除透過popBackStack()
或popUpToSaveState
儲存的任何狀態。(I80a0f) - 您現在可以對巢狀結構導覽圖的建構工具傳入引數和/或深層連結的清單,而系統會自動將清單內容加到產生的圖形中。(I8a470、b/182545357)
API 變更
navArgument
Kotlin DSL 函式現在隸屬於navigation-common
,而非navigation-compose
。您必須更新匯入內容才能繼續使用這個函式。(I1d095)
行為變更
- 產生引數時,Safe Args 現在會優先使用不含預設值的參數,然後才使用含有預設值的參數。(I89709、b/198493585)
修正錯誤
- 使用 Navigation Compose 時,只有在其所有子項為
DESTROYED
狀態時,NavGraphs 才會處於DESTROYED
狀態。(I86552、b/198741720) - 可為空值的
NavDeepLink
引數不再需要使用預設值 (Ia14ef、b/198689811) - 使用新圖形呼叫
setGraph()
時,不僅會清除彈出返回堆疊之前的行為,也會一併清除所有已儲存的返回堆疊。(I97f96) - 修正問題:使用
launchSingleTop
時,系統不會通知OnDestinationChangedListener
執行個體和currentBackStackEntryFlow
。(Iaaebc)
依附元件更新
- Navigation Compose 現在依附於 Activity Compose 1.3.1。(I05829)
- Navigation Compose 現在依附於 Lifecycle ViewModel Compose
2.4.0-beta01
。(Ib86a3)
2.4.0-alpha08 版本
2021 年 9 月 1 日
發布 androidx.navigation:navigation-*:2.4.0-alpha08
。查看 2.4.0-alpha08 版的修訂項。
新功能
- 現在可以擴充
NavType
類別來建立自訂 NavType。只有透過程式輔助方式 (例如透過 Navigation Graph Kotlin DSL) 建構導覽圖時才支援自訂類型。(I78440、b/196871885)
行為變更
- 產生動作時,Safe Args 產生的 Kotlin 程式碼現在會優先將不含預設值的引數做為參數,然後才使用含有預設值的引數。(Idb697、b/188855904)
- 深層連結現在會驗證
Uri
中是否包含所有必要引數 (不含預設值的引數)。(#204、b/185527157)
修正錯誤
- 將 composable() 中的
getBackStackEntry
和previousBackStackEntry
與remember()
合併使用時,將不再導致返回堆疊中沒有目的地的例外狀況。(I75138、b/194313238) - 變更返回堆疊引數並使用
launchSingleTop=true
時,Navigation Compose 現在可正確重組。(Iebd69、b/186392337) - 使用具有 13 或 29 個目的地的圖形呼叫
setGraph
時,將不再出現ArrayIndexOutOfBoundsException
。(I1a9f1、b/195171984) - 產生 Args 類別時,SafeArgs Java 產生器應該不會再導致 Lint 警告。(I1a666、b/185843837)
外部貢獻
- 感謝 ospixd 的協助,確認深層連結會驗證
Uri
中是否包含所有必要引數 (不含預設值的引數)。(#204、b/185527157)
2.4.0-alpha07 版本
2021 年 8 月 18 日
發布 androidx.navigation:navigation-*:2.4.0-alpha07
。查看 2.4.0-alpha07 版的修訂項。
修正錯誤
- 在設定變更後,以及使用多個返回堆疊功能變更圖形時,Navigation Compose 現在可正確儲存狀態。(If5a3d、b/195141957)
- 將 Navigation Compose 與多個返回堆疊搭配使用時,重新選取同一個分頁不會再顯示空白螢幕。(I860dc、b/194925622)。
NavHost
現在會觀察NavBackStackEntry
的Lifecycle.State
中的任何異動;也就是說,NavHost
在片段中使用時會隨著生命週期變更正確重組,而不會顯示空白螢幕。(I4eb85、b/195864489)- 修正問題:在重新建立活動之後 (例如在設定變更後),關閉
DialogFragment
時不會正確更新NavController
狀態。(Icd72b) - 修正問題:彈出對話方塊目的地時不會更新 NavController 的系統返回按鈕處理作業,可能導致 NavController 攔截返回按鈕,即使沒有任何可彈出的返回堆疊。(If3b34)
- Safe-args 現在會為引數自動產生
toSavedStateHandle
方法,可用於測試ViewModel
程式碼。(If1e2d、b/193353880)
2.4.0-alpha06 版本
2021 年 8 月 4 日
發布 androidx.navigation:navigation-*:2.4.0-alpha06
。查看 2.4.0-alpha06 版的修訂項。
API 變更
AbstractListDetailFragment
中的requireSlidingPaneLayout()
和requireDetailPaneNavHostFragment()
方法已分別重新命名為getSlidingPaneLayout()
和getDetailPaneNavHostFragment()
。(I34a08)
行為變更
- 透過動畫 (例如
Crossfade
) 導覽時,新目的地的Lifecycle
現在只會在動畫結束時達到RESUMED
。(If0543、b/172112072、b/194301889) - Navigation Compose 的
NavHost
現在會將圖形設為第一個組合的一部分 (Ieb7be)
修正錯誤
- 彈出導覽圖的最後一個目的地時,不會再擲回
ClassCastException
。(If0543、b/172112072、b/194301889) - 修正問題:新增不含
Uri
的深層連結,以及透過路徑或深層連結導覽時,會發生NullPointerException
。(938a0c、b/193805425)。 - 修正 Navigation Compose 中的問題:加上深層連結的
NavBackStackEntry
無法達到RESUMED
狀態 (I192c5) - 修正問題:彈出對話方塊目的地時不會更新 NavController 的系統返回按鈕處理作業,可能導致 NavController 攔截返回按鈕,即使沒有任何可彈出的返回堆疊。(aosp/1782668)
2.4.0-alpha05 版本
2021 年 7 月 21 日
發布 androidx.navigation:navigation-*:2.4.0-alpha05
。查看 2.4.0-alpha05 版的修訂項。
行為變更
- 在目的地之間導覽時,Navigation Compose 的
NavHost
現在會一律使用交叉漸變效果。(I07049、b/172112072) - 您現在可以變更 NavHost 圖形。系統會將具有相同 startDestination 的圖形以及圖形中的目的地視為相等,且不會清除
NavController
返回堆疊。(I0b8db、b/175392262)
修正錯誤
- 從附加至
NavBackStackEntry
的LifecycleObserver
內呼叫popBackStack()
時,因對 NavController 的狀態進行重入更新而導致出現NoSuchElementException
,這個錯誤已獲得修正。(I64621) - 在
AbstractListDetailFragment
未使用的情況下,AbstractListDetailFragment
現在允許從 APK 中完全刪除SlidingPaneLayout
。(I611ad) NavGraph
和NavDestination
現在會覆寫 equals 方法,因此兩個含有相同值的物件會視為相等。(I166eb、b/175392262)
2.4.0-alpha04 版本
2021 年 7 月 1 日
發布 androidx.navigation:navigation-*:2.4.0-alpha04
。2.4.0-alpha04 版包含此連結所列的修訂項目。
新功能
navigation-fragment
構件現可透過新的AbstractListDetailFragment
,納入預先建構的雙窗格版面配置實作項目。此片段使用SlidingPaneLayout
來管理清單窗格 (也就是子類別提供的清單) 及詳細資料窗格,其使用NavHostFragment
做為實作,如 實作範例 中所述。(Iac4be、b/191276636)navigation-compose
構件的NavHost
除了支援composable
目的地外,現在也支援dialog
目的地。這些對話方塊目的地都會顯示在各自對應的Dialog
可組合元件內,並懸浮在目前composable
目的地上方。(I011d0)
val navController = rememberNavController()
Scaffold { innerPadding ->
NavHost(navController, "home", Modifier.padding(innerPadding)) {
composable("home") {
// This content fills the area provided to the NavHost
HomeScreen()
}
dialog("detail_dialog") {
// This content will be automatically added to a Dialog() composable
// and appear above the HomeScreen or other composable destinations
DetailDialogContent()
}
}
}
API 變更
NavigatorState
中的add
函式已重新命名為push
。目前對add()
的所有呼叫都必須變更為 push()。(Ie89fc、b/172112072)- 自訂
Navigator
執行個體現在可透過NavigatorState
上的pushWithTransaction
和popWithTransition
API,以非同步的方式推送或彈出目的地。請注意,任何隨附的導覽器都還未使用這個 API。(Ic4d7c、b/172112072)
行為變更
NavDeepLinkBuilder
現在會將PendingIntent.FLAG_IMMUTABLE
新增至createPendingIntent()
傳回的PendingIntent
中,確保這個 API 在以 Android 12 為目標的環境中能正常運作。(If8c52)
修正錯誤
- 修正問題:使用
<include-dynamic>
時,傳遞至圖形的引數無法正確傳遞至動態納入的圖形。(I3e115) - 修正透過含有
@null
預設值的string[]
引數導覽至目的地時會出現的NullPointerException
問題。(I1fbe8) - 新增
@Navigator.Name
的 ProGuard 規則,並修正使用 R8 3.1 完整模式時會出現的問題。(I2add9、b/191654433) - 使用
Kotlin
1.5.0
以下版本建構應用程式時,SafeArgs 將不再發生錯誤。(Icd1ff、b/190739257)
2.4.0-alpha03 版本
2021 年 6 月 16 日
發布了 androidx.navigation:navigation-*:2.4.0-alpha03
。查看 2.4.0-alpha03 版的修訂項。
修正錯誤
- 修正問題:需要呼叫兩次
navigate()
才能導覽至內含的動態圖形。(I7785c、b/188859835) - 修正 Navigation
2.4.0-alpha01
中引發的迴歸問題:在頂層目的地時,setupActionBarWithNavController()
不會正確移除 Up 圖示。(I5d443、b/189868637) - 修正在先前彈出 NavController 根圖形後呼叫
popBackStack()
時會出現的IllegalStateException
問題。(I2a330、b/190265699) - 使用
navigation-common
以及依附於它的所有構件時,現在可正確套用by navArgs()
的 ProGuard 規則 (I68800、b/190082521) - 如果
OnDestinationChangedListener
在第一次收到回呼時呼叫navigate()
,現在可正確收到第二次回呼,其中包含要導覽前往的目的地。(Ie5f9e、b/190228815) - 將 Safe Args 與動態功能模組和 AGP 7.0 以上版本搭配使用時,不會再發生當機。(I69518、b/189966576)。
已知問題
- 由於 Gradle
6.7.0
依附於舊版的 Kotlin,因此在使用時會導致 Safe Args 失敗,並顯示Unable to find method ‘’java.lang.String kotlin.text.CarsKt.titleCase(char, java.util.Locale)’’
錯誤。只要更新至 Gradle 7.0 即可解決。(b/190739257)
2.4.0-alpha02 版本
2021 年 6 月 2 日
發布 androidx.navigation:navigation-*:2.4.0-alpha02
。2.4.0-alpha02 版包含此連結所列的修訂項目。
新功能
- Activity、Fragment 和 Dialog 目的地以及整個 DynamicNavigation Kotlin DSL 現在都支援路徑。(Ib5544、Ia617b、I22f96、b/188914648、b/188901565)
NavigationUI
暫時新增了實驗性 API,可讓您選擇不要儲存狀態。雖然一律儲存狀態才是正確的行為,但系統仍會在儲存狀態時使用不受支援而淘汰的程式庫 (即保留的片段),這麼做能讓應用程式逐漸汰換不受支援的 API。(Idf93c)Navigation 現在提供
findDestination()
和getHierarchy()
API,可用於實作自訂 NavigationUI。findDestination()
是NavGraph
上的擴充功能,可用來在圖形中找到目的地。getHierarchy()
則是NavDestination
上的函式,可用來驗證特定目的地是否位於其他階層結構中。(I2932f、b/188183365)val matchingRoute: Boolean = destination.hierarchy.any { it.route == routeToFind }
更新原本接受
BottomNavigationView
的 NavigationUI 方法,改為接受 Material1.4.0
中引入的NavigationBarView
父類別。這樣即可將這些方法與NavigationRailView
搭配使用。(Ib0b36、b/182938895)當透過 XML 加載
<action>
元素時,動畫屬性可使用透過app:enterAnim="?attr/transitionEnter"
語法從主題中擷取的屬性。(I07bc1、b/178291654)
API 變更
- 淘汰使用 ID 的 Kotlin DSL 建構工具,請改用使用路徑的建構工具 (I85b42、b/188816479) (I9f58f、b/188816479)
修正錯誤
- 使用者按下系統返回按鈕或點選按鈕外的區域來關閉對話方塊時,
DialogFragmentNavigator
現在會使用NavigatorState.pop()
API 來通知NavController
,以確保NavController
狀態一律會與導覽器的狀態保持同步。(I2ead9) 使用
onDestinationChanged
回呼操控OnDestinationChangedListeners
的清單時,Navigation 不會再提供ConcurrentModificationException
。(Ib1707、b/188860458)嘗試在 Kotlin 中產生方向屬性時,Safe Args 不會再發生當機。(Id2416、b/188564435)
現在可正確使用
@IdRes
為 NavDestination 上的 setId 方法加上註解,因此這個方法只接受資源 ID。(I69b80)findNode
的 int 參數現在是resId
,而不是resid
。(I7711d)
依附元件更新
- Safe-Args 現在依附於 Android Gradle 外掛程式 4.2.0。如此一來,您不會再收到使用
applicationIdTextResource
的警告。(I6d67b、b/172824579)。
2.4.0-alpha01 版本
2021 年 5 月 18 日
發布 androidx.navigation:navigation-*:2.4.0-alpha01
。2.4.0-alpha01 版包含此連結所列的修訂項目。
新功能
NavController
上的currentBackStackEntryAsFlow()
方法提供Flow
,會在每次目前的NavBackStackEntry
變化時發出。您可以將這個流程做為手動管理OnDestinationChangedListener
的替代選項。(I19c4a、#89、b/163947280)
多個返回堆疊
NavController 負責管理目的地的返回堆疊,當您 navigate()
至其堆疊位置時會在返回堆疊中新增目的地,並且在您呼叫 popBackStack()
或觸發系統返回按鈕時移除這些目的地。我們擴展了導覽圖 XML 中現有 NavOptions
類別以及與 <action>
項目的整合功能,以支援儲存及還原返回堆疊的功能。(b/80029773)
做為本次異動的一部分,onNavDestinationSelected()
、BottomNavigationView.setupWithNavController()
和 NavigationView.setupWithNavController()
的 NavigationUI
方法現在會自動儲存並還原彈出目的地的狀態,因此無需變更任何程式碼即可支援多個返回堆疊。將 Navigation 與 Fragment 搭配使用時,建議採用這個方法與多個返回堆疊整合。(Ie07ca)
用於儲存及還原狀態的基礎 API 會透過多個介面公開:
在 Navigation XML 中,
<action>
元素現可使用app:popUpToSaveState
和app:restoreState
的布林值屬性,儲存透過app:popUpTo
彈出的任何目的地狀態,並還原做為app:destination
傳遞的目的地相關聯狀態:<action android:id=”@+id/swap_stack” app:destination=”@id/second_stack” app:restoreState=”true” app:popUpTo=”@id/first_stack_start_destination” app:popUpToSaveState=”true” />
在
navOptions
Kotlin DSL 中,您可以在popUpTo
建構工具中加入restoreState
布林值屬性和saveState
布林值屬性:// Use the navigate() method that takes a navOptions DSL Builder navController.navigate(selectedBottomNavRoute) { launchSingleTop = true restoreState = true popUpTo(navController.graph.startDestinationId) { saveState = true } }
透過
NavOptions.Builder
手動構建NavOptions
物件時,可對接受額外saveState
參數的setPopUpTo()
使用setRestoreState()
和新的過載。NavOptions navOptions = new NavOptions.Builder() .setLaunchSingleTop(true) .setRestoreState(true) .setPopUpTo(navController.getGraph().getStartDestinationId(), false, // inclusive true) // saveState .build(); navController.navigate(selectedBottomNavId, null, navOptions);
對
popBackStack()
發出的程式輔助呼叫現可包含額外的saveState
參數。
在所有情況下,NavController
會儲存及還原每個 NavBackStackEntry
的狀態,包括限定於任何導覽目的地的 ViewModel
執行個體。Navigator
API 已經過更新,可讓每個 Navigator
支援儲存及還原本身的狀態。
我們更新了 Navigation Compose 中 composable
目的地所用的 ComposeNavigator
,以及包含 Fragment 的 Navigation 中 <fragment>
目的地所用的 FragmentNavigator
和 DynamicFragmentNavigator
,以便使用新的 Navigator API,並支援儲存及還原狀態的功能。
導覽路徑
「路徑」為識別目的地的唯一 String
。雖然這個概念先前只在 Navigation Compose 中使用,但現在已成為核心 Navigation API 的一部分。透過 Navigation Kotlin DSL 建構圖形時,這可以做為使用整數 ID 的替代方法。(b/172823546)
以往只接受 ID 的所有 API 現在都具有接受路徑 String
的超載,包含 navigate()
、popBackStack()
、popUpTo()
和 getBackStackEntry()
。
這對 API 產生了一些影響:
- Kotlin DSL 上的
popUpTo
kotlin 屬性已淘汰,請改用popUpToId
。(I59c73、b/172823546) getStartDestination()
API 已淘汰,改以getStartDestinationId()
取代。(I0887f、b/172823546)
如果開發人員已經從舊版 Navigation Compose 升級至 Navigation Compose 2.4.0-alpha01
版本,便不再需要對擴充方法匯入以下項目,應將其移除:
import androidx.navigation.compose.navigation
import androidx.navigation.compose.createGraph
import androidx.navigation.compose.getBackStackEntry
import androidx.navigation.compose.navigate
import androidx.navigation.compose.popUpTo
KEY_ROUTE
引數已替換為 NavDestination
上的 route
屬性,可讓您直接呼叫 navBackStackEntry.destination.route
。
API 變更
- 所有 Navigation 構件都已使用 Kotlin 重新編寫,對於採用一般項目的類別 (例如
NavType
子類別) 改善了其「是否可為空值」的屬性。過去屬於-ktx
構件的所有 Kotlin 擴充功能都已移至各自的主要構件中。-ktx
構件會繼續發布,但不會有任何內容。(b/184292145) NavDeepLinkBuilder
現在支援將在產生的返回堆疊中加入多個不同的目的地。(I3ee0d、b/147913689)- 為
DynamicNavHostFragment
新增工廠函式。(Icd515、b/175222619) NavBackStackEntry
的專屬 ID 現已公開,可做為公用 API 的一部分。(Ie033a)NamedNavArgument
的name
和argument
欄位以及解構函式現已公開。(#174、b/181320559)- 推出新的
NavBackStackEntry#provideToCompositionLocals
擴充功能,為相關的組合本機值提供NavBackStackEntry
。(#175、b/187229439)
Safe Args
Safe Args 現在會為每個
NavArgs
類別產生fromSavedStateHandle()
方法。(#122、b/136967621)class HomeViewModel(savedStateHandle: SavedStateHandle) : ViewModel() { // Create a HomeDestinationArgs class with type safe accessors for each argument // defined on your destination private val args = HomeDestinationArgs.fromSavedStateHandle(savedStateHandle) }
更新 Safe Args 以依附於 KotlinPoet
1.8.0
。(#172、b/183990444)
行為變更
- Navigation 現在依附於 Lifecycle
2.3.1
,且現在會將更新NavBackStackEntry
Lifecycle
的setGraph()
、popBackStack()
、navigateUp()
和navigate()
方法標示為@MainThread
,讓 Navigation 與 Lifecycle2.3.0
中引入的主要執行緒強制執行功能保持一致。(b/171125856) - 現在剖析深層連結中的 Enum 引數時不會區分大小寫,可讓
http://www.example.com/red
這類深層連結成功比對www.example.com/{color}
深層連結,即使 Enum 的值為RED
也沒問題。(#152、b/135857840)
Compose 相容性
androidx.navigation:navigation-compose:2.4.0-alpha01
只與 Compose1.0.0-beta07
以上版本相容,
修正錯誤
- 修正問題:結尾的預留位置優先於含有完全比對後置字串的深層連結。(#153、b/184072811)
NavHostFragment
現在支援使用相同@Navigator.Name("dialog")
做為預設DialogFragmentNavigator
的自訂導覽器。(Ib1c2c、b/175979140)- 改善
NavigatorProvider#addNavigator
的行為,確保透過同一執行個體重複呼叫時不會造成問題。(#176、b/187443146)
外部貢獻
- 感謝 simonschiller 的協助,提供建構 Safe Args 的支援,為每個
NavArgs
類別產生fromSavedStateHandle()
方法。(#122、b/136967621) - 感謝 Bradleycorn 的協助,讓系統剖析深層連結的 Enum 引數時不區分大小寫。(#152、b/135857840)
- 藉助 osipxd 修正問題,即後端引數預留位置優先於含有完全相符後置字串的深層連結。(#153、b/184072811)
- 感謝 tatocaster 協助更新 Safe Args,讓 Safe Args 依附於 KotlinPoet
1.8.0
。(#172、b/183990444) - 感謝 jossiwolf 的協助,公開
NamedNavArgument
的name
和argument
欄位以及銷毀函式。(#174、b/181320559) - 感謝 jossiwolf 的協助,推出新的
NavBackStackEntry#provideToCompositionLocals
擴充功能,為相關組合本機值提供NavBackStackEntry
。(#175、b/187229439) - 感謝 jossiwolf 的協助,改善
NavigatorProvider#addNavigator
的行為,確保透過同一執行個體重複呼叫時不會造成問題。(#176、b/187443146)
Navigation Compose 1.0.0 版本
1.0.0-alpha10 版本
2021 年 4 月 7 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha10
。1.0.0-alpha10 版包含此連結所列的修訂項目。
API 變更
NavHost
現在接受Modifier
,可向下傳遞至會納入目的地可組合項的可組合項容器。(I85aca、b/175125483)
修正錯誤
- 即使沒有找到
OnBackPressedDispatcherOwner
(例如預覽NavHost
時),NavHost
現在也可正常運作 (I7d8b4) - Navigation Compose 現在依附於 Navigation
2.3.5
,並修正在NavHost
目的地中使用BackHandler
時出現的問題。(I7e63b、b/182284739)
1.0.0-alpha09 版本
2021 年 3 月 10 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha09
。1.0.0-alpha09 版包含此連結所列的修訂項目。
API 變更
LocalViewModelStoreOwner.current
現在會傳回可為空值的ViewModelStoreOwner
,以便更準確地判斷目前組合中是否有可用的ViewModelStoreOwner
。如果 API 須使用ViewModelStoreOwner
(例如viewModel()
和NavHost
),在未設定ViewModelStoreOwner
時仍會擲回例外狀況。(Idf39a)
修正錯誤
- Navigation Compose 現在依附於 Navigation 2.3.4,其中修正了在設定圖形之後嘗試設定相同 ViewModelStore 物件的問題。(I65c24、b/177825470)
1.0.0-alpha08 版本
2021 年 2 月 24 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha08
。查看 1.0.0-alpha08 版的修訂項。
新功能
NavHost
現在會在LocalSavedStateRegistryOwner
CompositionLocal 中填入該目的地的NavBackStackEntry
,確保直接儲存在SavedStateRegistry
中的任何狀態都會隨著目的地儲存及還原。(I435d7、b/179469431)
1.0.0-alpha07 版本
2021 年 2 月 10 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha07
。查看 1.0.0-alpha07 版的修訂項。
依附元件更新
- Navigation Compose 現在依附於 Lifecycle ViewModel Compose 1.0.0-alpha01,可為
composable
目的地提供viewModel()
支援。(I7a374) NavHost
現在會使用 Activity-Compose 1.3.0-alpha01 中全新的LocalOnBackPressedDispatcherOwner
,以取得在NavController
上設定的OnBackPressedDispatcher
。(I65b12)
1.0.0-alpha06 版本
2021 年 1 月 28 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha06
。1.0.0-alpha06 版包含此連結所列的修訂項目。
API 變更
- 在
NavController
上新增getBackStackEntry(route: String)
擴充功能方法,以傳回相關聯的NavBackStackEntry
。(If8931)
1.0.0-alpha05 版本
2021 年 1 月 13 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha05
。查看 1.0.0-alpha05 版的修訂項。
進行相關更新,以依附於 Compose 1.0.0-alpha10。
1.0.0-alpha04 版本
2020 年 12 月 16 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha04
。查看 1.0.0-alpha04 版的修訂項。
- 更新與 Compose
1.0.0-alpha09
的相容性。
1.0.0-alpha03 版本
2020 年 12 月 2 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha03
。查看 1.0.0-alpha03 版的修訂項。
修正錯誤
- 修正問題:在設定變更或者程序結束並重建之後,
popBackStack()
和navigateUp()
無法正常運作。(Icea47、b/173281473) - 導覽至 NavHost 中的巢狀結構圖現在可正常運作。(I0948d、b/173647694)
1.0.0-alpha02 版本
2020 年 11 月 11 日
發布 androidx.navigation:navigation-compose:1.0.0-alpha02
。1.0.0-alpha02 版包含此連結所列的修訂項目。
API 變更
- Navigation Compose 現在支援使用 popUpTo 和 launchSingleTop 作業所需的的 NavOptions。(If96c3、b/171468994)
- 新增可接受路徑而非 ID 的導覽函式,讓您在 Navigation Compose DSL 中建構巢狀結構圖形。(I1661d)
- 在 NavHost 參數清單中,startDestination 現在位於路徑之前。(Ie620e)
- 現在建立圖形時,可使用路徑做為 NavHost 可組合項以外的起始目的地。(Iceb75)
1.0.0-alpha01 版本
2020 年 10 月 28 日
發布 android.navigation:navigation-compose:1.0.0-alpha01
。1.0.0-alpha01 版包含此連結所列的修訂項目。
新功能
navigation-compose
構件可提供 Navigation Component 和 Jetpack Compose 之間的整合功能,並使用 @Composable
函式做為應用程式的目的地。
初始版本提供以下功能:
NavHost
可組合元件,可讓您透過 Kotlin DSL 建構導覽圖。- 在目的地層級限定生命週期、
ViewModel
以及記憶狀態的範圍。 - 自動與系統返回按鈕整合。
- 支援傳遞引數、將深層連結附加至目的地,以及將結果傳回至之前的目的地。
rememberNavController()
和currentBackStackEntryAsState()
中的特定 Compose 輔助工具,可讓您提升狀態,並將NavController
連接至NavHost
外的可組合元件 (例如底部導覽列)。
詳情請參閱 Compose Navigation 指南。
2.3.5 版本
2.3.5 版本
2021 年 4 月 7 日
發布 androidx.navigation:navigation-*:2.3.5
。查看 2.3.5 版的修訂項。
新功能
- 使用
NavDeepLinkRequest
或Uri
導覽時,您現在可在結果目的地中存取Uri
、動作和 MIME 類型,方法是透過KEY_DEEP_LINK_INTENT
取得引數中的意圖,為可用於外部深層連結的函式建立鏡射。(I975c3、b/181521877)
修正錯誤
- 將
OnBackPressedCallbacks
新增至含有NavBackStackEntry
的調度工具,因為在活動生命週期為STOPPED
狀態,再變為STARTED
狀態之後,LifecycleOwner 現在可正確攔截返回動作。(Iff94f、b/182284739) - 深層連結網域剖析功能現在不區分大小寫,可確保
www.example.com
能同時正確比對www.example.com
和www.Example.com
。請注意,查詢參數名稱仍有大小寫之分。(#144、b/153829033) - 修正問題:如果目的地有多個不可為空值的預設引數,而且導覽至該目的地時只覆寫這些引數的子集,可能會發生
NullPointerException
(aosp/1644827)
依附元件更新
- Navigation Safe Args Gradle 外掛程式現在依附於 Kotlin Gradle 外掛程式 1.4.31。(aosp/1661058、b/181156413)
外部貢獻
- 感謝
bentrengrove
提出提取要求,讓深層連結剖析功能不區分大小寫。(#144、b/153829033)
2.3.4 版本
2.3.4 版本
2021 年 3 月 10 日
發布 androidx.navigation:navigation-*:2.3.4
。查看 2.3.4 版的修訂項。
新功能
- 系統現在可正確剖析做為深層連結 URI 的一部分傳送的
ReferenceType
引數。這同時支援原始整數值和以0x
為開頭的十六進位值。(#127、b/179166693) - 包含
app:argType="float"
的引數的android:defaultValue
現在支援整數預設值,可讓您使用android:defaultValue="0"
,而無需使用0.0
。(#117、b/173766247)
修正錯誤
- 修正使用 Navigation 支援的動態功能時安裝進度停滯的問題。(Ib27a7、b/169636207)。
- 使用已完成設定的同一物件呼叫
setViewModelStore
或setLifecycleOwner
,現在不需要人工管理 (Idf491、b/177825470)。 - 使用 Java 時,Safe-Args 會在適當的方法中加上抑制註解。(I8fbc5、b/179463137)
外部貢獻
- 感謝
JvmName
提出提取要求,確保當ReferenceType
引數做為深層連結 URI 的一部分傳送時,系統可正確剖析引數。(#127、b/179166693) - 感謝
tatocaster
提出提取要求,讓內含app:argType=”float”
的引數defaultValue
現在能夠支援整數預設值。(#117、b/173766247)
2.3.3 版本
2.3.3 版本
2021 年 1 月 27 日
發布 androidx.navigation:navigation-*:2.3.3
。查看 2.3.3 版的修訂項。
修正錯誤
- 彈出
NavBackStackEntry
再將其Lifecycle
移至CREATED
狀態時,不會再異常終止 (Ie3ba3) - 修正 b/171364502 引起的迴歸問題,亦即導覽至含有動畫資源值為
0
的活動時會發生ResourceNotFoundException
。(I7aedb、b/176819931)
2.3.2 版本
2.3.2 版本
2020 年 12 月 2 日
發布 androidx.navigation:navigation-*:2.3.2
。查看 2.3.2 版的修訂項。
修正錯誤
- 修正迴歸問題:在
NavigationUI
中搭配onNavDestinationSelected
使用<activity>
目的地時會無法導覽至 Activity。(I22e34、b/171364502) - 修正問題:
navigation-dynamic-features-fragment
會導致系統多次導覽至新安裝的目的地。(aosp/1486056、b/169636207) - 修正問題:使用
launchSingleTop
時,預設引數不會傳送至OnDestinationChangedListener
例項 (I2c5cb) - 修正問題:導覽至巢狀結構圖時,系統不會在返回堆疊上建立新的圖形執行個體。(Ifc831)
- 修正問題:使用含有
popUpTo
的navigate()
在導覽圖中移除最後一個目的地時,系統不會立即從返回堆疊中刪除及移除導覽圖本身。(I910a3) - Navigation SafeArgs 現在採用 KotlinPoet 1.7.2 版本,新增支援 Kotlin 的明確 API 模式。(I918b5)
NavHostFragment.findNavController(Fragment)
原本就會檢查 Fragment 階層和 Fragment 檢視區塊階層,現在還會檢查 DialogFragment 的根層級 DecorView。如此一來,您可以透過FragmentScenario
和Navigation.setViewNavController()
對使用 Navigation 的對話方塊片段進行測試。(I69e0d)
2.3.1 版本
2.3.1 版本
2020 年 10 月 14 日
發布 androidx.navigation:navigation-*:2.3.1
。查看 2.3.1 版的修訂項。
新功能
- Navigation UI 已新增預設的 Animator 資源;建議改用這項資源,而不要使用預設動畫資源。(b/167430145)
- NavOptions 現在會覆寫雜湊碼和 equals 方法。(b/161586466)
- Navigation 現已在「無目的地含有 ID」的 LegalArgumentException 中加入目前目的地,以便改善開發人員偵錯體驗。(b/168311416)
修正錯誤
- 即使產生的引數類別名稱長度超過 100 個半型字元,Safe Args 也不會再納入回傳行。(b/168584987)
依附元件變更
navigation-ui
現在依附於 DrawerLayout 1.1.1,確保在使用LOCK_MODE_LOCKED_CLOSED
或LOCK_MODE_LOCKED_OPEN
的情況下NavigationUI
也能開啟導覽匣。(b/162253907)- Safe Args 現在依附於 KotlinPoet 1.6.0。(aosp/1435911)
- Safe Args 現在依附於 AGP 4.0.1。(aosp/1442337)
2.3.0 版本
2.3.0 版本
2020 年 6 月 24 日
發布 androidx.navigation:navigation-*:2.3.0
。2.3.0 版包含此連結所列的修訂項目。
自 2.2.0 版本以來的重大異動
- 功能模組整合:
navigation-dynamic-features-runtime
和navigation-dynamic-features-fragment
構件可讓您導覽至功能模組中定義的目的地,並視需要自動處理功能模組的安裝作業。詳情請參閱「使用功能模組進行導覽」。 - 導覽測試:
navigation-testing
構件會提供TestNavHostController
來讓您設定目前的目的地,並在導覽作業完成之後驗證返回堆疊。詳情請參閱「測試導覽」。 - 傳回結果:您現在可透過 Navigation 返回堆疊中與每個目的地相關聯的
NavBackStackEntry
存取SavedStateHandle
,這個元件適合儲存少量應與特定返回堆疊項目相關聯的已儲存狀態。詳情請參閱「將結果傳回之前的目的地」。 - 對
Openable
的NavigationUI
支援:在NavigationUI
中使用的所有DrawerLayout
都已替換為更一般的Openable
介面。這個介面已新增至 CustomView1.1.0
中,且由 DrawerLayout1.1.0
中的DrawerLayout
實作。 - 深層連結中的操作和 MIME 類型支援:除了原本可用的
app:uri
之外,深層連結也已支援app:action
和app:mimeType
。NavController
現在支援透過新的NavDeepLinkRequest
類別使用任何欄位組合進行導覽。詳情請參閱「使用 NavDeepLinkRequest 導覽」。
已知問題
- 資訊清單合併工具仍不支援深層連結動作和 MIME 類型。在提供支援之前,從資訊清單中
<nav-graph>
元素產生的任何<intent-filter>
元素,都不會在其<data>
元素或您的自訂<action>
中納入 MIME 類型。您必須在資訊清單中手動新增適當的<intent-filter>
。
2.3.0-rc01 版本
2020 年 6 月 10 日
發布 androidx.navigation:navigation-*:2.3.0-rc01
。2.3.0-rc01 版包含此連結所列的修訂項目。
修正錯誤
- 修正問題:使用
singleTop
將不含引數的目的地例項替換為「包含」引數的其他例項時,會發生NullPointerException
(b/158006669) NavController
擲回的所有destination is unknown
例外狀況現在都會提供額外的偵錯資訊,協助判斷NavController
的狀態 (b/157764916)
2.3.0-beta01 版本
2020 年 5 月 20 日
發布 androidx.navigation:navigation-*:2.3.0-beta01
。查看 2.3.0-beta01 版的修訂項。
修正錯誤
- 修正
NavBackStackEntry
的Lifecycle
在程序死亡後無法正確更新的問題。(b/155218371) - 在程序終止後,現在可將還原的目的地正確傳送給呼叫
setGraph()
前就已註冊的OnDestinationChangedListener
例項 (b/155218371) - 使用
singleTop
時,NavBackStackEntry
現在可正確更新引數,並將更新後的引數傳送至所有OnDestinationChangeListener
執行個體。(b/156545508)
依附元件更新
NavigationUI
構件現在依附於 CustomView1.1.0-rc01
和 DrawerLayout1.1.0-rc01
。(aosp/1309696)
2.3.0-alpha06 版本
2020 年 4 月 29 日
發布 androidx.navigation:navigation-*:2.3.0-alpha06
。(查看 2.3.0-alpha06 版的修訂項。)
新功能
- 除了先前可用的
app:uri
之外,深層連結也已進一步支援app:action
和app:mimeType
。NavController 現在支援透過新的NavDeepLinkRequest
類別使用任何欄位組合進行導覽。(b/136573074、b/135334841)
API 變更
- 大幅擴充 Kotlin DSL 對 Dynamic Navigation 目的地的支援 (b/148969800)
修正錯誤
- 修正問題:使用巢狀結構起始目的地時,系統會忽略深層連結意圖。(b/154532067)
2.3.0-alpha05 版本
2020 年 4 月 15 日
發布 androidx.navigation:navigation-*:2.3.0-alpha05
。查看 2.3.0-alpha05 版的修訂項。
新功能
- 對於使用
<include-dynamic>
的內含動態圖形,您不再需要指定app:graphPackage
,只要在applicationId
結尾依序加上點和moduleName
後置字串,即可使用預設值。如果您需要自訂graphPackage
,系統現在也支援${applicationId}
預留位置。(b/152696768) - Navigation Graph Kotlin DSL 現在公開提供
defaultArguments
Map
,可讓您在 Navigation XML 檔案中設定<action>
元素的預設值,並為這項功能建立鏡射。(b/150345605)
修正錯誤
- 自 Navigation 2.2.2 起:修正在 Activity 含有多個
NavHostFragment
例項時,透過深層連結前往圖形起始目的地時會出現的IllegalStateException
問題 (b/147378752)
依附元件更新
- Navigation 現在依附於 Fragment
1.2.4
。(aosp/1277325) - Dynamic Navigation 現在依附於 Play Core
1.7.2
。(aosp/1282257)
2.3.0-alpha04 版本
2020 年 3 月 18 日
發布 androidx.navigation:navigation-*:2.3.0-alpha04
。2.3.0-alpha04 版包含此連結所列的修訂項目。
新功能
- 在 Navigation Kotlin DSL 中新增對功能模組活動和片段目的地的支援。(b/148969800)
API 變更
DynamicExtras
類別不再使用建構工具模式,現在可直接進行建構。(aosp/1253671)DynamicActivityNavigator
現可在其建構函式中使用Context
(而不是Activity
)。(aosp/1250252)
修正錯誤
NavigationUI
不會再忽略空白標籤 (亦即含有android:label=””
的目的地),且現在會將標題正確設為空字串。(b/148679860)
依附元件更新
- Navigation 動態功能構件現在依附於 Play Core
1.6.5
。(b/149556401)
2.3.0-alpha03 版本
2020 年 3 月 4 日
發布 androidx.navigation:navigation-*:2.3.0-alpha03
。查看 2.3.0-alpha03 版的修訂項。
API 變更
- 現在,
AppBarConfiguration
不再需要使用DrawerLayout
具體類別,改用 CustomView1.1.0-alpha02
中引入的Openable
介面 (自 DrawerLayout1.1.0-alpha04
起由DrawerLayout
進行實作),可讓您將Openable
自訂實作項目與NavigationUI
搭配使用。(b/129030452)
修正錯誤
navigation-common-ktx
ProGuard 規則現在只會正確保留已使用的NavArgs
類別,而非所有的NavArgs
執行個體。(b/150213558)
依附元件變更
- Navigation 已還原對
1.2.0
的依附性,並且現在依附於1.1.0
,以避免當 Navigation 不依附於 Core1.2.0
中的任何新 API 時,強制開發人員改用更高版本的依附元件。
2.3.0-alpha02 版本
2020 年 2 月 19 日
發布 androidx.navigation:navigation-*:2.3.0-alpha02
。2.3.0-alpha02 版包含此連結所列的修訂項目。
新功能
- 您現在可透過
NavBackStackEntry
存取SavedStateHandle
,這個元件適合儲存少量應與特定返回堆疊項目相關聯的已儲存狀態。如需用途範例,請參閱「傳回結果」。(b/79672220)
API 變更
- 新增
getCurrentBackStackEntry()
和getPreviousBackStackEntry()
的簡易方法,以便輕鬆擷取目前和先前目的地的NavBackStackEntry
。(b/79672220)
修正錯誤
- 在自己的工作堆疊中啟動應用程式時,
navigateUp()
現在會將目前目的地的引數和KEY_DEEP_LINK_INTENT
傳遞至之前的目的地。(b/147456890)
依附元件變更
- Navigation 現在依附於 Core
1.2.0
。
2.3.0-alpha01 版本
2020 年 2 月 5 日
發布 androidx.navigation:navigation-*:2.3.0-alpha01
。查看 2.3.0-alpha01 版的修訂項。
新功能
- 新的
navigation-testing
構件會提供TestNavHostController
類別。這個類別可做為測試 Navigation 時使用模擬NavController
的替代方法,以便您設定目前目的地,並在導覽作業完成後驗證返回堆疊。(b/140884273) - 新的
navigation-dynamic-features-fragment
(及其傳遞依附元件navigation-dynamic-features-runtime
) 可讓您從功能模組加入目的地或整個導覽圖 (透過<include-dynamic>
),以便在導覽至這些目的地時可視需求無縫安裝功能模組。詳情請參閱「使用功能模組進行導覽」。(b/132170186)
修正錯誤
- 自 Navigation
2.2.1
起:不含查詢參數的深層連結現在可正確忽略任何查詢參數,而不會將其附加在{argument}
元素結尾,或不與深層連結比對。(b/147447512) - 自 Navigation
2.2.1
起:更新DrawerArrowDrawable
的navigation-ui
ProGuard 規則,確保不需使用android.enableJetifier=true
(b/147610424) - 從 Navigation
2.2.1
起:navigation-common-ktx
模組現在擁有專屬的資訊清單套件名稱,不再和navigation-runtime-ktx
共用相同的資訊清單套件名稱。(aosp/1141947)
依附元件更新
- 自 Navigation
2.2.1
起:Navigation2.2.1
現在依附於 Lifecycle ViewModel SavedState2.2.0
和 Fragment1.2.1
。
2.2.2 版本
2.2.2 版本
2020 年 4 月 15 日
發布 androidx.navigation:navigation-*:2.2.2
。查看 2.2.2 版的修訂項。
修正錯誤
- 修正問題:在 Activity 含有多個
NavHostFragment
例項時,透過深層連結前往圖形起始目的地時會出現IllegalStateException
(b/147378752) NavigationUI
不會再忽略空白標籤 (亦即含有android:label=””
的目的地),且現在會將標題正確設為空字串。這項功能先前已在 Navigation 2.3.0-alpha04 中發布。(b/148679860)navigation-common-ktx
ProGuard 規則現在只會正確保留已使用的NavArgs
類別,而非所有的NavArgs
例項。這項功能先前已在 Navigation 2.3.0-alpha03 中發布。(b/150213558)
依附元件更新
- Navigation 現在依附於 Fragment
1.2.4
。(aosp/1277325)
2.2.1 版本
2.2.1 版本
2020 年 2 月 5 日
發布 androidx.navigation:navigation-*:2.2.1
。2.2.1 版包含此連結所列的修訂項目。
修正錯誤
- 不含查詢參數的深層連結現在可正確忽略任何查詢參數,而不會將其附加在
{argument}
元素結尾,或不與深層連結比對。(b/147447512) - 已更新
DrawerArrowDrawable
的navigation-ui
ProGuard 規則,確保不需要android.enableJetifier=true
。(b/147610424) navigation-common-ktx
模組現在擁有專屬的資訊清單套件名稱,不再與navigation-runtime-ktx
共用相同的資訊清單套件名稱。(aosp/1141947)
依附元件更新
- Navigation
2.2.1
現在依附於 Lifecycle ViewModel SavedState2.2.0
和 Fragment1.2.1
。
2.2.0 版本
2.2.0 版本
2020 年 1 月 22 日
發布了 androidx.navigation:navigation-*:2.2.0
。2.2.0 版包含此連結所列的修訂項目。
2.1.0 版之後的重要異動
- NavBackStackEntry:您現在可以呼叫
NavController.getBackStackEntry()
,傳入返回堆疊上特定目的地或導覽圖的 ID。傳回的NavBackStackEntry
除了提供用來啟動該目的地的引數,還會提供以 Navigation 為基礎的LifecycleOwner
、ViewModelStoreOwner
(與NavController.getViewModelStoreOwner()
傳回的值相同) 以及SavedStateRegistryOwner
。 - 整合 Lifecycle ViewModel SavedState:將
by navGraphViewModels()
或ViewModelProvider
建構函式與由NavController.getBackStackEntry()
或NavController.getViewModelStoreOwner()
傳回的ViewModelStoreOwner
搭配使用時,系統現在會將SavedStateViewModelFactory
做為預設的工廠函式。 - 支援深層連結的查詢參數:包含查詢參數的深層連結現在支援重新排序的查詢參數;比對深層連結時,現在可選用包含預設值或可為空值的引數。
- 改善動畫支援:
NavHostFragment
現在會使用 Fragment 1.2.0 的FragmentContainerView
,修正動畫 Z 排序以及視窗插邊會分派給 Fragment 的問題。
2.2.0-rc04 版本
2019 年 12 月 18 日
發布 androidx.navigation:navigation-*:2.2.0-rc04
。查看 2.2.0-rc04 版的修訂項。
修正錯誤
- 調整
navigation-ui
所使用的預設淡出動畫效果,以符合 Fragment1.2.0-rc04
中經過調整的淡出動畫效果。(b/145769814)
2.2.0-rc03 版本
2019 年 12 月 4 日
發布了 androidx.navigation:navigation-*:2.2.0-rc03
。查看 2.2.0-rc03 版的修訂項。
修正錯誤
- 修正深層連結剖析問題:使用查詢參數和引數做為路徑的最後一部分時,會導致最終路徑引數的多個字元無法剖析。(b/144554689)
- 修正深層連結剖析問題:選用的參數會接收到
"@null"
,而不是null
(b/141613546) - 與
FragmentContainerView
搭配使用時,NavHostFragment
現在可在變更設定後正確還原圖形 (b/143752103)
依附元件變更
- Navigation 現在會視情況依附於 Lifecycle
2.2.0-rc03
、Lifecycle ViewModel SavedState1.0.0-rc03
、Activity1.1.0-rc03
以及 Fragment1.2.0-rc03
。
2.2.0-rc02 版本
2019 年 11 月 7 日
發布了 androidx.navigation:navigation-*:2.2.0-rc02
。2.2.0-rc02 版包含此連結所列的修訂項目。
依附元件變更
- Navigation 現在依附於 androidx.lifecycle
2.2.0-rc02
。
2.2.0-rc01 版本
2019 年 10 月 23 日
發布 androidx.navigation:navigation-*:2.2.0-rc01
,且自 2.2.0-beta01
版以來皆無異動。查看 2.2.0-rc01 版的修訂項。
2.2.0-beta01 版本
2019 年 10 月 9 日
發布了 androidx.navigation:navigation-*:2.2.0-beta01
。2.2.0-beta01 版包含此連結所列的修訂項目。
新功能
NavDestination
及其子類別現在會覆寫toString()
,以便在偵錯時提供更多實用資訊。(b/141264986)
行為變更
- 比對深層連結時,系統現在會忽略額外的查詢參數,而不會導致比對失敗。(b/141482822)
修正錯誤
- 修正問題:如果同時指定了查詢參數,系統會忽略深層連結路徑中的引數。(b/141505755)
- 即時沒有額外項目,
Activity
上的navArgs()
Kotlin 擴充功能現在也會提供更明確的錯誤訊息 (b/141408999) - Safe Args 產生的
Directions
Java 類別現在包含預設值。(b/141099045) - Safe Args 產生的
Args
Java 類別現在包含預設值。(b/140123727) - 使用
Toolbar
時,如果在兩個頂層目的地之間移動,NavigationUI
不會再顯示文字變更的動畫效果。(b/140848160)
2.2.0-alpha03 版本
2019 年 9 月 18 日
發布 androidx.navigation:navigation-*:2.2.0-alpha03
。查看 2.2.0-alpha03 版的修訂項。
行為變更
- 在呼叫
setGraph
之後,呼叫setViewModelStore()
會導致IllegalStateException
。這個項目應一律在初始設定中透過NavHost
設定,以確保所有NavBackStackEntry
執行個體都具有一致的儲存空間供ViewModel
執行個體使用。(aosp/1111821)
修正錯誤
- 修正問題:使用
ViewModel
例項時,如果該例項已附加到多個不同導覽圖限定範圍內的ViewModelStore
例項,會導致ConcurrentModificationException
(aosp/1112257)
2.2.0-alpha02 版本
2019 年 9 月 5 日
發布了 androidx.navigation:navigation-*:2.2.0-alpha02
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- 包含查詢參數的深層連結現在支援重新排序的查詢參數;比對深層連結時,現在可選用包含預設值或可為空值的引數。(b/133273839)
- 您現在可以呼叫
NavController.getBackStackEntry()
,傳入返回堆疊上的目的地或導覽圖的 ID。傳回的NavBackStackEntry
除了提供用來啟動該目的地的引數,還會提供以 Navigation 為基礎的LifecycleOwner
、ViewModelStoreOwner
(與NavController.getViewModelStoreOwner()
傳回的值相同) 以及SavedStateRegistryOwner
。(aosp/1101691\aosp/1101710)
修正錯誤
- 修正問題:將
NavHostFragment
新增至ViewPager2
時會發生失敗並出現IllegalArgumentException
。(b/133640271) NavInflater
現可避免不必要的getResourceName()
呼叫,讓加載時間最多加快 40%。(b/139213740)
2.2.0-alpha01 版本
2019 年 8 月 7 日
發布 androidx.navigation:navigation-*:2.2.0-alpha01
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- 將
by navGraphViewModels()
或ViewModelProvider
建構函式與由NavController.getViewModelStoreOwner()
傳回的ViewModelStoreOwner
搭配使用時,現在的預設工廠函式為SavedStateViewModelFactory
(b/135716331)
API 變更
- 自 Navigation
2.1.0-rc01
起:針對2.1.0-alpha02
中引入的NavController
,移除其中已淘汰的getViewModelStore()
API。(aosp/1091021)
修正錯誤
NavHostFragment
現在使用FragmentContainerView
,修正了動畫 Z 排序問題以及視窗插邊會派給 Fragment 的問題。(b/137310379)
2.1.0 版本
2.1.0 版本
2019 年 9 月 5 日
發布了 androidx.navigation:navigation-*:2.1.0
。您可以前往這裡查看這個版本包含的修訂項目。
自 2.0.0 版以來的重要異動
- 將 ViewModel 範圍限定為導覽圖:您現在可透過
by navGraphViewModels()
屬性委派 (適用於使用-ktx
程式庫的 Kotlin 使用者) 或加到NavController
的getViewModelStoreOwner()
API,建立範圍限定在導覽圖層級的 ViewModel。詳情請參閱「在目的地之間共用 UI 相關資料」。 - 對話方塊目的地:您現在可以建立
<dialog>
目的地,系統會在您navigate
至這些目的地時顯示DialogFragment
。NavHostFragment
預設支援對話方塊目的地。詳情請參閱「透過 DialogFragment 建立目的地」。 - 使用 Uri 導覽:現在可以使用
Uri
的navigate
,以使用新增至目的地的<deepLink>
進行導覽。詳情請參閱「使用 URI 進行導覽」。 - NavHostController:專門用於建構自訂
NavHost
的 API 已移至NavHostController
,以便您進行實作,將其NavController
連結至代管的LifecycleOwner
、OnBackPressedDispatcher
和ViewModelStore
。
2.1.0-rc01 版本
2019 年 8 月 7 日
發布 androidx.navigation:navigation-*:2.1.0-rc01
。您可以前往這裡查看這個版本包含的修訂項目。
API 變更
- 已移除
2.1.0-alpha02
中引入的NavController
的已淘汰getViewModelStore()
API。(aosp/1091021)
2.1.0-beta02 版本
2019 年 7 月 19 日
發布 androidx.navigation:*:2.1.0-beta02
。您可以前往這裡查看這個版本包含的修訂項目。
修正錯誤
- 移除
2.1.0-beta01
中意外引入的 jacoco 依附元件。(b/137782950)
2.1.0-beta01 版本
2019 年 7 月 17 日
發布 androidx.navigation:*:2.1.0-beta01
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- 將
setupWithNavController()
與Toolbar
或CollapsingToolbarLayout
搭配使用時,NavigationUI
現在可顯示移除向上按鈕的動畫 (b/131403621)
修正錯誤
- 修正透過
findNavController()
使用包含相同容器的多個 NavHostFragment 時會發生的計時問題 (b/136021571)
2.1.0-alpha06 版本
2019 年 7 月 2 日
發布 androidx.navigation:*:2.1.0-alpha06
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- NavHostFragment 使用的
app:navGraph
屬性現已移至navigation-runtime
構件。可透過 XML 新增的自訂導覽器應使用這個屬性,藉此與導覽編輯器的主機面板整合。(b/133880955)
API 變更
NavController
上的getViewModelStore()
API 已淘汰,並改用會傳回ViewModelStoreOwner
的新getViewModelStoreOwner()
方法。(aosp/987010)- 將浮動視窗目的地 (例如
<dialog>
目的地) 的實作一般化為標記介面FloatingWindow
,因此現在可以實作所有的<dialog>
目的地。用於與頂部應用程式列互動的 NavigationUI 方法現在會忽略FloatingWindow
目的地。(b/133600763)
行為變更
- 使用
<dialog>
目的地時,Navigation 現可正確讓其狀態與螢幕顯示內容保持同步。因此,當導覽至非對話方塊及非活動目的地時,例如<fragment>
目的地,Navigation 會自動彈出<dialog>
目的地。(b/134089818)
修正錯誤
- 如果在處理深層連結時重新建立活動,Navigation 現在會抑制動畫效果,藉此修正影像閃爍問題。(b/130362979)
- 修正錯誤:如果在新增初始片段時彈出 Fragment,Navigation 返回堆疊會無法同步 (b/133832218)
2.1.0-alpha05 版本
2019 年 6 月 5 日
發布 androidx.navigation:*:2.1.0-alpha05
。您可以前往這裡查看這個版本包含的修訂項目。
API 變更
NavController
上的主機相關 API 已重新命名,並移至NavController
的新子類別NavHostController
。(aosp/966091)NavController
setHostOnBackPressedDispatcherOwner()
方法已替換為NavHostController
的setOnBackPressedDispatcher()
方法,現在,您必須先呼叫setLifecycleOwner()
才能呼叫此方法。(aosp/965409)NavHostController
現在包含enableOnBackPressed(boolean)
方法,取代先前由setHostOnBackPressedDispatcherOwner()
傳回的NavHostOnBackPressedManager
類別。(aosp/966091)
修正錯誤
- 修正在透過 URI 導覽後返回堆疊不正確的問題。(b/132509387)
- NavController 自動處理的深層連結現在只會觸發一次。(b/132754763)
2.1.0-alpha04 版本
2019 年 5 月 16 日
發布 androidx.navigation:*:2.1.0-alpha04
。您可以前往這裡查看這個版本包含的修訂項目。
修正錯誤
- 攔截系統返回按鈕事件時,
NavHostFragment
可正確遵守app:defaultNavHost
,進而修正 Navigation2.1.0-alpha03
中的迴歸問題。b/132077777 DialogFragmentNavigator
現在可正確處理popBackStack()
和navigateUp()
作業。b/132576764- 修正在不同巢狀結構圖之間重複導覽時發生的
IllegalStateException: unknown destination during restore
問題。b/131733658
2.1.0-alpha03 版本
2019 年 5 月 7 日
發布了 androidx.navigation:*:2.1.0-alpha03
。您可以前往這裡查看這個版本包含的修訂項目。
已知問題
- 即使使用
app:defaultNavHost="false"
,NavHostFragment 仍會繼續攔截系統返回按鈕。b/132077777
新功能
- 您現在可以建立
<dialog>
目的地,以便系統在您navigate
至這些目的地時顯示DialogFragment
。NavHostFragment
預設支援對話方塊目的地。b/80267254 - 除了使用資源 ID 或
NavDirections
執行個體呼叫navigate
之外,您現在也可使用Uri
進行導覽,透過加到目的地的<deepLink>
導覽至正確的目的地。b/110412864
行為變更
- NavigationUI 提供的預設動畫效果已經從 400 毫秒加快到 220 毫秒,以便與活動和片段的預設動畫速度相符。b/130055522
API 變更
NavHostFragment
的createFragmentNavigator()
方法已淘汰,其功能也已移至新的onCreateNavController()
方法,以便您清楚瞭解這是建立子類別NavHostFragment
時新增自訂導覽器的正確進入點。b/122802849hasDeepLink()
方法已新增至NavDestination
,可讓您檢查處理特定Uri
是否可由該目的地處理;或在有NavGraph
的情況下,是否可由導覽圖的中的任何目的地處理。b/117437718
修正錯誤
- 預設引數現在可正確傳遞至
OnDestinationChangedListener
執行個體。b/130630686 NavHostFragment
現在會透過OnBackPressedDispatcher
攔截系統返回事件,修正了返回 Fragment 時在 Fragment 生命週期方法中進行條件式導覽時會發生的問題。b/111598096- 針對 Safe Args,現在可將未指定
app:argType
的android:defaultValue=”@null”
正確推論為string
引數。b/129629192
2.1.0-alpha02 版本
2019 年 4 月 3 日
發布 androidx.navigation:*:2.1.0-alpha02
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- 您現在可透過適用於 Kotlin 使用者的
by navGraphViewModels()
屬性委派項目或加到NavController
的getViewModelStore()
API,建立範圍限定在導覽圖層級的 ViewModel。b/111614463
API 變更
- 您現在可將
app:targetPackage
新增至<activity>
目的地,以限制比對的套件名稱。支援app:targetPackage="${applicationId}"
,限制套件只能採用您自己的應用程式 ID。b/110975456
修正錯誤
<activity>
目的地的android:name
將不再於加載時剖析為類別,從而在使用動態功能時可防止 ClassNotFoundExceptions。b/124538597
2.1.0-alpha01 版本
2019 年 3 月 19 日
這是 Navigation 2.1.0
的第一個 Alpha 版本。
依附元件變更
- Navigation 現在依附於
androidx.core:core:1.0.1
和androidx.fragment:fragment:1.1.0-alpha05
。這個版本也會移除androidx.legacy:legacy-support-core-utils:1.0.0
上的依附元件。b/128632612
API 變更
- 新增
Navigation.createNavigateOnClickListener(NavDirections)
方法,用於取代使用資源 ID 和 Bundle 建立點擊事件監聽器的做法。b/127631752 FragmentNavigator.instantiateFragment
目前已淘汰。預設實作現在會使用FragmentFactory
對 Fragment 執行個體化。b/119054429
修正錯誤
- 如果目的地已附加引數,Navigation 不會再傳送空值的
Bundle
,修正了使用android:defaultValue="@null"
時會發生的問題。b/128531879 - Safe Args 現在依附於 KotlinPoet 1.1.0,修正了套件名稱過長的問題。b/123654948
2.0.0 版本
2.0.0 版本
2019 年 3 月 14 日
發布 Navigation 2.0.0
,且自 2.0.0-rc02
版本以來沒有異動。
2.0.0-rc02 版本
2019 年 3 月 6 日
Navigation 2.0.0-rc02 提供具有 androidx.navigation
群組 ID 的新構件,並將其依附元件變更為 AndroidX 對應項目。
2.0.0-rc02 的行為與 Navigation 1.0.0-rc02 的行為相同,除了更新依附元件來比對新的依附元件外,從 1.0.0-rc02 更新時也不需要對程式碼進行任何變更。
您的專案必須遷移至 AndroidX,才能使用 Navigation 的 2.X 版本。Navigation 1.0 穩定版是採用支援資料庫依附元件的最後一個版本;1.0 之後的所有開發作業都將以 AndroidX 為基礎,並以 2.0 穩定版為基礎進行建構。
Pre-AndroidX 依附元件
使用 AndroidX 之前的 Navigation 版本時,請納入以下依附元件:
dependencies {
def nav_version = "1.0.0"
implementation "android.arch.navigation:navigation-fragment:$nav_version" // For Kotlin use navigation-fragment-ktx
implementation "android.arch.navigation:navigation-ui:$nav_version" // For Kotlin use navigation-ui-ktx
}
針對 Safe Args,請在「頂層」build.gradle
檔案中新增以下「類別路徑」:
buildscript {
repositories {
google()
}
dependencies {
classpath "android.arch.navigation:navigation-safe-args-gradle-plugin:1.0.0"
}
}
1.0.0 版本
1.0.0 版本
2019 年 3 月 14 日
發布 Navigation 1.0.0
,且自 1.0.0-rc02
版本以來沒有異動。
1.0.0-rc02 版本
2019 年 2 月 26 日
這是 Navigation 1.0.0 穩定版的第二個候選版本。這個版本包含一些錯誤修正。
修正錯誤
- 修正系統在根圖形沒有 ID 的情況下忽略
popBackStack()
的問題。b/126251695 - 在處理不含
FLAG_ACTIVITY_NEW_TASK
的深層連結後呼叫navigateUp()
時,可正確處理導覽至應用程式工作的所需操作。b/126082008 - 修正
ActivityNavigator.applyPopAnimationsToPendingTransition
無法套用正確的彈出式退出動畫的問題。b/126237567 - Safe Args 產生的 Kotlin 程式碼現在會在與
R
類別相關聯的套件名稱中,正確逸出 Kotlin 關鍵字 (例如in
和fun
)。b/126020455
1.0.0-rc01 版本
2019 年 2 月 21 日
這是 Navigation 1.0.0 穩定版的候選版本。這個版本包含一個錯誤修正。
修正錯誤
- 修正使用 Fragment 和
singleTop
導覽作業時發生的問題。b/124294805
1.0.0-beta02 版本
2019 年 2 月 12 日
這個版本包含幾項細微改善以及重大錯誤修正。
新功能
- 您現在可使用
0
做為reference
引數的android:defaultValue
。b/124248602
行為變更
- 深層連結的完全相符項目現在優先於含有
.*
或相符引數的深層連結。b/123969518
修正錯誤
- 彈出返回堆疊上的最後一個目的地時,
popBackStack()
和navigateUp
現在可正確傳回false
,修正了1.0.0-beta01
中引入的迴歸問題。b/123933201 - 在還原已儲存的執行個體狀態期間,Navigation 現在可正確設定
ClassLoader
,避免在Navigator
儲存的狀態或傳送至NavDestination
的引數中使用自訂類別時發生問題。b/123893858 - 從已儲存的執行個體狀態還原
Parcelable[]
引數時,Safe Args 產生的 NavArgs 類別不會再發生當機。b/123963545 - Safe Args 現在可正確清除由系統產生且不必要的 Kotlin 類別。b/124120883
1.0.0-beta01 版
2019 年 2 月 4 日
這是 Navigation 的第一個 Beta 版;之後,除非出現重大問題,否則 Navigation API 將保持穩定,直到推出下一個版本。這個版本包含一些錯誤修正及行為變更。
行為變更
- Navigation 現在可確保引數預設值在執行階段中及透過 Safe Args 使用時,都以相同的方式處理。因此,只有包含
app:argType="reference"
的引數可以擁有指向其他資源 (例如@color/colorPrimary
) 的預設值。剖析導覽 XML 時,如果嘗試使用不同app:argType
的參照預設值,會導致例外狀況發生。b/123551990 - Safe Args 現在依附於 Android Gradle 外掛程式 3.3.0。aosp/888413
- Safe Args 現在依附於 Kotlin 1.3.20。aosp/888414
修正錯誤
- 現在,在 Android Gradle 外掛程式所有版本的程式庫和功能模組中,都能使用 Safe Args。b/121304903
- 修正迴歸問題:這個問題會導致單一
popBackStack()
作業從返回堆疊的頂端彈出目的地的所有複本,而不只是一次彈出一個目的地。b/123552990 - 修正問題:
FragmentNavigator
狀態不會與NavController
的狀態保持同步,且在嘗試還原返回堆疊時導致IllegalStateException
出現。b/123803044 - 修正問題:將 ProGuard 與模糊處理搭配使用時,系統不會顯示
NavigationUI
處理的返回箭頭。b/123449431 - Safe Args 產生的程式碼現在可正確處理使用指向靜態內部類別 (格式為
.OuterClass$InnerClass
) 的app:argType
這類操作。b/123736741 - Safe Args 產生的 Java 程式碼現在可正確處理全域動作以及深層巢狀結構目的地。b/123347762
1.0.0-alpha11 版本
2019 年 1 月 23 日
這是 1.0.0-alpha10
的 Hotfix 版本,修正了 Safe Args 的問題。
修正錯誤
- 修正問題:Safe Args 無法匯入與全域動作相關聯的 Directions 類別。b/123307342
1.0.0-alpha10 版本
2019 年 1 月 23 日
已知問題
- Safe Args 無法匯入與全域動作相關聯的 Directions 類別。b/123307342
這個版本包含破壞性的 API 變更;請參閱下方「破壞性變更」一節。
新功能
- Kotlin 使用者現在可使用
by navArgs()
屬性委派,來延遲取得對Activity
或Fragment
中由 Safe Args 產生的NavArgs
類別的參照。b/122603367 - Safe Args 現在讓您運用
androidx.navigation.safeargs.kotlin
外掛程式來產生 Kotlin 程式碼。Kotlin 程式碼專為 Kotlin 獨有模組打造,使用的是預設引數和不可變類別,而不是仍可透過先前androidx.navigation.safeargs
外掛程式使用的建構工具模式。b/110263087
行為變更
- 相符的深層連結現已調整為含有最相符引數的深層連結。b/118393029
- 對
NavController
呼叫setGraph()
現在會重設返回堆疊。b/111450672 - 未知的深層連結不會再擲回
IllegalStateException
,但會遭到忽略,進而修正巢狀結構或多個NavHostFragment
的問題。b/121340440
破壞性變更
- 對 Activity 套用的彈出動畫的
NavOptions.applyPopAnimationsToPendingTransition()
方法已移至ActivityNavigator
。b/122413117 - Safe Args 現在可避免為不含引數的動作複製相同的類別。在產生的 NavDirections 類別中,不含引數方法的傳回類型現在為
NavDirections
。b/123233147 - Safe Args 產生的 Directions 類別不再提供公開的建構函式,因此您應只與產生的靜態方法互動。b/123031660
- Safe Args 產生的
NavDirections
類別不再有公開建構函式;只能在產生的 Directions 類別中透過靜態方法產生這些類別。b/122963206 NavDirections
的getArguments()
傳回的Bundle
現在會標示為@NonNull
,而非@Nullable
。b/123243957
修正錯誤
NavDeepLinkBuilder
現在會使用您傳入的引數來判斷唯一性,以正確處理多個指向相同目的地的PendingIntent
。b/120042732- 將巢狀結構的
NavHostFragment
或其他子項 Fragment 與返回堆疊搭配使用時,NavController
現在可正確處理popBackStack()
作業。b/122770335 NavigationUI
現在可正確設定向上按鈕的內容說明。b/120395362- Safe Args 產生的 Directions 類別現在可正確處理與目的地的動作具有相同 ID 的全域動作。b/122962504
- 當
equals()
傳回 true 時,Safe Args 產生的NavDirections
類別現在會擁有相等的hashCode()
值。b/123043662 - 如果您嘗試在
NavHostFragment
的FragmentManager
中自訂FragmentTransactions
,FragmentNavigator
現在會擲回更明確的錯誤訊息。建議您一律使用getChildFragmentManager()
。b/112927148
1.0.0-alpha09 版本
2018 年 12 月 18 日
這個版本包含破壞性的 API 變更;請參閱下方「破壞性變更」一節。
我們決定不繼續開發 android.arch.navigation:navigation-testing
構件。雖然經證明這對 NavController
的內部測試有幫助,但我們強烈建議採用其他測試策略 (例如模擬 NavController
執行個體),以驗證目前進行的 navigate()
呼叫正確無誤。2018 年 Android 開發人員高峰會的單次活動講座 詳細討論了這種做法,而我們也會專門針對 Navigation 測試提供更多說明文件。
新功能
- 與
NavigationUI
搭配使用時,含有menuCategory="secondary"
的MenuItem
不會再彈出返回堆疊。b/120104424 AppBarConfiguration
現在可讓您設定備用的OnNavigateUpListener
執行個體,於navController.navigateUp()
傳回false
時進行呼叫。b/79993862 b/120690961
破壞性變更
- 將
<argument>
與argType="reference"
搭配使用時,Navigation 不會再剖析參照,改為提供原始資源 ID 本身。b/111736515 - 根據預設,
onNavDestinationSelected()
現在會彈回導覽圖的起始目的地,與setup
方法維持一致。為MenuItem
新增menuCategory="secondary"
,以免彈出返回堆疊。aosp/852869 - 產生的
Args
類別的fromBundle()
方法現在接受非空值的Bundle
,而非可為空值的Bundle
。aosp/845616
修正錯誤
- 引數現在可從深層連結正確剖析為正確的
argType
,而非一律剖析為字串。b/110273284 - Navigation 現在可正確匯出公開資源。b/121059552
- Safe Args 現在與 Android Gradle 外掛程式 3.4 Canary 4 以上版本相容。b/119662045
1.0.0-alpha08 版本
2018 年 12 月 6 日
這個版本包含破壞性的 API 變更;請參閱下方「破壞性變更」一節。
新功能
- 目的地標籤現在搭配
NavigationUI
方法使用時,將自動使用正確的引數取代android:label
中的{argName}
執行個體 b/80267266 - Navigation 現在依附於支援資料庫 28.0.0。b/120293333
破壞性變更
OnNavigatedListener
已重新命名為OnDestinationChangedListener
。b/118670572OnDestinationChangedListener
現在也會傳遞引數的Bundle
。aosp/837142- 移除了
app:clearTask
和app:launchDocument
屬性及其相關方法。您可以將app:popUpTo
與圖形根層級搭配使用,來移除返回堆疊中的所有目的地。b/119628354 ActivityNavigator.Extras
現在採用Builder
模式,並加入可設定任何Intent.FLAG_ACTIVITY_
標記的功能。aosp/828140NavController.onHandleDeepLink
已重新命名為handleDeepLink
。aosp/836063- 許多不適用於設定子類別的類別和方法 (例如
NavOptions
、NavInflater
、NavDeepLinkBuilder
和AppBarConfiguration
) 皆已設為final
。aosp/835681 - 移除已淘汰的
NavHostFragment.setGraph()
方法。aosp/835684 - 移除已淘汰的
NavigationUI.navigateUp(DrawerLayout, NavController)
方法。aosp/835684 - Fragment 建立程序已移至
FragmentNavigator
,以便將 Fragment 建立程序委派給FragmentFactory
。b/119054429 NavGraphNavigator
的建構函式不再接受Context
。aosp/835340- NavigatorProvider 現已成為類別,不再是介面。
getNavigatorProvider()
傳回的NavigatorProvider
並未改變其功能。aosp/830660 - 已移除
NavDestination.navigate()
。請改為透過Navigator
呼叫navigate()
。aosp/830663 - 大幅重構
Navigator
,不再需要使用OnNavigatorNavigatedListener
,而是改為讓navigate
傳回原本的導覽目的地NavDestination
。 Navigator
執行個體無法再將彈出事件傳送至NavController
。建議您使用OnBackPressedCallback
來攔截返回按鈕點按動作,並呼叫navController.popBackStack()
。aosp/833716
修正錯誤
- 當目的地為
<navigation>
元素時,popUpTo
現在會穩定運作。b/116831650 - 修正因使用巢狀結構圖時發生
IllegalArgumentException
而導致的數個問題。 b/118713731 b/113611083 b/113346925 b/113305559 <activity>
目的地的dataPattern
屬性現在可為引數填入非 String 引數,方法是呼叫toString()
。b/120161365
Safe Args
- Secure Args 支援可序列化物件,包括 Enum 值。Enum 類型可以使用列舉常值來設定預設值,無須使用類別名稱 (例如
app:defaultValue="READ"
)。b/111316353 - 只要是 Safe Args 支援的類型,Safe Args 皆支援其陣列 b/111487504
- Safe Args 現在會忽略資源目錄的子資料夾 b/117893516
- Safe Args 會視情況新增
@Override
註解。b/117145301
1.0.0-alpha07 版本
2018 年 10 月 29 日
新功能
- 全新的 AppBarConfiguration 類別可讓您自訂要列為「頂層」的目的地。詳情請參閱更新版說明文件。b/117333663
- 您現在可以將引數傳遞至圖形的起始目的地。 b/110300470
- 深層連結現在支援含有半形句號、連字號和加號的自訂配置。b/112806402
破壞性變更
navigation-testing-ktx
模組已收入navigation-testing artifact
,因此無法再發布。navigation-testing
構件現在依附於 Kotlin 標準程式庫。API 經變更後更符合 Kotlin 使用慣例,但您可以繼續使用該 API 執行以 Java 編寫的測試。- 不再支援中繼資料資訊清單註冊導覽圖。b/118355937
- 無法再將動作附加至 <activity> 目的地。aosp/785539
修正錯誤
- 深層連結現在可正確地剖析查詢參數。b/110057514
- Activity 目的地現在可正確地套用所有進入與退出的動畫。b/117145284
- 修正了使用自訂 Navigator 時因設定變更而發生的異常終止問題。b/110763345
Safe Args
- Safe Args 現在可以固定依附於 Android Gradle 外掛程式 3.2.1。b/113167627
- 現在可以為內部類別產生 Directions。b/117407555
- 修正無法順利產生 Directions 並加到 <include> 導覽圖的問題。b/116542123
1.0.0-alpha06 版本
2018 年 9 月 20 日
新功能
- 現在支援 Fragment 和 Activity 目的地的共用元素轉換 b/79665225。詳情請參閱「使用導覽架構元件實作導覽功能」。
- 現在如果選取
NavigationView
中的某個項目,其所屬的所有底部功能表都會關閉 b/112158843
API 變更
- 破壞性變更:Navigator
navigate()
方法現在接受Navigator.Extras
參數。 - NavController 的
getGraph()
方法現在為NonNull
。b/112243286
修正錯誤
NavigationUI.setupWithNavController()
與個別目的地的檢視搭配使用時,不會再洩露檢視內容 b/111961977- 系統現在只會呼叫 Navigator
onSaveState()
一次 b/112627079
Safe Args
- 導覽目的地的 Directions 類別現在會擴充其父項 Directions 類別 (如果有的話)。b/79871405
- Directions 和 Args 類別現在具備實用的
toString()
實作。b/111843389
1.0.0-alpha05 版本
2018 年 8 月 10 日
修正錯誤
- 修正導致返回堆疊行為不正確的錯誤。b/111907708
- 修正所產生的 Args 類別在
equals()
中的錯誤。b/111450897 - 修正 Safe Args 中的建構失敗問題。B/109409713
- 修正將資源 ID 轉換成 Java 名稱時發生的問題。b/111602491
- 修正 Safe Args 外掛程式中針對是否可為空值顯示的錯誤訊息。
- 新增原本遺漏的是否可為空值註解。
1.0.0-alpha04 版本
2018 年 7 月 19 日
Navigation 1.0.0-alpha04
和相關聯的 Safe Args Gradle 外掛程式包含多項 API 變更、行為變更和錯誤修正。
API/行為變更
- NavHostFragment 一律會將目前的 Fragment 設為主要導覽片段,以確保先彈出子項片段管理員,再彈出外部的 NavController。b/111345778
Safe Args
- 破壞性變更:
app:type
已變更為app:argType
,以免與 ConstraintLayout 2.0.0-alpha1 等其他程式庫發生衝突。b/111110548 - Safe Args 顯示的錯誤訊息現在可供點選。b/111534438
- Args 類別現在會確認
NonNull
屬性實際並非空值 b/111451769 - 為 NavDirections 和 Args 所產生的類別新增
NonNull
註解。b/111455455 b/111455456
修正錯誤
- 修正透過深層連結前往片段目的地後發生的系統返回按鈕問題。b/111515685
1.0.0-alpha03 版本
2018 年 7 月 12 日
Navigation 1.0.0-alpha03
和相關聯的 Safe Args Gradle 外掛程式包含多項 API 變更、行為變更和錯誤修正。
API/行為變更
- 新增了工具列適用的 NavigationUI.setupWithNavController 方法 b/109868820
- 新增了 CollapsingToolbarLayout 適用的 NavigationUI.setupWithNavController 方法 b/110887183
- 現在,如果返回堆疊為空白或指定目的地 ID 不在返回堆疊中,popBackStack() 會傳回 false。b/110893637
- 現在,FragmentNavigator 在 FragmentManager 儲存狀態後會忽略導覽作業,以避免「無法在 onSaveInstanceState 之後執行這項動作」例外狀況 b/110987825
Safe Args
- 破壞性變更:如果動作和引數名稱包含非英數字元,在各自的 NavDirections 方法名稱中將改用駝峰式大小寫
- 例如:
DemoController.index
會變成setDemoControllerIndex
b/79995048 - 例如:
action_show_settings
會變成actionShowSettings
b/79642240
- 例如:
- 破壞性變更:現在系統預設會將引數視為非空值。想讓字串和可剖析引數使用空值,請新增
app:nullable="true"
b/79642307 - 您現在能夠以「123L」的格式將
app:type="long"
與 defaultValue 搭配使用。b/79563966 - 現在支援可剖析引數,只要在
app:type
使用完整的類別名稱即可。唯一支援的預設值為"@null"
b/79563966 - Args 類別現在會導入
equals()
和hashCode()
b/79642246 - Safe Args 外掛程式現在可套用至程式庫專案。b/80036553
- Safe Args 外掛程式現在可套用至功能專案。b/110011752
修正錯誤
- 修正在 Fragment 生命週期方法執行期間進行導覽時發生的問題。b/109916080
- 修正在透過巢狀結構圖多次進行導覽時發生的問題 b/110178671
- 修正在搭配使用
setPopUpTo
與圖形中第一個目的地時發生的問題。/b/109909461 - 修正所有
app:defaultValue
值都是以 String 形式傳遞的問題。b/110710788 - Android Gradle 外掛程式 3.2 Beta 01 版隨附的 aapt2 現在會為 Navigation XML 檔案中的每個
android:name
屬性新增保留規則。b/79874119 - 修正在取代預設 FragmentNavigator 時發生的記憶體流失問題 b/110900142
1.0.0-alpha02 版本
2018 年 6 月 7 日
行為變更
FragmentNavigator
現在採用setReorderingAllowed(true)
。b/109826220Navigation 現在會對從深層連結網址剖析出的參數進行 URLDecode 處理。b/79982454
修正錯誤
修正了在透過 Fragment 生命週期方法呼叫 navigate 時發生的
IllegalStateException
。b/79632233為修正使用動畫時的閃爍問題,Navigation 現在依附於支援資料庫 27.1.1。b/80160903
修正在使用 defaultNavHost="true" 做為子項片段時發生的
IllegalArgumentException
。b/79656847修正了在使用 NavDeepLinkBuilder 時發生的
StackOverflowError
。b/109653065修正在導覽回巢狀結構圖時發生的
IllegalArgumentException
。b/80453447修正使用
launchSingleTop
時的 Fragment 重疊問題。b/79407969Navigation 現在會為巢狀圖建構正確的合成返回堆疊。b/79734195
現在使用巢狀結構圖做為
MenuItem
時,NavigationUI 會醒目顯示正確的項目。b/109675998
API 變更
淘汰了動作的
clearTask
屬性和NavOptions
中相關聯的 API。b/80338878淘汰了動作的
launchDocument
屬性和NavOptions
中相關聯的 API。b/109806636
1.0.0-alpha01 版本
2018 年 5 月 8 日
Navigation 提供一個架構,可用於建構應用程式內導覽功能。初始版本為 1.0.0-alpha01
。