Fragment

將應用程式區隔成多個獨立的畫面。這些畫面由 Activity 代管。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2022 年 4 月 20 日 1.4.1 - 1.5.0-beta01 -

宣告依附元件

如果要為 Fragment 新增依附元件,您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區

在應用程式或模組的 build.gradle 檔案中,為您需要的構件新增依附元件:

Groovy

dependencies {
    def fragment_version = "1.4.1"

    // Java language implementation
    implementation "androidx.fragment:fragment:$fragment_version"
    // Kotlin
    implementation "androidx.fragment:fragment-ktx:$fragment_version"
    // Testing Fragments in Isolation
    debugImplementation "androidx.fragment:fragment-testing:$fragment_version"
}

Kotlin

dependencies {
    val fragment_version = "1.4.1"

    // Java language implementation
    implementation("androidx.fragment:fragment:$fragment_version")
    // Kotlin
    implementation("androidx.fragment:fragment-ktx:$fragment_version")
    // Testing Fragments in Isolation
    debugImplementation("androidx.fragment:fragment-testing:$fragment_version")
}

如要進一步瞭解依附元件,請參閱新增建構依附元件一文。

意見回饋

您的意見可協助我們改善 Jetpack。發現新的問題或有改善這個程式庫的想法時,請告訴我們。請先查看此程式庫中的現有問題,再建立新的問題。只要按一下星號按鈕,即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件

1.5 版本

1.5.0-beta01 版

2022 年 4 月 20 日

androidx.fragment:fragment:1.5.0-beta01androidx.fragment:fragment-ktx:1.5.0-beta01androidx.fragment:fragment-testing:1.5.0-beta01 發布。1.5.0-beta01 版本包含這些修訂版本。

API 異動

  • DialogFragment 新增了新的 dismissNow 方法,該方法使用 commitNow 來與 showNow 函式進行成對。請注意,這樣做不會立即關閉 Dialog,而只會同步更新 FragmentManager 的狀態。(I15c36, b/72644830)

已儲存的執行個體狀態重構

  • FragmentManager 現在會將已儲存的執行個體狀態儲存到 Bundle,而不是直接儲存至自訂的 Parcelable。這是為片段實際儲存的內容提供更高透明度的第一步。(I93807, b/207158202)
  • 現在透過 Fragment Result API 設定且尚未傳送的結果,會另外單獨儲存於 FragmentManager 內部狀態之外。如此一來,將可為儲存的執行個體狀態提高更多儲存了哪些結果的透明度。(I6ea12, b/207158202)

1.5.0-alpha05 版

2022 年 4 月 6 日

androidx.fragment:fragment:1.5.0-alpha05androidx.fragment:fragment-ktx:1.5.0-alpha05androidx.fragment:fragment-testing:1.5.0-alpha05 發布。1.5.0-alpha05 版本包含這些修訂版本。

API 異動

1.5.0-alpha04 版本

2022 年 3 月 23 日

androidx.fragment:fragment:1.5.0-alpha04androidx.fragment:fragment-ktx:1.5.0-alpha04androidx.fragment:fragment-testing:1.5.0-alpha04 發布。1.5.0-alpha04 版本包含這些修訂版本

API 異動

  • 用於為活動 ActionBar 提供選單的 Fragment API 已淘汰,因為這些 API 將片段與活動緊密結合,無法單獨測試。活動 1.4.0-alpha01 中新增的 MenuHostMenuProvider API 提供了片段應使用的等同 API 介面,該介面可進行測試,且知道生命週期的情形。(I50a59, I20758)

修正錯誤

  • SavedStateViewFactory 現在支援使用 CreationExtras (即使已透過 SavedStateRegistryOwner 初始化)。如果提供額外項目,系統將忽略初始化的引數。(I6c43bb/224844583)

1.5.0-alpha03 版本

2022 年 2 月 23 日

androidx.fragment:fragment:1.5.0-alpha03androidx.fragment:fragment-ktx:1.5.0-alpha03androidx.fragment:fragment-testing:1.5.0-alpha03 發布。1.5.0-alpha03 版本包含這些修訂版本。

API 異動

  • 您現在可以將 CreationExtras 傳送至 by viewModels()by activityViewModels() 函式。(Ibefe7b/217601110)

行為變更

1.5.0-alpha02 版本

2022 年 2 月 9 日

androidx.fragment:fragment:1.5.0-alpha02androidx.fragment:fragment-ktx:1.5.0-alpha02androidx.fragment:fragment-testing:1.5.0-alpha02 發布。1.5.0-alpha02 版本包含這些修訂版本。

新功能

  • FragmentStrictMode 現在提供私人第三方片段的功能,可讓您使用有類別名稱的 allowViolation() 來略過特定違規行為。(I8f678)

1.5.0-alpha01 版本

2022 年 1 月 26 日

androidx.fragment:fragment:1.5.0-alpha01androidx.fragment:fragment-ktx:1.5.0-alpha01androidx.fragment:fragment-testing:1.5.0-alpha01 發布。1.5.0-alpha01 版本包含這些修訂版本。

新功能

修正錯誤

  • Fragment 1.4.1 中:當 xml 產生的檢視 ID 為負值時,FragmentContainerView 不會再擲回非法狀態例外狀況。(Ic185bb/213086140)
  • Fragment 1.4.1 中:搭配 by viewModels() 延遲函式使用自訂時 ownerProducer lambda 時,系統現在會在自訂 ViewModelProvider.Factory 沒有提供,而是改為總是使用片段的中心時,使用來自擁有者的 defaultViewModelProviderFactory。(I56170b/214106513)
  • 修正從 FragmentregisterForActivityResult() 回呼首次存取 ViewModel 時會停止運作的問題。(Iea2b3)

1.4 版本

1.4.1 版本

2022 年 1 月 26 日

androidx.fragment:fragment:1.4.1androidx.fragment:fragment-ktx:1.4.1androidx.fragment:fragment-testing:1.4.1 發布。1.4.1 版本包含這些修訂版本。

修正錯誤

  • 當 xml 產生的檢視畫面 ID 為負值時,FragmentContainerView 不會再擲回非法狀態例外狀況。(Ic185bb/213086140)
  • 搭配 by viewModels() 延遲函式使用自訂 ownerProducer lambda 時,系統現在會在自訂 ViewModelProvider.Factory 沒有提供,而是改為總是使用片段的中心時,使用來自擁有者的 defaultViewModelProviderFactory。(I56170b/214106513)

1.4.0 版本

2021 年 11 月 17 日

androidx.fragment:fragment:1.4.0androidx.fragment:fragment-ktx:1.4.0androidx.fragment:fragment-testing:1.4.0 發布。1.4.0 版本包含這些修訂版本。

自 1.3.0 版以來的重要異動

  • FragmentStrictMode API 提供的執行階段檢查可讓您驗證依賴的應用程式或程式庫不會呼叫已淘汰的片段 API。當系統偵測到違規問題時,您可以選擇列印記錄訊息、觸發自己的自訂事件監聽器,或是導致應用程式停止運作。控制已啟用檢查以及觸發「懲罰」的 FragmentStrictMode.Policy 可以透過新的 setStrictModePolicy() 方法在 FragmentManager 上進行設定。這項政策適用於該 FragmentManager,並會轉移給所有未設定專屬政策的子項片段管理員。請參閱適用於片段的 StrictMode
  • FragmentContainerView 現在提供 getFragment() 方法,此方法會傳回最近新增至容器的片段。這會使用與 FragmentContainerView ID 相同的 findFragmentById() 邏輯,但允許鏈結呼叫。

    val navController = binding.container.getFragment<NavHostFragment>().navController
    
  • FragmentScenario 現已實作 Closeable,允許您搭配 Kotlin 的 use 方法或 try-with-resources 使用。

  • 新增 FragmentTransaction#TRANSIT_FRAGMENT_MATCH_ACTIVITY_{OPEN, CLOSE},以指定是否要啟用在片段轉換效果中擷取自主題的標準「活動轉換」動畫。

  • 已移除 FragmentManager.enableNewStateManager(boolean) 的實驗性 API,現在只能使用新狀態管理員

多個返回堆疊

FragmentManager 會維護使用 addToBackStack() 片段交易組成的返回堆疊。這可以讓您使用「使用片段來儲存狀態」機制來填入這些交易並回復先前的狀態,讓片段適當地還原狀態。

此版本根據這三個新的 FragmentManager API (saveBackStack(String name)restoreBackStack(String name)clearBackStack(String name)) 進一步擴充這些機制。這些 API 使用與 addToBackStack() 相同的 name 來儲存 FragmentTransaction 的狀態,以及您在這些交易中新增的任何片段狀態,方便您稍後還原這些交易及其片段的狀態。這可讓您透過儲存目前的返回堆疊和還原儲存的返回堆疊,以有效率的方式在多個返回堆疊之間「切換」。

saveBackStack() 的運作方式與 popBackStack() 類似,差別在於執行非同步動作時,所有片段交易都會傳回至該特定名稱,以便執行反向撤銷 (亦即「填入」) 以及所有即將捨棄的片段,但有以下幾項差異:

  • saveBackStack() 總是包含在內。
  • popBackStack() 不同的是,如果返回堆疊中找不到指定的名稱,或者如果提供空值名稱,則在返回堆疊中會執行所有交易;若您尚未提供空值,如果您之前並未使用 addToBackStack() 提供確切的非空值名稱來修訂片段交易,saveBackStack() 就不會執行任何動作。
  • 系統會儲存這些交易中所有片段的狀態。這表示系統會儲存所有片段的「檢視」狀態,然後呼叫每個片段的 onSaveInstanceState() 並還原該狀態,且會保留與這些片段相關聯的任何 ViewModel 執行個體 (且 onCleared() 不會根據他們呼叫)。

可與 saveBackStack() 搭配使用的片段交易必須符合下列條件:

  • 所有片段交易都必須使用 setReorderingAllowed(true),確保交易能夠以單一、不可部分完成的作業進行還原。
  • 所儲存的交易組合必須獨立包含 (也就是說,交易不得明確參照該交易組合以外的任何片段),以確保之後不論在一段時間內返回堆疊是否有變更都能還原。
  • 所有儲存的片段都不可為保留的片段,或是在子區段的保留片段中建立保留的片段,以確保 FragmentManager 不會在返回堆疊儲存後傳回任何參考至儲存的片段。

saveBackStack()restoreBackStack()clearBackStack() 類似,如果您之前不曾使用相同的名稱呼叫 saveBackStack(),這項操作會一併還原先前儲存過的返回堆疊,或清除先前儲存的返回堆疊。

詳情請參閱多個反向堆疊:深入探索

1.4.0-rc01 版本

2021 年 11 月 3 日

androidx.fragment:fragment:1.4.0-rc01 發布,Fragment 1.4.0-beta01 沒有任何變更。1.4.0-rc01 版本包含這些修訂版本。

1.4.0-beta01 版本

2021 年 10 月 27 日

androidx.fragment:fragment:1.4.0-beta01androidx.fragment:fragment-ktx:1.4.0-beta01androidx.fragment:fragment-testing:1.4.0-beta01 發布。1.4.0-beta01 版本包含這些修訂版本。

修正錯誤

  • 父項片段現在會分派 onHiddenChanged() 至其整個階層,然後再啟動自己的回呼。(Iedc20b/77504618)
  • 現在如果使用開放鍵盤從一個片段前往另一個有回收器檢視畫面的片段,鍵盤會自動關閉。(I8b842b/196852211)
  • DialogFragment 現在會在您呼叫 show()showNow()dismiss() 時,針對其所有建立的交易使用 setReorderingAllowed(true)。(Ie2c14)
  • DetachAndAttachFragmentInSameFragmentTransaction 的極長 Lint 警告已縮短為 DetachAndAttachSameFragment。(e9eca3)

1.4.0-alpha10 版本

2021 年 9 月 29 日

androidx.fragment:fragment:1.4.0-alpha10androidx.fragment:fragment-ktx:1.4.0-alpha10androidx.fragment:fragment-testing:1.4.0-alpha10 發布。1.4.0-alpha10 版本包含這些修訂版本。

Lint

  • 新增 DetachAndAttachFragmentInSameFragmentTransaction Lint 警告以在相同的 FragmentTransaction 中,於同一個 Fragment 同時呼叫 detach()attach(),因為這些互補運算會在相同交易中完成時互相取消,它們必須拆分為不同交易,才能真正執行。(aosp/1832956b/200867930)
  • 使用 MenuHostaddMenuProvider API 時,針對 Fragment Lifecycle 的修正功能在 Fragment 檢視畫面 Lifecycle 加入 FragmentAddMenuProvider Lint 錯誤。(aosp/1830457b/200326272)

說明文件更新

  • API的淘汰訊息現已由Activity Result API (即startActivityForResultstartIntentSenderForResultonActivityResultrequestPermissionsonRequestPermissionsResult)處理提供更多詳細資料。(cce80f)
  • FragmentDialogFragmentonActivityCreated() 淘汰訊息已全部展開,而且提供更多詳細資料。(224db4)

1.4.0-alpha09 版本

2021 年 9 月 15 日

已釋出 androidx.fragment:fragment:1.4.0-alpha09androidx.fragment:fragment-ktx:1.4.0-alpha09androidx.fragment:fragment-testing:1.4.0-alpha091.4.0-alpha09 版本包含這些修訂版本。

新功能

  • 您現在可以呼叫 clearBackStack(name) 以清除先前使用 saveBackStack(name) 儲存的任何狀態。(I70cd7)

API 異動

  • FragmentContainerView 類別已按照 Kotlin 重新編寫,確保 getFragment 函式正確遵循空值。(If694ab/189629145)
  • FragmentstrictMode 現已以 Kotlin 編寫 (I11767b/199183506)

修正錯誤

  • 修正透過 setReorderingAllowed(true) 新增的片段狀態,並在移除待處理交易前立即移除的片段的問題。(I8ccb8)

1.4.0-alpha08 版本

2021 年 9 月 1 日

androidx.fragment:fragment:1.4.0-alpha08androidx.fragment:fragment-ktx:1.4.0-alpha08androidx.fragment:fragment-testing:1.4.0-alpha08 發布。1.4.0-alpha08 版本包含這些修訂版本。

修正錯誤

  • 改善 UseRequireInsteadOfGet Lint 檢查功能,以更妥善的方式處理冗餘括號。(I2d865)
  • 改善 UseGetLayoutInflater Lint 檢查功能,以處理額外的邊緣案例。(Ie5423)

1.4.0-alpha07 版本

2021 年 8 月 18 日

androidx.fragment:fragment:1.4.0-alpha07androidx.fragment:fragment-ktx:1.4.0-alpha07androidx.fragment:fragment-testing:1.4.0-alpha07 發布,且沒有重大異動。1.4.0-alpha07 版本包含這些修訂版本。

1.4.0-alpha06 版本

2021 年 8 月 4 日

已釋出 androidx.fragment:fragment:1.4.0-alpha06androidx.fragment:fragment-ktx:1.4.0-alpha06androidx.fragment:fragment-testing:1.4.0-alpha061.4.0-alpha06 版本包含這些修訂版本。

修正錯誤

  • 修正在返回堆疊之間快速切換時,如果還原 FragmentTransaction 為顯示片段的第二副本,就會有多個返回堆疊以 IllegalStateException 顯示的問題。(I9039f)
  • 修正即使在還原狀態之後,FragmentManager 仍會保留之前透過 saveBackStack() 儲存狀態副本的問題。(Ied212)
  • 透過 show(FragmentTransaction, String) 方法新增 DialogFragment 後,狀態以儲存後呼叫 DialogFragmentdismissAllowingStateLoss() 方法不再會停止運作。(I84422)

1.4.0-alpha05 版本

2021 年 7 月 21 日

androidx.fragment:fragment:1.4.0-alpha05androidx.fragment:fragment-ktx:1.4.0-alpha05androidx.fragment:fragment-testing:1.4.0-alpha05 發布。1.4.0-alpha05 版本包含這些修訂版本。

修正錯誤

  • Fragment 1.3.6 中:當根層級畫面檢視已設定 transitionGroup=”true” 時,Fragment 的畫面檢視現在會於使用 hide() 時正確地設為 GONE。(aosp/1766655b/193603427)
  • Fragment 1.3.6 中:FragmentActivity 現在一律會解鎖儲存的狀態為生命週期回呼中覆寫的第一個作業。(I6db7a)

依附元件更新

1.4.0-alpha04 版本

2021 年 6 月 30 日

已釋出 androidx.fragment:fragment:1.4.0-alpha04androidx.fragment:fragment-ktx:1.4.0-alpha04androidx.fragment:fragment-testing:1.4.0-alpha041.4.0-alpha04 版本包含這些修訂版本。

API 異動

  • FragmentManager 現在使用 SavedStateRegistry 進接功能以儲存狀態。saveAllState()restoreSavedState() 方法現在已於 FragmentController 中淘汰。如果您使用 FragmentController 代管位於 FragmentActivity 以外的片段,您應使 FragmentHostCallbacks 實作 SavedStateRegistryOwner。(Iba68eb/188734238)

修正錯誤

  • 修正問題:執行使用 replace()FragmentTransaction 時如果同時完成,呼叫 saveBackStack() 做為支援多個返回堆疊的要求會失敗。(I73137)
  • 修正如果針對多個返回堆疊支援使用 restoreBackStack() API,就會在手動儲存包含多個交易的返回堆疊後出現 NullPointerException 的問題。這也修正了系統不會針對所有交易檢查 setReorderingAllowed(true) 的問題。(I8c593)
  • 修正問題:FragmentManager 以錯誤的方式繼續還原之前已儲存的片段狀態,即使那些片段已從 FragmentManager 移除也會如此,因此導致儲存的狀態會隨著時間持續增長。(I1fb8e)

1.4.0-alpha03 版本

2021 年 6 月 16 日

androidx.fragment:fragment:1.4.0-alpha03androidx.fragment:fragment-ktx:1.4.0-alpha03androidx.fragment:fragment-testing:1.4.0-alpha03 發布。1.4.0-alpha03 版本包含這些修訂版本。

新功能

  • 所有 Fragment strictMode Violation 類別已更新,提供更詳細的錯誤訊息,說明違規問題詳情。(b/187871638)
    • FragmentTagUsageViolation 現在包含更詳細的錯誤訊息,說明容器要插入片段的父項容器。(Ic33a7)
    • WrongFragmentContainerViolation 現在有更詳細的錯誤訊息,包括要新增片段的容器。(Ib55f8)
    • TargetFragmentUsageViolation 的用途類別現在包含更詳細的錯誤訊息,說明違規事項和任何其他包含的資訊。(Icc6ac)
    • 擴充 RetainInstanceUsageViolation 的類別現在有更詳細的錯誤訊息,包含導致違規的片段。(I6bd55)
    • FragmentReuseViolation 現在提供更多詳細錯誤訊息,包含片段的前一個 ID。(I28ce2)
    • SetUserVisibleHintViolation 現在會顯示更詳細的錯誤訊息,包含設定的使用者顯示提示。(Ib2d5f)

行為變更

  • 已還原在 FragmentContainerView 上呼叫 fitsSystemWindows 的限制 - 應用程式不再因此當機。(6b8dddb/190622202)

修正錯誤

  • Fragment 1.3.5 中:修正在 Fragment 1.3.4aosp/1679887 造成的共用元素轉換中的迴歸。片段現在可以正確地處理轉換群組 (直接透過 transitionGroup="true" 設定,或透過 transitionNamebackground 間接設定),共用元素將不再傳送 IndexOutOfBoundsException。(I16484b/188679569b/188969304)
  • 嘗試隱藏移除的片段時,FragmentManager 不會再停止運作。(I573ddb/183634730)
  • 評估最高等級變數時,OnCreateDialogIncorrectCallback Lint 檢查將不再停止運作。(0a9efab/189967522)。

1.4.0-alpha02 版本

2021 年 6 月 2 日

已釋出 androidx.fragment:fragment:1.4.0-alpha02androidx.fragment:fragment-ktx:1.4.0-alpha02androidx.fragment:fragment-testing:1.4.0-alpha021.4.0-alpha02 版本包含這些修訂版本。

新功能

  • 現在無論目前使用的嚴格模式政策為何,FragmentStrictMode 都會透過 FragmentManager 進行記錄時一律記錄違規行為。(I02df6b/187872638)。
  • FragmentStrictMode 現支援將特定 Fragment 類別從嚴格模式 Violation 中排除,使該類別略過任何懲處。(Ib4e5db/184786736)

  • 我們已進一步擴充 FragmentStrictMode Violation 類別,以根據每項違規加入結構資訊。這可讓您驗證導致違規的確切原因與違規的片段 (If5118b/187871150),每個 Violation 包含以下內容:

    • WrongFragmentContainerViolation 現在包含 Fragment 嘗試加入的 ViewGroup。(I83c75b/187871150)
    • TargetFragmentUsageViolation 已展開為 SetTargetFragmentUsageViolationGetTargetFragmentUsageViolationGetTargetFragmentRequestCodeUsageViolation,其中 SetTargetFragmentUsageViolation 包含目標片段和要求代碼。(I741b4b/187871150)
    • SetUserVisibleHintViolation 現在包含傳送至 setUserVisibleHint() 的布林值。(I00585b/187871150)
    • FragmentTagUsageViolation 現在包含 <fragment> 標記嘗試將片段灌入的 ViewGroup。(I5dbbcb/187871150)
    • FragmentReuseViolation 現在包含過去導致 Viotion 的 Fragment 執行個體專屬 ID。(I0544db/187871150)
    • RetainInstanceUsageViolation 現在為摘要,且有兩個子類別:SetRetainInstanceUsageViolationGetRetainInstanceUsageViolation,分別代表兩種違規類型的案件。(Ic81e5b/187871150)

行為變更

  • FragmentContainerView 現在在嘗試以程式控制方式或透過 XML 變更 fitsSystemWindow 屬性時,會擲回例外狀況。插邊應由個別片段的檢視畫面處理。(Ie6651b/187304502)

1.4.0-alpha01 版本

2021 年 5 月 18 日

androidx.fragment:fragment:1.4.0-alpha01androidx.fragment:fragment-ktx:1.4.0-alpha01androidx.fragment:fragment-testing:1.4.0-alpha01 發布。1.4.0-alpha01 版本包含這些修訂版本。

新功能

  • FragmentContainerView 現在提供 getFragment() 方法,此方法會傳回最近新增至容器的片段。這會使用 ID 與 FragmentContainerView 相同的 findFragmentById() 邏輯,但允許鏈結呼叫。(Ife17ab/162527857)

    val navController = binding.container.getFragment<NavHostFragment>().navController
    
  • 新增 FragmentTransaction#TRANSIT_FRAGMENT_MATCH_ACTIVITY_{OPEN, CLOSE},以指定是否要啟用在片段轉換效果中擷取自主題的標準「活動轉換」動畫。(I46652)

多個返回堆疊

FragmentManager 會維護使用 addToBackStack() 片段交易組成的返回堆疊。這可以讓您使用「使用片段來儲存狀態」機制來填入這些交易並回復先前的狀態,讓片段適當地還原狀態。

此版本根據這兩個新的 FragmentManager API (saveBackStack(String name)restoreBackStack(String name)) 進一步擴充這些機制。這些 API 使用與 addToBackStack() 相同的 name 來儲存 FragmentTransaction 的狀態,以及您在這些交易中新增的任何片段狀態,方便您稍後還原這些交易及其片段的狀態。這可讓您透過儲存目前的返回堆疊和還原儲存的返回堆疊,以有效率的方式在多個返回堆疊之間「切換」。

saveBackStack() 的運作方式與 popBackStack() 類似,差別在於執行非同步動作時,所有片段交易都會傳回至該特定名稱,以便執行反向撤銷 (亦即「填入」) 以及所有即將捨棄的片段,但有以下幾項差異:

  • saveBackStack() 總是包含在內。
  • popBackStack() 不同的是,如果返回堆疊中找不到指定的名稱,或者如果提供空值名稱,則在返回堆疊中會執行所有交易;若您尚未提供空值,如果您之前並未使用 addToBackStack() 提供確切的非空值名稱來修訂片段交易,saveBackStack() 就不會執行任何動作。
  • 系統會儲存這些交易中所有片段的狀態。這表示系統會儲存所有片段的「檢視」狀態,然後呼叫每個片段的 onSaveInstanceState() 並還原該狀態,且會保留與這些片段相關聯的任何 ViewModel 執行個體 (且 onCleared() 不會根據他們呼叫)。

可與 saveBackStack() 搭配使用的片段交易必須符合下列條件:

  • 所有片段交易都必須使用 setReorderingAllowed(true),確保交易能夠以單一、不可部分完成的作業進行還原。
  • 所儲存的交易組合必須獨立包含 (也就是說,交易不得明確參照該交易組合以外的任何片段),以確保之後不論在一段時間內返回堆疊是否有變更都能還原。
  • 所有儲存的片段都不可為保留的片段,或是在子區段的保留片段中建立保留的片段,以確保 FragmentManager 不會在返回堆疊儲存後傳回任何參考至儲存的片段。

saveBackStack() 類似,如果您之前不曾使用相同的名稱呼叫 saveBackStack()restoreBackStack() 就不會有任何動作。(b/80029773)

Fragment strictMode

FragmentStrictMode API 提供的執行階段檢查可讓您驗證依賴的應用程式或程式庫不會呼叫已淘汰的片段 API。當系統偵測到違規問題時,您可以選擇列印記錄訊息、觸發自己的自訂事件監聽器,或是導致應用程式停止運作。控制已啟用檢查以及觸發「懲罰」的 FragmentStrictMode.Policy 可以透過新的 setStrictModePolicy() 方法在 FragmentManager 上進行設定。這項政策適用於該 FragmentManager,並會轉移給所有未設定專屬政策的子項片段管理員。(#123#131#150b/143774122)

  • 不論先前移除的 Fragment 執行個體是否會重新加入至 FragmentManagerdetectFragmentReuse() 都會偵測。在 Fragment 執行個體已經刪除且從 FragmentManager 移除後,請勿與其互動或保留其參考。(#142b/153738653)
  • detectFragmentTagUsage() 會偵測您是否於版面配置 XML 中使用 <fragment> 標記。加載片段為版面配置的部分時,您應總是使用 FragmentContainerView。(#141b/153738235)
  • detectWrongFragmentContainer() 會偵測您新增至容器的片段是否不是 FragmentContainerView。建議您一律使用 FragmentContainerView 做為版面配置中的片段容器。(#146b/181137036)
  • detectRetainInstanceUsage() 會偵測您是否使用已淘汰的 setRetainInstance()getRetainInstance() API。(#140b/153737954)
  • detectSetUserVisibleHint() 會偵測你是否使用已淘汰的 setUserVisibleHint() API。(#136b/153738974)
  • detectTargetFragmentUsage() 會偵測您是否使用已淘汰的 setTargetFragment()getTargetFragment()getTargetRequestCode() API。(#139b/153737745)

API 異動

新的 Lint 檢查

  • DialogFragment 中使用 LayoutInflater.from(Context) 時,UseGetLayoutInflater Lint 檢查現在會顯示警告 - 請務必使用對話方塊片段的 getLayoutInflater() 方法以取得適合的 LayoutInflater。(#156b/170781346)
  • DialogFragmentCallbacksDetector Lint 檢查現在會於 DialogFragmentonCreateDialog() 方法中呼叫 setOnCancelListenersetOnDismissListener 時發出警告 - 這些事件監聽器為 DialogFragment 擁有,且您應覆寫 onCancel()onDismiss() 以接收這些回呼。(#171b/181780047b/187524311)

修正錯誤

  • Fragment 1.3.4 中:修正搭配 ViewModelProvider 或在 Fragment 中 的 viewModel() Jetpack Compose 方法使用 ViewTreeViewModelStoreOwner.get() 時,會在 Fragment 1.3.3 加入迴歸的問題。這些用途現在會覆寫您片段中的 ViewModelProvider.Factory,因為覆寫 getDefaultViewModelProviderFactory() 時必須使用 @AndroidEntryPoint 註解的片段。如果未覆寫該方法,與 Fragment 檢視畫面一起的儲存和還原狀態的 SavedStateViewModelFactory 就會建立為預設中心。(I5cbfab/186097368)
  • Fragment 1.3.4 中:在 API 29 上使用 FragmentContainerView 時,插邊不會再無限期地分派,修正 BottomNavigationBarFloatingActionButton 執行個體的問題。(I1bb78b/186012452)
  • Fragment 1.3.4 中:現在您可以在處理結束後,從片段結果套裝組合中擷取 Parcelable。(I65932b/187443158)
  • Fragment 1.3.4 中:在 ViewGroup 上執行共用元素轉換時,如果 ViewGroup 的 transitionGroup 設為 False,系統就能正確地轉換。(I99675)

外部貢獻

版本 1.3

1.3.6 版本

2021 年 7 月 21 日

已釋出 androidx.fragment:fragment:1.3.6androidx.fragment:fragment-ktx:1.3.6androidx.fragment:fragment-testing:1.3.61.3.6 版本包含這些修訂版本。

修正錯誤

  • Fragment 1.4.0-alpha03 中:嘗試隱藏移除片段時,FragmentManager 不會再停止運作。(I573ddb/183634730)
  • 當根層級畫面檢視已設定 transitionGroup=”true” 時,Fragment 的畫面檢視現在會於使用 hide() 時正確地設為 GONE。(aosp/1766655b/193603427)
  • FragmentActivity 現在一律會解鎖儲存的狀態為生命週期回呼中覆寫的第一個作業。(I6db7a)

依附元件更新

1.3.5 版本

2021 年 6 月 16 日

androidx.fragment:fragment:1.3.5androidx.fragment:fragment-ktx:1.3.5androidx.fragment:fragment-testing:1.3.5 發布。1.3.5 版本包含這些修訂版本。

修正錯誤

  • 修正在 Fragment 1.3.4aosp/1679887 造成的共用元素轉換中的迴歸。片段現在可以正確地處理轉換群組 (直接透過 transitionGroup="true" 設定,或透過 transitionNamebackground 間接設定),共用元素將不再傳送 IndexOutOfBoundsException。(I16484b/188679569b/188969304)

1.3.4 版本

2021 年 5 月 18 日

androidx.fragment:fragment:1.3.4androidx.fragment:fragment-ktx:1.3.4androidx.fragment:fragment-testing:1.3.4 發布。1.3.4 版本包含這些修訂版本。

修正錯誤

  • 修正搭配 ViewModelProvider 或在 Fragment 中 的 viewModel() Jetpack Compose 方法使用 ViewTreeViewModelStoreOwner.get() 時,會在 Fragment 1.3.3 加入迴歸的問題。如果覆寫 getDefaultViewModelProviderFactory(),這些用途現在會在正確地使用 Fragment 提供的 ViewModelProvider.Factory (和 @AndroidEntryPoint 註解的片段一樣)。如果未覆寫該方法,與 Fragment 檢視畫面一起的儲存和還原狀態的 SavedStateViewModelFactory 就會建立為預設中心。(I5cbfab/186097368)
  • 在 API 29 上使用 FragmentContainerView 時,插邊不會再無限期地分派,修正 BottomNavigationBarFloatingActionButton 執行個體的問題。(I1bb78b/186012452)
  • 現在您可以在處理結束後,從片段結果套裝組合中擷取 Parcelable。(I65932b/187443158)
  • 在 ViewGroup 上執行共用元素轉換時,如果 ViewGroup 的 transitionGroup 設為 False,系統就能正確地轉換。(I99675)

1.3.3 版

2021 年 4 月 21 日

androidx.fragment:fragment:1.3.3androidx.fragment:fragment-ktx:1.3.3androidx.fragment:fragment-testing:1.3.3 發布。1.3.3 版本包含這些修訂版本。

新功能

  • 使用 ViewTreeSavedStateRegistryOwner.get() 搭配 Fragment 的檢視畫面傳回 SavedStateRegistryOwner 時,現在可以正確地使用 SavedStateViewModelFactory。(I21acfb/181577191)

修正錯誤

  • 修正 Fragment 1.3.2 中引起的迴歸問題;填入 FragmentTransaction 且包含 setPrimaryNavFragment 作業 (例如 NavHostFragment 使用的作業) 時,此問題會導致 popEnter 動畫無法執行。(I38c87b/183877426)
  • FragmentContainerView 現在會確保每個 Fragment 都會分派一組新的 WindowInsets,確保每個片段現在都能獨立消耗插邊。(I63f68b/172153900)
  • 當子項片段新增至 ID 與自訂 Dialog 類別相同的容器中,DialogFragment 現在可以正確地處理案件,因此解決重複使用 BottomSheetDialog 等對話內部使用的 ID 時導致的檢視區塊階層問題。(Ie6279b/180021387)
  • FragmentManager.dump() 現在可正確地在已啟用片段的清單中縮排第一個片段。(If5c33b/183705451)

新狀態管理員錯誤修正

  • 新的片段狀態管理員現在可透過隱藏作業,正確地處理結束事件轉換。(I9e4deb/184830265)

1.3.2 版本

2021 年 3 月 24 日

已釋出 androidx.fragment:fragment:1.3.2androidx.fragment:fragment-ktx:1.3.2androidx.fragment:fragment-testing:1.3.21.3.2 版本包含下列修訂版本。

新狀態管理員錯誤修正

  • 同時執行 popBackStack()commit() 作業時,上次作業會設定所有動畫的方向,而不會執行某些快顯動畫和部分進入的動畫。(I7072eb/181142246)
  • 在共用元素階層中的檢視畫面將不再於執行共用元素轉換時清除轉換名稱。(I4d4a6b/179934757)

依附元件更新

  • 片段現在依附於 Activity 1.2.2,修正使用 Fragment 1.3.1 以上版本時 Activity 的 InvalidFragmentVersionForActivityResult Lint 檢查問題。
  • 片段現在依附於 Lifycycle 2.3.1

1.3.1 版本

2021 年 3 月 10 日

androidx.fragment:fragment:1.3.1androidx.fragment:fragment-ktx:1.3.1androidx.fragment:fragment-testing:1.3.1 發布。1.3.1 版本包含這些修訂版本。

新功能

  • DialogFragment 中的對話方塊現可透過 DecorView 存取 ViewTree 擁有者,確保 DialogFragment 可與 ComposeView 搭配使用。(Ib9290b/180691023)

修正錯誤

  • 使用 FragmentContainerView 匯入現有 RESUMED 活動的片段,現在會在設定變更後正確顯示。(Ie14c8b/180538371)
  • 片段 toString() 的結尾不再有額外的 } (I54705b/177761088)
  • FragmentActivity 中的覆寫方法現在可正確繼承基礎方法 javaDoc (I736ceb/139548782)
  • setFragmentResultsetFragmentResultListener 的文件已更新其參數文件,使其不再接受可為空值 (I990bab/178348386)

新狀態管理員錯誤修正

  • 修正 mFocusedView 造成的片段記憶體流失 (Ib4e9eb/179925887)
  • 使用顯示/隱藏交易時,片段現在可以正確呼叫 onCreateOptionsMenu (I8bce8b/180255554)
  • 有片段 (轉換前開始) 的子項片段現在可以正確觸及 RESUMED (Ic11e6b/180825150)
  • 使用 <fragment> 標記加載的片段現在一律適用於 RESUMED (I452acI9fa49)

依附元件更新

1.3.0 版本

2021 年 2 月 10 日

androidx.fragment:fragment:1.3.0androidx.fragment:fragment-ktx:1.3.0androidx.fragment:fragment-testing:1.3.0 發布。1.3.0 版本包含這些修訂版本。

自 1.2.0 版以來的重大異動

  • 新的狀態管理員FragmentManager 的重大內部重新編寫修正了多個生命週期、動畫和轉換分派的問題,以及延期片段的處理方式。
  • Activity Result API 整合:新增 Activity 1.2.0ActivityResultRegistry API 支援,可處理 startActivityForResult()+onActivityResult()requestPermissions()+onRequestPermissionsResult() 流程,除了針對測試這些流量提供的掛鉤之外,不會覆寫 Fragment 中的方法。請參閱最新的從活動取得結果

    • 此版本修正了幾項無效要求代碼的問題以及權限指派要求,避免 Activity Result API 使用舊版 FragmentActivity。您必須升級至 1.3.0 版,才能在 FragmentActivityAppCompatActivity 中使用 Activity Result API。
  • Fragment Result API:現支援透過 FragmentManager 的新 API 在兩個片段之間傳送結果。這項功能適用於「導覽」中的階層片段 (父項/子項)、DialogFragment 和片段,且可確保結果至少傳送給 STARTED 時,Fragment 才會傳送到您的片段。目標片段 API 已淘汰,並改用新的 API。請參閱使用 Fragment Result API 取得結果

  • FragmentOnAttachListenerFragmentActivityFragmentonAttachFragment() 回呼已淘汰。已新增 FragmentOnAttachListener,以提供更靈活的替代方案:將 onAttachFragment() 的委派功能指派給其他可測試的監聽器,並支援將直接事件新增至 FragmentManagers (除了直接子項 FragmentManager 之外)。

  • FragmentScenario 改善fragment-testing 構件中的 FragmentScenario 類別在 Kotlin 中經過重新編寫,並進行了幾項改善:

    • FragmentScenario 現在使用 setMaxLifecycle() 以實作 moveToState(),確保所有 API 層級的行為一致,並解除 Fragment 狀態與基礎 Activity 之間的關係。
    • FragmentScenario 現在支援設定初始 Lifecycle.State,藉此在移動至各個 Lifecycle.State 前先確認片段狀態。
    • 現在改為使用允許傳回值的 Kotlin 修訂擴充功能方法 withFragmentonFragment FragmentScenario API。值得一提的是,這個區塊會擷取指定區塊中產生的例外狀況。
  • ViewTree 支援Fragment現在支援在Lifecycle 2.3.0 中新增的 ViewTreeLifecycleOwner.get(View)ViewTreeViewModelStoreOwner.get(View)ViewTreeSavedStateRegistryOwner API SavedState 1.1.0,可使 Fragment 傳回 ViewModelStoreOwner,Fragment 則與 SavedStateRegistryOwnerLifecycleOwner 連結至片段的 Lifecyle 檢視畫面 (在 Fragment 內使用 View 時)。

  • TRANSIT_ 動畫變更:片段預設效果、TRANSIT_FRAGMENT_OPENTRANSIT_FRAGMENT_CLOSETRANSIT_FRAGMENT_FADE 現在會使用 Animator,而不是 Animation。用於建構這些動畫的資源現已設為不公開。

  • setRetainInstance() 淘汰:Fragment 中的 setRetainInstance() 方法已淘汰。推出 ViewModels 後,開發人員可利用特定 API 保留狀態,並將其與 Activity、Fragment 和 Navigation 圖表建立關聯。因此,開發人員可以使用一般且未保留的片段,並分別保留所需的特定狀態,避免常見的外洩來源、同時保留單一建立與刪除保留狀態的實用屬性 (也就是 ViewModelonCleared() 回呼)。

  • ViewPager 1 轉接程式淘汰ViewPager2 1.0.0 推出後,與 ViewPager 互動的 FragmentPagerAdapterFragmentStatePagerAdapter 類別已淘汰。請參閱從 ViewPager 移轉至 ViewPager2

1.3.0-rc02 版本

2021 年 1 月 27 日

androidx.fragment:fragment:1.3.0-rc02androidx.fragment:fragment-ktx:1.3.0-rc02androidx.fragment:fragment-testing:1.3.0-rc02 發布。1.3.0-rc02 版本包含這些修訂版本。

修正錯誤

  • 修正設定變更後,父項 DialogFragment 會顯示在子項 DialogFragment 上方的問題;子項對話方塊片段一律顯示在上層對話方塊片段上方。(I30806b/177439520)
  • 修正問題:如果使用 Animation 執行 hide 作業,會導致隱藏片段在動畫結束時閃爍。(I57e22b/175417675)
  • 在附加檢視表階層之前新增的轉換片段,現在可與 RESUMED 正確連結。(I1fc1db/177154873)

新狀態管理員錯誤修正

  • Fragment 的檢視畫面 Lifecycle 現在可以正確地處理在 Lifecycle 達到 CREATED 之前刪除片段的檢視畫面,避免出現表示「沒有來自 INITIALIZED 的下傳事件」例外內容。(eda2bdb/176138645)
  • 使用 Animator 的片段現在會在使用 FragmentContainerView 時,以正確的順序顯示。(Id9aa3b/176089197)

1.3.0-rc01 版本

2020 年 12 月 16 日

androidx.fragment:fragment:1.3.0-rc01androidx.fragment:fragment-ktx:1.3.0-rc01androidx.fragment:fragment-testing:1.3.0-rc01 發布。1.3.0-rc01 版本包含這些修訂版本。

修正錯誤

  • onPrepareOptionsMenu() 現在使用與 onCreateOptionsMenu() 相同的邏輯,而父項片段呼叫 setMenuVisibility(false) 時不會再呼叫此方法。(Id7de8b/173203654)

新狀態管理員錯誤修正

  • 已修正將含有 Animation 的片段新增至 FragmentContainerView 後,會干擾 Pop 作業加入的問題。(I952d8)
  • 修正在 onCreate()onViewCreated() 方法中如果遭到取代,片段檢視畫面就會保留在檢視區塊階層中的問題。(I8a7d5)
  • 繼續處理時,聚焦現已還原至 Fragment 根層級檢視畫面。(Ifc84b)
  • 在同一個片段交易中合併及取代作業現在會顯示正確的動畫 (Ifd4e4b/170328691)

1.3.0-beta02 版本

2020 年 12 月 2 日

androidx.fragment:fragment:1.3.0-beta02androidx.fragment:fragment-ktx:1.3.0-beta02androidx.fragment:fragment-testing:1.3.0-beta02 發布。1.3.0-beta02 版本包含這些修訂版本。

新功能

  • FragmentScenario 已完全轉換為 Kotlin,同時使用 Kotlin 1.4 適用於 FragmentAction 的功能介面,確保原始碼與二進位檔相容。(I19d31)

行為變更

  • 不用使用 classandroid:name 屬性加載片段的 FragmentContainerView 現在可以在 FragmentActivity 之外使用。(Id4397b/172266337)
  • 嘗試將片段時間生命週期上限設為 DESTROYED 時,將會擲回 IllegalArgumentException (Ie7651b/170765622)
  • 初始化處於 DESTROYED 狀態的 FragmentScenario 時,現在會擲回 IllegalArgumentException (I73590b/170765622)

新狀態管理員錯誤修正

  • 修正問題:如果使用 AnimatorTRANSIT_FRAGMENT_ 選項的片段轉換過程中斷,檢視畫面不會達到最終狀態。(I92426b/169874632)
  • 修正會導致有結束的 Animation 片段無法正確刪除的錯誤。(I83d65)
  • 結束的片段如果反轉其效果,現在會正確地取消並以正確的輸入效果重新開始。(I62226b/167092035)
  • 修正 hide()Animator 結束事件無法執行的問題。(Id7ffe)
  • 片段現在會於延遲然後立即啟動時正確顯示。(Ie713bb/170022857)
  • 片段如果在動畫期間移除其聚焦的檢視畫面,將不再於達到 RESUMED 時嘗試在卸離的檢視畫面上還原焦點 (I38c65b/172925703)

外部貢獻

  • FragmentFactory 現在會針對不同的 ClassLoader 執行個體分別快取片段類別。感謝 Simon Schiller!(#87b/113886460)

1.3.0-beta01 版本

2020 年 10 月 1 日

androidx.fragment:fragment:1.3.0-beta01androidx.fragment:fragment-ktx:1.3.0-beta01androidx.fragment:fragment-testing:1.3.0-beta01 發布。1.3.0-beta01 版本包含這些修訂版本。

新功能

  • setMaxLifecycle() 現在支援將 Lifecycle 狀態設為 INITIALIZING,但前提是該片段尚未移至 CREATED。(b/159662173)

API 異動

行為變更

修正錯誤

  • 使用 <fragment> 標記加載的片段現在會正確等待,直到其檢視畫面於移至 STARTED 前加入至容器中 (I02f4c)
  • 會先顯示,然後 setMaxLifecycle()CREATED 的片段現在會正確地執行其結束效果。(b/165822335)
  • 移除未新增至返回堆疊的卸離的片段,不會再造成記憶體流失。感謝 Nicklas Ansman Giertz!(b/166489383)
  • 使用中的片段現在一律非空值 FragmentManager,而有非空值 FragmentManager 的片段將總是會視為已啟用。(aosp/1422346)
  • 片段預設效果、TRANSIT_FRAGMENT_OPENTRANSIT_FRAGMENT_CLOSETRANSIT_FRAGMENT_FADE 現已改用 Animator,而非 Animation。(b/166155034)

新狀態管理員錯誤修正

  • 片段現在會在動畫開始播放前正確還原視角。(Icc256)
  • 只有共用元素轉換的片段,現在正確地完成其特殊效果,也就是說,它們會實際轉為其最終狀態 (Iaebc7b/166658128)
  • 在刪除片段前,系統一律會從容器中移除片段檢視。(Id5876)
  • 新的狀態管理員現在會一致地移除結束片段檢視畫面,然後再加入進入片段檢視畫面。(I41a6e)
  • 片段檢視畫面的瀏覽權限明確變更現在會遵守新的狀態管理員設定。也就是說,如果在動畫開始前將進入片段的檢視畫面設為 INVISIBLE,該檢視畫面就不會保持顯示。(b/164481490)
  • 片段現在會以 Animators 優先,而不是 Animations,也就是說,如果片段同時都有 AnimatorAnimation,就只會執行前者並忽略後者。(b/167579557)
  • 新的狀態管理員在使用進入動畫時,不會再導致片段閃爍。(b/163084315)

已知問題

使用新版狀態管理員時,如果在進入特殊效果時按下返回,而不是返回至上一個片段,舊的片段絕對不會重新加入,導致顯示空白畫面。(b/167259187b/167092035b/168442830)

1.3.0-alpha08 版本

2020 年 8 月 19 日

androidx.fragment:fragment:1.3.0-alpha08androidx.fragment:fragment-ktx:1.3.0-alpha08androidx.fragment:fragment-testing:1.3.0-alpha08 發布。1.3.0-alpha08 版本包含這些修訂版本。

新狀態管理員

此版本包含 FragmentManager 內部狀態管理的重大重構,主要影響生命週期方法、動畫和轉換作業的分派,以及延遲交易的處理方式。這個選項預設為啟用。詳情請參閱片段:重新建立內部網誌文章。(b/139536619b/147749580)

  • 您可以使用 FragmentManager.enableNewStateManager(boolean) 中的 experimental API 來控制 FragmentManager 是否使用新的狀態管理工具。(I7b6ee)

以下問題只會在使用新版狀態管理員時修正:

  • replace 的上一個片段現在會於新的片段開始前正確地停止。(b/161654580)
  • 片段現在會避免在相同片段中出現多個競爭動畫,避免 Animation 覆寫所有 Transition 效果,或是只針對個別片段執行 AnimatorTransition。(b/149569323)
  • 所有進入和結束片段的 enterTransitionexitTranstion 現在都會執行,而非只有最後一個進入片段和第一個結束片段。(b/149344150)
  • 已延後的片段不再卡在 CREATED 狀態,而是會然後移至有其他片段的 STARTED。(b/129035555)
  • 修正在混合延後的重新預訂交易和非重新預訂交易時,FragmentManager 會不正確執行運算子的問題。(b/147297731)
  • 如果在多個片段中同時填入多個片段,那麼在延後片段時,系統不會再顯示中繼片段。(b/37140383)
  • FragmentManager 現可在 onAttachFragment() 回呼中呼叫 findFragmentById()findFragmentByTag() 時傳回正確的片段。(b/153082833)
  • 取代片段的區段在延後的片段刪除後,就不會再呼叫 onCreateView() 的片段。(b/143915710)
  • 嘗試合併架構 Transition 和 AndroidX Transition 執行個體的錯誤訊息,表示片段有無效轉換片段的錯誤訊息現在會顯示。(b/155574969)

行為變更

  • 您現在可以在片段的 onCreate() 生命週期方法中,透過 ActivityResultLauncher 呼叫 launch()。(b/161464278)
  • onCreate() 之後呼叫 registerForActivityResult() 現在可擲回例外狀況,表示不允許此設定,而非在設定變更後直接不傳回結果。(b/162255449)
  • FragmentActivity 現在會使用 Activity 1.2.0-alpha08 中導入的 OnContextAvailableListener API 還原 FragmentManager 的狀態。任何新增至 FragmentActivity 子類別的事件監聽器,都會在此事件監聽器之後執行。(I513da)

修正錯誤

  • 使用 startIntentSenderForResult() 時現在必須遵守 ActivityOptions。(b/162247961)

已知問題

  • 使用新的狀態管理員時,直接在 onViewCreated() 之後和 onResume() 之前設定片段的根層級瀏覽權限,會導致您設定的瀏覽權限遭到負責控管根檢視表瀏覽權限的 FragmentManager 覆寫。為解決這個問題,請一律使用 hide()show() 運算變更片段的瀏覽權限。(b/164481490)

1.3.0-alpha07 版本

2020 年 7 月 22 日

androidx.fragment:fragment:1.3.0-alpha07androidx.fragment:fragment-ktx:1.3.0-alpha07androidx.fragment:fragment-testing:1.3.0-alpha07 發布。1.3.0-alpha07 版本包含這些修訂版本。

新功能

  • FragmentScenario 現在支援將初始 Lifesycle 狀態設為 CREATEDSTARTEDRESUMED,而不是一律將片段移至 RESUMED 狀態。(b/159662750)
  • 新增 onFragmentFragmentScenario API 替代選項 (採用 Kotlin 修訂後擴充功能方法 withFragment),此選項可讓您回傳值。值得一提的是,這個區塊會擷取指定區塊中產生的例外狀況。(b/158697631)

行為變更

  • FragmentScenario 現在使用 setMaxLifecycle() 以實作 moveToState(),確保所有 API 層級的行為一致,並解除 Fragment 狀態與基礎 Activity 之間的關係。(b/156527405)
  • ViewTreeSavedStateRegistryOwner 傳回的 SavedStateRegistryOwner 已連結到片段檢視畫面的 Lifecycle。這樣可確保其狀態會與片段檢視畫面的狀態同時儲存和復原。(b/158503763)

修正錯誤

  • 片段現在會等待片段的檢視畫面先附加,然後再呼叫 ViewCompat.requestApplyInsets(),避免出現插入要求遺失的情況。(b/158095749)
  • 呼叫 clearFragmentResultListener 可正確清除生命週期觀察器。(b/159274993)

1.3.0-alpha06 版本

2020 年 6 月 10 日

已釋出 androidx.fragment:fragment:1.3.0-alpha06androidx.fragment:fragment-ktx:1.3.0-alpha06androidx.fragment:fragment-testing:1.3.0-alpha061.3.0-alpha06 版本包含這些修訂版本。

新功能

  • FragmentActivityFragmentonAttachFragment() 回呼已淘汰。已新增 FragmentOnAttachListener,以提供更靈活的替代方案:將 onAttachFragment() 的委派功能指派給其他可測試的監聽器,並支援將直接事件新增至 FragmentManagers (除了直接子項 FragmentManager 之外)。(I06d3d)

修正錯誤

  • 父項片段現在可以在子項片段之前還原其檢視畫面狀態,修正在 DialogFragment 設定將另一個 DialogFragment 顯示為子項片段後,變更顯示順序的問題。(b/157195715)
  • 修正以往 UseRequireInsteadOfGet Lint 檢查無法正確處理 ?.!! 運算子的連續使用情況,這個問題現已修正。(b/157677616)

1.3.0-alpha05 版本

2020 年 5 月 20 日

androidx.fragment:fragment:1.3.0-alpha05androidx.fragment:fragment-ktx:1.3.0-alpha05androidx.fragment:fragment-testing:1.3.0-alpha05 發布。1.3.0-alpha05 版本包含這些修訂版本。

新功能

API 異動

  • setFragmentResult()setFragmentResultListener() API 現已分別採用非空值的 BundleFragmentResultListener。如要明確清除先前設定的結果或事件監聽器,請使用新的 clearFragmentResult()clearFragmentResultListener() 方法。(b/155416778)
  • 用來接收 lambda 的 setFragmentResultListener() Kotlin 擴充功能現已標示為 inline。(b/155323404)

行為變更

  • 先前已淘汰 startActivityForResult()startIntentSenderForResult(),以及 FragmentrequestPermissions 為目前內部使用 ActivityResultRegistry,因此使用這些 API 時,請針對您的要求程式碼移除僅使用較低位元 (低於 0xFFFF) 的限制。(b/155518741)

說明文件更新

  • 展開 Fragment(@LayoutRes int)DialogFragment(@LayoutRes int) 建構函式的說明文件,以釐清使用預設 FragmentFactory 時,系統會使用子類別的引數呼叫這些建構函式。(b/153042497)

1.3.0-alpha04 版本

2020 年 4 月 29 日

androidx.fragment:fragment:1.3.0-alpha04androidx.fragment:fragment-ktx:1.3.0-alpha04androidx.fragment:fragment-testing:1.3.0-alpha04 發布。1.3.0-alpha04 版本包含這些修訂版本。

新功能

  • 現支援透過 FragmentManager 的新 API 在兩個片段之間傳送結果。這項功能適用於「導覽」中的階層片段 (父項/子項)、DialogFragment 和片段,且可確保結果至少傳送給 STARTED 時,Fragment 才會傳送到您的片段。(b/149787344)

API 異動

  • 已淘汰目標片段 API。如要在片段之間傳輸資料,請改用新的 Fragment Result API。(b/149787344)
  • Fragment 上的 startActivityForResult()/onActivityResult()requestPermissions()/onRequestPermissionsResult() API 已淘汰。請使用 Activity Result API。(aosp/1290887)
  • 來自 Activity 1.2.0-alpha04破壞性變更prepareCall() 方法已重新命名為 registerForActivityResult()。(aosp/1278717)

修正錯誤

  • 片段的 getViewLifecycleOwner() 現在已在呼叫 onSaveInstanceState() 之前停止,因此會反映片段生命週期的行為。(b/154645875)
  • 呼叫片段的 setMenuVisibility(false) 現在可以正確變更其子項片段提供的選單顯示設定。(b/153593580)
  • 修正透過 FragmentContainerView 將片段新增至 DialogFragment 的檢視階層時會發生 illegalStateException 的問題。(b/154366601)
  • 代管活動以外的片段時,片段的 getDefaultViewModelProviderFactory() 方法不會再停止運作。(b/153762914)

1.3.0-alpha03 版本

2020 年 4 月 1 日

androidx.fragment:fragment:1.3.0-alpha03androidx.fragment:fragment-ktx:1.3.0-alpha03androidx.fragment:fragment-testing:1.3.0-alpha03 發布。1.3.0-alpha03 版本包含這些修訂版本。

API 異動

  • FragmentprepareCall 方法現在是 final。(b/152439361)

修正錯誤

  • 修正使用 BottomSheetDialogFragment 時,Fragment 1.3.0-alpha02 中導入的迴歸問題。(b/151652127aosp/1263328aosp/1265163)
  • 修正設定變更後,從片段使用 prepareCall 的問題。(b/152137004)
  • 修正使用 setTargetFragment() 時忽略共用元素和結束轉換的問題。(b/152023196)
  • Fragment 1.2.4 中:更新片段 ProGuard 規則,以允許對保留的片段進行模糊處理。(b/151605338)
  • Fragment 1.2.4 中:已停用 DialogFragment 類別的 FragmentLiveDataObserve Lint 規則,因為其生命週期和檢視畫面生命週期都會保持同步,因此呼叫 observe 時可以安全使用 thisviewLifecycleOwner。(b/151765086)

依附元件變更

  • 片段取決於 Activity 1.2.0-alpha03,這對 Activity 1.2.0-alpha02 導入的 Activity Result API 有大幅改善。

1.3.0-alpha02 版本

2020 年 3 月 18 日

androidx.fragment:fragment:1.3.0-alpha02androidx.fragment:fragment-ktx:1.3.0-alpha02androidx.fragment:fragment-testing:1.3.0-alpha02 發布。1.3.0-alpha02 版本包含這些修訂版本。

新功能

  • 新增 Activity 1.2.0-alpha02 中導入的 ActivityResultRegistry API 支援,可處理 startActivityForResult()+onActivityResult()requestPermissions()+onRequestPermissionsResult() 流程,除了針對測試這些流量提供的掛鉤之外,不會覆寫 Fragment 中的方法。請參閱最新的從 Activity 取得結果。(b/125158199)

API 異動

  • DialogFragment 現在提供使用 @LayoutRes 的建構函式,可指出 onCreateView() 預設應調整的版面配置。(b/150327080)
  • onActivityCreated() 方法現已淘汰。與片段檢視畫面相連的程式碼應透過 onViewCreated() 執行 (在 onActivityCreated() 之前立即呼叫),而其他初始化程式碼則應在 onCreate() 中。如要在活動的 onCreate() 完成時接收回呼,LifeCycleObserver 活動應於 onAttach() 中活動的 Lifecycle 註冊,並在收到 onCreate() 回呼時移除。(b/144309266)

修正錯誤

  • Fragment 1.2.3 中:修正在 onCreateDialog() 內呼叫 getLayoutInflater() 時,在 DialogFragment 中導致 StackOverflowError 的錯誤。(b/117894767aosp/1258664)
  • Fragment 1.2.3 中:減少 Fragment 內含 ProGuard 規則的範圍,確保系統會移除未使用的片段。(b/149665169)
  • Fragment 1.2.3 中:修正 UseRequireInsteadOfGet 使用遮蔽 Kotlin 屬性名稱的本機變數名稱時,系統會進行檢查的問題。(b/149891163)
  • Fragment 1.2.3 中:FragmentContainerView 因為在版面配置預覽中使用錯誤的建構函式,而不再擲回 UnsupportedOperationException。(b/149707833)

已知問題

  • BottomSheetDialogFragment 不再正確地固定螢幕上的對話方塊。(b/151652127)

1.3.0-alpha01 版本

2020 年 3 月 4 日

androidx.fragment:fragment:1.3.0-alpha01androidx.fragment:fragment-ktx:1.3.0-alpha01androidx.fragment:fragment-testing:1.3.0-alpha01 發布。1.3.0-alpha01 版本包含這些修訂版本。

新功能

API 異動

  • Fragments 的 setRetainInstance() 方法已淘汰。推出 ViewModels 後,開發人員可利用特定 API 保留狀態,並將其與 Activity、Fragment 和 Navigation 圖表建立關聯。因此,開發人員可以使用一般且未保留的片段,並分別保留所需的特定狀態,避免常見的外洩來源、同時保留單一建立與刪除保留狀態的實用屬性 (也就是 ViewModelonCleared() 回呼)。(b/143911815)
  • 由於 ViewPager2 1.0.0 已推出,與 ViewPager 互動的 FragmentPagerAdapterFragmentStatePagerAdapter 類別已經淘汰。請參閱從 ViewPager 移轉至 ViewPager2。(b/145132715)

修正錯誤

  • Fragment ProGuard 規則現在只會保留預設建構函式 Fragment 類別 (而不是所有 Fragment 執行個體),修正 Fragment 1.2.1 中導入的迴歸問題。(b/149665169
  • Fragment 1.2.2 中新增的 require___() Lint 規則,在與 shadow 資源名稱相同的名稱底下,對應的本機變數不再是誤判 (例如 view)。(b/149891163)
  • 使用 Android Studio 中的版面配置預覽時,FragmentContainerView 不會再擲回 UnsupportedOperationException。(b/149707833)
  • 修正狀態儲存後新增的保留片段不會持續重新建立,且會在每次設定變更後刪除。(b/145832397)

1.2.5 版本

1.2.5 版本

2020 年 6 月 10 日

androidx.fragment:fragment:1.2.5androidx.fragment:fragment-ktx:1.2.5androidx.fragment:fragment-testing:1.2.5 發布。1.2.5 版本包含這些修訂版本。

修正錯誤

  • 片段的 getViewLifecycleOwner() 現在已在呼叫 onSaveInstanceState() 之前停止,因此會反映片段生命週期的行為。這項功能之前已於 Fragment 1.3.0-alpha04 中推出。(b/154645875)
  • 呼叫片段的 setMenuVisibility(false) 現在可以正確變更其子項片段提供的選單顯示設定。這項功能之前已於 Fragment 1.3.0-alpha04 中推出。(b/153593580)

1.2.4 版本

1.2.4 版本

2020 年 4 月 1 日

androidx.fragment:fragment:1.2.4androidx.fragment:fragment-ktx:1.2.4androidx.fragment:fragment-testing:1.2.4 發布。1.2.4 版本包含這些修訂版本。

修正錯誤

  • 更新 Fragment ProGuard 規則,以允許對保留的片段進行模糊處理。(b/151605338)
  • 已停用 DialogFragment 類別中 FragmentLiveDataObserve Lint 規則,因為其生命週期和檢視畫面生命週期都會保持同步,因此呼叫 observe 時可以安全使用 thisviewLifecycleOwner。(b/151765086)

1.2.3 版本

1.2.3 版本

2020 年 3 月 18 日

androidx.fragment:fragment:1.2.3androidx.fragment:fragment-ktx:1.2.3androidx.fragment:fragment-testing:1.2.3 發布。1.2.3 版本包含這些修訂版本。

修正錯誤

  • 修正 DialogFragment 中的錯誤,此錯誤在 onCreateDialog() 內呼叫 getLayoutInflater() 會導致 StackOverflowError。(b/117894767aosp/1258665)
  • 減少 Fragment 內含 ProGuard 規則的範圍,確保系統會移除未使用的片段。(b/149665169)
  • 修正 UseRequireInsteadOfGet 使用遮蔽 Kotlin 屬性名稱的本機變數名稱時,系統會進行檢查的問題。(b/149891163)
  • FragmentContainerView 無法再因為於版面配置預覽中使用不正確的建構函式擲回 UnsupportedOperationException。(b/149707833)

1.2.2 版本

1.2.2 版本

2020 年 2 月 19 日

androidx.fragment:fragment:1.2.2androidx.fragment:fragment-ktx:1.2.2androidx.fragment:fragment-testing:1.2.2 發布。1.2.2 版本包含這些修訂版本。

新的 Lint 檢查

  • Lint 建議使用 viewLifecycleOwner 做為 LifecycleOwner,以呼叫 onCreateView()onViewCreated()onActivityCreated() 中的 OnBackPressedDispatcher。(b/142117657)
  • 新增 Lint 檢查,確認您在使用 fragment-testing 成果時使用的是正確的 debugImplementation。(b/141500106)
  • 片段現在會建議使用相關聯的 require___() 方法,以取得更多說明錯誤訊息,而不是同時包含 包含 getrequire 所有 Fragment API 的 checkNotNull(get___())requireNonNull(get___())get___()!!。(aosp/1202883)

修正錯誤

  • 修正 Fragment ProGuard 檔案以避免 R8 警告 (b/148963981)
  • 改善現有的 Lint 檢查,建議使用 viewLifecycleOwner 時使用 observe,這樣也可以處理 observelivedata-ktx 擴充功能方法版本。(b/148996309)
  • 修正許多 Lint 檢查的格式 (aosp/1157012)

外部貢獻

  • 感謝 Zac Sweers 代表 Slack 提供 require___() 的 Lint 檢查!(aosp/1202883)

1.2.1 版本

1.2.1 版本

2020 年 2 月 5 日

androidx.fragment:fragment:1.2.1androidx.fragment:fragment-ktx:1.2.1androidx.fragment:fragment-testing:1.2.1 發布。1.2.1 版本包含這些修訂版本

修正錯誤

  • 透過 addreplace 方法新增的片段,採用 Class 執行個體 (或 Kotlin 修訂版) 現已預設由 ProGuard 保留。(b/148181315)
  • 執行 finishUpdate() 時,FragmentStatePagerAdapterFragmentPagerAdapter 不再偵測到 FragmentManager 擲回的例外狀況。(aosp/1208711)
  • 修正 FragmentManager.findFragment() 無法與透過 <fragment> 標記新增的片段搭配運作的問題。(b/147784323)
  • 使用 <fragment> 標記加載的片段,現在會在版面配置中 onCreate() 之前一律接受 onInflate() 的呼叫。(aosp/1215856)
  • 當 Activity 已經刪除時,針對 FragmentManager 執行個體呼叫 toString() 不會再擲回 NullPointerException。(b/148189412)

依附元件變更

版本 1.2.0

版本 1.2.0

2020 年 1 月 22 日

androidx.fragment:fragment:1.2.0androidx.fragment:fragment-ktx:1.2.0androidx.fragment:fragment-testing:1.2.0 發布。1.2.0 版本包含這些修訂版本

自 1.1.0 版以來的重要異動

  • FragmentContainerViewFragmentContainerView 是強烈建議加入的片段,用於動態新增片段,取代 FrameLayout 或其他版面配置。這也支援與 <fragment> 標記相同的 classandroid:name 和選用 android:tag,但使用一般 FragmentTransaction 新增這個初始片段,而非 <fragment> 使用的自訂程式碼路徑。
  • onDestroyView() 時間碼:片段現在會等待結束動畫、結束架構轉換,然後結束 AndroidX 轉換 (使用轉換 1.3.0 時) 結束,再呼叫 onDestroyView()
  • add()replace() 為基礎的類別:在 FragmentTransaction 中加入 add()replace() 的超載,且採用 Class<? extends Fragment> 與選擇性的 Bundle引數。這些方法會使用您的 FragmentFactory 建構要新增的 Fragment 執行個體。使用修正類型的 Kotlin 擴充功能 (例如 fragmentTransaction.replace<YourFragment>(R.id.container)) 也已新增至 fragment-ktx
  • Lifecycle ViewModel SavedState 整合:現在 SavedStateViewModelFactory 在搭配 Fragment 使用 by viewModels()by activityViewModels()ViewModelProvider 建構函式或 ViewModelProviders.of() 時,使用的是原廠預設選項。
  • 新 Lint 檢查:新增 Lint 檢查,確保您在透過 onCreateView()onViewCreated()onActivityCreated() 觀察 LiveData 時正在使用 getViewLifecycleOwner()
  • getFragmentManager() 淘汰:Fragment 的 getFragmentManager()requireFragmentManager() 方法已淘汰,並由單一 getParentFragmentManager() 方法取代,而該非傳回空值 FragmentManager片段就會加入 (您可以使用 isAdded() 來判斷是否安全呼叫)。
  • 已淘汰 FragmentManager.enableDebugLogging():靜態 FragmentManager.enableDebugLogging 方法已淘汰。FragmentManager 現在會遵循 FragmentManager 標記的 Log.isLoggable(),因此您不必重新編譯應用程式,就能啟用 DEBUGVERBOSE 記錄。

已知問題

  • 僅在 FragmentContainerView 透過 classandroid:name 屬性參考的片段,不會由 ProGuard 自動保留,您必須手動為每個片段類別新增保留規則。(b/142601969)
  • 在有 FragmentContainerView 的 XML 中使用 classandroid:name 加入 NavHostFragment 時,無法在 Activity 的 onCreate() 中使用 findNavController()。(b/142847973)

1.2.0-rc05 版本

2020 年 1 月 8 日

androidx.fragment:fragment:1.2.0-rc05androidx.fragment:fragment-ktx:1.2.0-rc05androidx.fragment:fragment-testing:1.2.0-rc05 發布。1.2.0-rc05 版本包含這些修訂版本

修正錯誤

  • 修正使用 <fragment> 標記時 Fragment 1.2.0-rc04 中會導致活動刪除時無法正確呼叫 onViewCreated() 的問題。(b/146290333)
  • 使用 <fragment> 標記新增的片段現在也能正常清除其設定,即使只出現在版面配置中 (也就是僅出現在橫向版面配置中) 也一樣。因此,即使這些片段配不在版面配置中,也會正確地移至 CREATED,而不會執行個體化但絕對不會在任何生命週期方法中移動。(b/145769287)

1.2.0-rc04 版本

2019 年 12 月 18 日

androidx.fragment:fragment:1.2.0-rc04androidx.fragment:fragment-ktx:1.2.0-rc04androidx.fragment:fragment-testing:1.2.0-rc04 發布。1.2.0-rc04 版本包含這些修訂版本

修正錯誤

  • 已調整 TRANSIT_FRAGMENT_OPENTRANSIT_FRAGMENT_CLOSETRANSIT_FRAGMENT_FADE 的動畫,以免發生視覺問題。(b/145468417)

1.2.0-rc03 版本

2019 年 12 月 4 日

androidx.fragment:fragment:1.2.0-rc03androidx.fragment:fragment-ktx:1.2.0-rc03androidx.fragment:fragment-testing:1.2.0-rc03 發布。1.2.0-rc03 版本包含這些修訂版本

修正錯誤

  • 修正 findFragmentById()/findFragmentByTag() 在結束動畫/轉換執行期間,系統仍會移除片段的意外行為變更情況。(b/143982969aosp/1167585)
  • 如果包含的活動呼叫 onSaveInstanceState(),子項片段現在會正確地在其父項前停止。(b/144380645)
  • 修正以下問題:在彈出隱藏的「片段」之後,檢視畫面會錯誤地標記為 INVISIBLE (b/70793925)
  • 片段共用元素轉換現在會處理已旋轉、縮放等的檢視畫面 (b/142835261)

說明文件更新

  • 釐清有關 setUserVisibleHint() 的淘汰說明文件。(b/143897055)
  • 改善 setFragmentFactory()getFragmentFactory() 的說明文件,以更有效地表示設定 FragmentFactory 也會影響子項 FragmentManagers。(aosp/1170095)

依附元件變更

  • 片段現在取決於 Lifecycle 2.2.0-rc03、Lifecycle ViewModel SavedState 1.0.0-rc03 以及 Activity 1.1.0-rc03

1.2.0-rc02 版本

2019 年 11 月 7 日

androidx.fragment:fragment:1.2.0-rc02androidx.fragment:fragment-ktx:1.2.0-rc02androidx.fragment:fragment-testing:1.2.0-rc02 發布。1.2.0-rc02 版本包含這些修訂版本

修正錯誤

  • 在 Kotlin 中,從 onCreateView()onViewCreated()onActivityCreated() 觀察 LiveData 時使用 getViewLifecycleOwner() 的 LintFix (於 Fragment 1.2.0-rc01 中加入),現在會使用 Kotlin 屬性存取語法 viewLifecycleOwner,而非 getViewLifecycleOwner()。(aosp/1143821)

1.2.0-rc01 版本

2019 年 10 月 23 日

androidx.fragment:fragment:1.2.0-rc01androidx.fragment:fragment-ktx:1.2.0-rc01androidx.fragment:fragment-testing:1.2.0-rc01 發布。1.2.0-rc01 版包含這些修訂版本

新功能

  • FragmentContainerView 現在除了支援 android:name 以外,還支援 class 屬性 (與 <fragment> 標記的功能相同)。(b/142722242)
  • 新增一項 Lint 檢查,確保您在透過 onCreateView()onViewCreated()onActivityCreated() 觀察 LiveData 時使用 getViewLifecycleOwner()。(b/137122478)

修正錯誤

  • DialogFragment 上的 onDismissonCancel 回呼,現在能確保傳送至這些 DialogInterface 的函式並非空值,且 getDialog() 會在執行時傳回非空值。(b/141974033)
  • FragmentContainerView 現已新增由 classandroid:name 定義的片段做為加載的一部分,因此 findFragmentById()findFragmentByTag() 會立即運作。(b/142520327)
  • 修正 FragmentContainerView 中因為儲存的狀態已儲存的 IllegalStateException。(b/142580713)
  • 修正當 FragmentContainerView 類別經模糊處理時,FragmentContainerView 中的 UnsupportedOperationException。(b/142657034)

已知問題

  • 僅在 FragmentContainerView 透過 classandroid:name 屬性參考的片段,不會由 ProGuard 自動保留,您必須手動為每個片段類別新增保留規則。我們已停用建議移至 FragmentContainerView 的 Lint 規則,直到透過 aapt2 的問題修正為止。(b/142601969)

1.2.0-beta02 版本

2019 年 10 月 11 日

androidx.fragment:fragment:1.2.0-beta02androidx.fragment:fragment-ktx:1.2.0-beta02androidx.fragment:fragment-testing:1.2.0-beta02 發布。1.2.0-beta02 版本包含這些修訂版本

修正錯誤

  • 修正問題:Fragment 的 onInflate() 並未收到 FragmentContainerView 的適當屬性,例如 NavHostFragment。(b/142421837)

1.2.0-beta01 版本

2019 年 10 月 9 日

androidx.fragment:fragment:1.2.0-beta01androidx.fragment:fragment-ktx:1.2.0-beta01androidx.fragment:fragment-testing:1.2.0-beta01 發布。1.2.0-beta01 版本包含這些修訂版本

新功能

  • FragmentContainerView 新增初始片段的支援,並加入 android:name 和選用的 android:tag XML 屬性的支援。與 <fragment> 標記不同的是,FragmentContainerView 會在背景中使用 FragmentTransaction 來新增初始片段,因此可以在 FragmentContainerView 中進一步執行 FragmentTransaction 版面配置作業。(b/139830628b/141177981)
  • 片段現在包含 Lint 警告,可讓您快速將 FragmentContainerView 替換成 <fragment>。(b/139830056)

修正錯誤

  • 修正使用 androidx.transition 時的 ClassCastException。(b/140680619)
  • 使用 Transition 1.3.0-beta01 時,片段現在會等待 androidx.transition 轉換 (除了架構轉換和動畫外,也已在片段 1.2.0-alpha03 中修正) 以及 Fragment 1.2.0-alpha02),以在分派 onDestroyView() 前完成。(aosp/1119841)
  • 使用 Transition 1.3.0-beta01 時,片段現在會先取消 androidx.transition 轉換,然後再啟動相同容器的新轉換/動畫。(aosp/1119841)
  • 修正使用 FragmentContainerView 時,在片段的根層級使用 androidx.transition 轉換時的 API 17 和以下版本問題。(b/140361893)
  • fragment-testing 成果現已支援 AndroidX Test 1.2.0,修正了與最新版 Espresso 3.2.0 不相容的問題。(b/139100149)
  • 移除 FragmentManager 中的 Log.w 使用。(aosp/1126468)

已知問題

  • Fragment 的 onInflate() 並未收到 FragmentContainerView 的適當屬性,例如 NavHostFragment。(b/142421837)

1.2.0-alpha04 版本

2019 年 9 月 18 日

androidx.fragment:fragment:1.2.0-alpha04androidx.fragment-ktx:example:1.2.0-alpha04androidx.fragment:fragment-testing:1.2.0-alpha04 發布。1.2.0-alpha04 版本包含這些修訂版本

API 異動

  • Fragment 中的 getFragmentManager()requireFragmentManager() 方法已淘汰,並由單一 getParentFragmentManager() 方法取代,而這會傳回 Fragment 中新增的非空值 FragmentManager (您可以使用 isAdded() 判斷是否安全)。(b/140574496)
  • 靜態 FragmentManager.enableDebugLogging 方法已淘汰。FragmentManager 現在會遵循 FragmentManager 標記的 Log.isLoggable(),因此您不必重新編譯應用程式,就能啟用 DEBUGVERBOSE 記錄。(aosp/1116591)

修正錯誤

  • 片段現在會在其他片段執行的動畫結束時正確地刪除。(b/140574199)
  • 修正問題:片段會不正確地呼叫 Activity.findViewById()。(aosp/1116431)

1.2.0-alpha03 版本

2019 年 9 月 5 日

androidx.fragment:fragment:1.2.0-alpha03androidx.fragment:fragment-ktx:1.2.0-alpha03androidx.fragment:fragment-testing:1.2.0-alpha03 發布。這個版本包含的修訂版本,請按這裡

API 異動

  • FragmentContainerView 現在是 final。(b/140133091)

修正錯誤

  • FragmentContainerView 現在會於返回堆疊放出片段時,會正確還原繪圖順序。(b/139104187)
  • 修正問題:同時填入片段及新增片段時,系統會執行錯誤的動畫。(b/111659726)
  • 片段現在會等待轉換 (除了在 Fragment 1.2.0-alpha02 中已修正的動畫之外) 完成,然後再分派 onDestroyView()。(b/138741697)

1.2.0-alpha02 版本

2019 年 8 月 7 日

androidx.fragment:fragment:1.2.0-alpha02androidx.fragment:fragment-ktx:1.2.0-alpha02androidx.fragment:fragment-testing:11.2.0-alpha02 發布。這個版本包含的修訂版本,請按這裡

新功能

  • 使用 by viewModels()by activityViewModels()ViewModelProvider 建構函式,或搭配 Fragment 使用 ViewModelProviders.of() 時,SavedStateViewModelFactory 現在是預設的原廠設定。(b/135716331)
  • FragmentTransaction 上搭配 setTransition 使用 TRANSIT_FRAGMENT_OPENTRANSIT_FRAGMENT_CLOSETRANSIT_FRAGMENT_FADE 時,預設動畫已更新為 Android 10 裝置上活動使用的動畫。(aosp/1012812aosp/1014730)

API 異動

  • 加入 FragmentContainerView,做為強烈建議您加入動態片段的動態容器以取代 FrameLayout 的用法,以修正動畫 Z-order 問題和視窗分派至 Fragments 的動畫。(b/37036000aosp/985243b/136494650)
  • 加入靜態 FragmentManager.findFragment(View) 方法,以從片段加載的畫面檢視擷取包含的 Fragment。fragment-ktx 中也提供 Kotlin 擴充功能。(aosp/1090757)
  • 在採用 Class<? extends Fragment> 和選擇性引數 BundleFragmentTransaction 上,新增 add()replace() 的超載。這些方法會使用您的 FragmentFactory 建構要新增的 Fragment 執行個體。使用修正類型的 Kotlin 擴充功能 (例如 fragmentTransaction.replace<YourFragment>(R.id.container)) 也已新增至 fragment-ktx。(b/126124987)
  • @MainThread 註解已新增至 Fragment 生命週期回呼。(b/127272564)
  • FragmentTransactionFragmentManager.BackStackEntry 的導覽標記標題相關 API 已淘汰。(b/138252944)
  • FragmentTransactionsetTransitionStyle 方法已淘汰。(aosp/1011537)
  • FragmentManager 中的許多方法已不再是 abstractFragmentManager 本身仍是 abstract,因此不應直接執行個體化或延伸;您應只會繼續收到來自 getSupportFragmentManager()getChildFragmentManager() 等的現有執行個體。

修正錯誤

  • Fragment 1.1.0-rc04 中:片段現在會明確取消 Fragment 中的延期轉換。(b/138251858)
  • Fragment 1.1.0-rc03 中:修正多次呼叫有逾時的 postponeEnterTransition()。並不會取消先前逾時設定的問題。(b/137797118)
  • Fragment 1.1.0-rc02 中:修正移除目前項目時 FragmentPagerAdapterFragmentStatePagerAdapter 中的當機問題。(b/137209870)
  • 片段現在會等待動畫完成,然後再傳送 onDestroyView()。(b/136110528)
  • 從子項片段及其子系的片段動畫,目前在父項片段中製作動畫時已正確處理。(b/116675313)
  • 修正使用共用元素轉換及結合彈出式視窗與新增作業時 NullPointerException 的問題。(b/120507394)
  • 新增在 Robolectric 測試中使用 FragmentPagerAdapterFragmentStatePagerAdapterIllegalStateException 的解決方法。(b/137201343)

1.2.0-alpha01 版本

2019 年 7 月 2 日

androidx.fragment:fragment:1.2.0-alpha01androidx.fragment:fragment-ktx:1.2.0-alpha01androidx.fragment:fragment-testing:1.2.0-alpha01 發布。這個版本包含的修訂版本,請按這裡

新功能

  • FragmentManager 現在會在連結片段的檢視畫面,及直接在呼叫 onViewCreated() 前呼叫 requestApplyInsets(),藉此確保檢視畫面總是會有正確的插邊。(b/135945162)

修正錯誤

  • 修正在 replace() 前使用 setPrimaryNavigationFragment()FragmentTransactionNullPointerException。(b/134673465)

1.1.0 版本

1.1.0 版本

2019 年 9 月 5 日

androidx.fragment:fragment:1.1.0androidx.fragment:fragment-ktx:1.1.0androidx.fragment:fragment-testing:1.1.0 發布。這個版本包含的修訂版本,請按這裡

自 1.0.0 版以來的重要異動

  • fragment-testingfragment-testing 構件會提供 FragmentScenario 類別,以測試隔離中的片段。詳情請參閱測試應用程式的片段說明文件
  • FragmentFactory:您現在可在 FragmentManager 上設定 FragmentFactory,藉此管理片段建立例項,並移除不需使用引數的建構函式。
  • ViewModels 的 Kotlin 資源委派fragment-ktx 成果現在包含兩個 Kotlin 資源委派:by viewModels() 用於存取與個別片段相關聯的 ViewModel,以及 by activityViewModels() 用於存取以活動為依據的 ViewModels。
  • 生命週期上限:您現在可以呼叫 FragmentTransactionsetMaxLifecycle(),為片段設定最大生命週期狀態。這會取代現已淘汰的 setUserVisibleHint()FragmentPagerAdapterFragmentStatePagerAdapter 有新的建構函式,可讓您切換至新行為。
  • FragmentActivity LayoutId 建構函式FragmentActivity 的子類別現在可選擇呼叫 FragmentActivity 上採用 R.layout ID 的建構函式,指出應將何種版面配置設為內容檢視畫面,並取代在 onCreate() 中呼叫 setContentView()。這個動作不會改變子類別採用無引數建構函式的要求。
  • Fragment LayoutId 建構函式Fragment 的子類別現在可選擇呼叫 Fragment 上採用 R.layout ID 的建構函式,指出應將何種版面配置設為此片段使用,並覆寫 onCreateView()。加載的版面配置可在 onViewCreated() 中設定。
  • 以逾時延後:新增需要逾時的 postponeEnterTransition() 超載。

1.1.0-rc04 版本

2019 年 8 月 7 日

androidx.fragment:fragment:1.1.0-rc04androidx.fragment:fragment-ktx:1.1.0-rc04androidx.fragment:fragment-testing:1.1.0-rc04 發布。這個版本包含的修訂版本,請按這裡

修正錯誤

  • 片段現在可以在 Fragment 彈出時,正確取消延後的轉換。(b/138251858)

1.1.0-rc03 版本

2019 年 7 月 19 日

androidx.fragment:fragment:1.1.0-rc03androidx.fragment:fragment-ktx:1.1.0-rc03androidx.fragment:fragment-testing:1.1.0-rc03 發布。這個版本包含的修訂版本,請按這裡

修正錯誤

  • 修正多次呼叫有逾時的 postponeEnterTransition() 時不會取消前一個逾時的問題。(b/137797118)

1.1.0-rc02 版本

2019 年 7 月 17 日

androidx.fragment:fragment:1.1.0-rc02androidx.fragment:fragment-ktx:1.1.0-rc02androidx.fragment-testing:fragment:1.1.0-rc02 發布。這個版本包含的修訂版本,請按這裡

修正錯誤

  • 修正 FragmentPagerAdapterFragmentStatePagerAdapter 移除現有項目時的停止運作問題。(b/137209870)

1.1.0-rc01 版本

2019 年 7 月 2 日

androidx.fragment:fragment:1.1.0-rc01androidx.fragment:fragment-ktx:1.1.0-rc01androidx.fragment:fragment-testing:1.1.0-rc01 發布。這個版本包含的修訂版本,請按這裡

修正錯誤

  • 執行轉換時,片段現在會於使用 show()hide() 運算時正確地更新其瀏覽權限。(b/133385058)
  • 修正在 replace() 前使用 setPrimaryNavigationFragment()FragmentTransactionNullPointerException。(b/134673465)

1.1.0-beta01 版本

2019 年 6 月 5 日

androidx.fragment:fragment:1.1.0-beta01androidx.fragment:fragment-ktx:1.1.0-beta01androidx.fragment:fragment-testing:1.1.0-beta01 發布。這個版本包含的修訂版本,請按這裡

修正錯誤

  • 巢狀片段的 androidx.lifecycle.Lifecycle 回呼 (尤其是 STARTEDRESUMEDPAUSEDSTOPPEDDESTROYED) 現已正確建立。(b/133497591)
  • 在 Fragment 的 onCreate() 中註冊的 OnBackPressedCallback 執行個體,現在可以優先於子項 FragmentManager。(b/133175997)
  • 取代父項片段後,子項片段就不再以動畫呈現。(b/121017790)
  • 使用 animateLayoutChanges="true" 時,系統會忽略片段動畫和轉場效果,修正無法正確刪除片段的問題。(b/116257087)

1.1.0-alpha09 版本

2019 年 5 月 16 日

androidx.fragment:fragment:1.1.0-alpha09androidx.fragment:fragment-ktx:1.1.0-alpha09androidx.fragment:fragment-testing:1.1.0-alpha09 發布。這個版本包含的修訂版本,請按這裡

API 異動

  • 當主要導覽片段發生變更時,現在片段會接收新的 onPrimaryNavigationFragmentChanged(boolean) 方法回呼。aosp/960857

修正錯誤

  • 移除父項片段時,子項片段加載的選單項目已移除。b/131581013

1.1.0-alpha08 版本

2019 年 5 月 7 日

androidx.fragment:fragment:1.1.0-alpha08androidx.fragment:fragment-ktx:1.1.0-alpha08androidx.fragment:fragment-testing:1.1.0-alpha08 發布。這個版本包含的修訂版本,請按這裡

這個版本與 Preferences 1.1.0-alpha01 到 1.1.0-alpha04 不相容。使用此版本 Fragment 時,請升級至 1.1.0-alpha05 版本。

新功能

  • 新增會採用逾時的 postponeEnterTransition() 新超載,此後 Fragment 將自動呼叫 startPostponedEnterTransition() b/120803208

API 異動

  • 破壞性變更:先前淘汰的 FragmentFactory instantiate 方法採用 Bundle 已移除。aosp/953856
  • 破壞性變更:FragmentPagerAdapterFragmentStatePagerAdapter 中的 RESUME_ONLY_CURRENT_FRAGMENTUSE_SET_USER_VISIBLE_HINT 常數已分別重新命名為 BEHAVIOR_RESUME_ONLY_CURRENT_FRAGMENTBEHAVIOR_SET_USER_VISIBLE_HINTaosp/954782

修正錯誤

  • 透過 setMaxLifecycle() 設定生命週期上限的片段,已無法在達到最終狀態前繼續。b/131557151
  • 使用 setMaxLifecycle(Lifecycle.State.CREATED) 時,片段會正確顯示檢視畫面。aosp/954180

1.1.0-alpha07 版本

2019 年 4 月 25 日

androidx.fragment:fragment:1.1.0-alpha07androidx.fragment:fragment-ktx:1.1.0-alpha07androidx.fragment:fragment-testing:1.1.0-alpha07 發布。這個版本包含的修訂版本,請按這裡

新功能

  • 您現在可以在 FragmentTransaction 呼叫 setMaxLifecycle(),藉此設定片段的生命週期上限。這會取代現已淘汰的 setUserVisibleHint()FragmentPagerAdapterFragmentStatePagerAdapter 有新的建構函式,可讓您切換至新行為。(b/129780800)

API 異動

  • FragmentScenariomoveToState(STARTED) 目前只能透過 API 24 以上版本的裝置呼叫。(b/129880016)

行為變更

  • 基於 (b/129907905) 的結果,當代管活動重新建立時,返回堆疊的片段不會傳回 onCreateView() 的回呼。只有當片段顯示時 (即返回堆疊彈出),系統才會呼叫 onCreateView()

修正錯誤

  • 修正在 XML 中使用 <fragment> 標記以及 FragmentActivityAppCompatActivitycontentLayoutId 建構函式的問題。(b/129907905)
  • 修正設定變更後,返回堆疊片段不會在設定變更後移至至少 CREATED,導致 ActiveModel 和子項保留的片段無法正確處理的問題。(b/129593351)
  • 修正已保留片段在執行個體狀態儲存後,因已保留片段不同步而導致 restoreSaveState 當機的問題。(b/130433793) (aosp/947824)
  • 修正問題:如果 FragmentManager 有返回堆疊,新增的 OnBackPressedCallback 片段將具有片段生命週期。詳情請參閱 androidx.activity 1.0.0-alpha07。(aosp/948209)
  • 片段將不再針對動畫強制執行 LAYER_TYPE_HARDWARE。如果您特別需要硬體圖層動畫,請將此設為動畫的一部分。(b/129486478)

1.1.0-alpha06 版本

2019 年 4 月 3 日

androidx.fragment:fragment:1.1.0-alpha06androidx.fragment:fragment-ktx:1.1.0-alpha06androidx.fragment:fragment-testing:1.1.0-alpha06 發布。這個版本包含的修訂版本,請按這裡

新功能

  • FragmentManager 擲回的例外狀況現在會於訊息中加入片段的名稱。(b/67759402)

API 異動

  • FragmentFragmentActivity 現在包含第二種建構函式;該函式可使用 @LayoutRes int 取代先前以 @ContentView 為類別加上註解的行為。這個方法適用於應用程式和程式庫模組。(b/128352521)
  • FragmentActivity 的 onActivityResult() 現已正確標示為 @CallSuper。(b/127971684)
  • 採用引數套裝組合的 FragmentFactory 的 instantiate 方法已不適用,使用新 instantiate 的應用程式不會採用套裝組合的超載。(b/128836103)
  • FragmentScenario 方法現已使用 @StyleRes 正確加註。(aosp/924193)
  • FragmentTabHost 已淘汰。(b/127971835)
  • 已移除 FragmentActivity 的 getThemedContext()。(aosp/934078)

修正錯誤

  • 修正 1.1.0-alpha05 中導致收到的項目片段在螢幕上閃爍的迴歸。(b/129405432)
  • 修正 popBackStack+replace+popBackStack 運算系列後,主要導覽片段會遺失的問題。(b/124332597)
  • 修正在還原片段狀態時,在 Activity 中使用 @ContentView 建構函式的問題。(b/127313094)
  • 修正 setTargetFragment() 的邏輯,也就是以尚未附加至 FragmentManager 的片段取代現有的目標片段。(aosp/932156)

1.1.0-alpha05 版本

2019 年 3 月 13 日

androidx.fragment:fragment:1.1.0-alpha05androidx.fragment:fragment-ktx:1.1.0-alpha05androidx.fragment:fragment-testing:1.1.0-alpha05 發布。您可以前往這裡查看這個版本包含的修訂版本完整清單。

新功能

行為變更

  • 使用連結到不同 FragmentManager 的 Fragment 呼叫 remove()hide()show()detach()setPrimaryNavigationFragment() 時,現在會傳送 IllegalStateException,而非直接失敗 (aosp) /904301)

修正錯誤

  • FragmentActivityonNewIntent 現已正確加上 @CallSuper 標記 (b/124120586)
  • 修正使用 getDialog().dismiss()getDialog().cancel() 時可能會呼叫 DialogFragment onDismiss() 的問題 (b/126563750)

1.1.0-alpha04 版本

2019 年 2 月 7 日

androidx.fragment:fragment 1.1.0-alpha04androidx.fragment:fragment-ktx 1.1.0-alpha04androidx.fragment:fragment-testing 1.1.0-alpha04 發布。

新功能

  • 現已支援 @ContentView 類別註解,可讓您指示應擴展哪個版面配置 XML 檔案以加載替代覆寫 onCreateView()。建議您在 onViewCreated() 中執行檢視畫面相關操作。(aosp/837619)
  • fragment-testing 現在依附於 androidx.test:core-ktx 1.1.0 穩定版 (b/121209673)
  • 您現在可以透過 openActionBarOverflowOrOptionsMenu 使用 FragmentScenario,測試片段代管選項選單 (b/121126668)

API 異動

  • 新增可傳回 @NonNull Bundle 或擲回 IllegalStateExceptionrequireArguments() 方法 (b/121196360)
  • 新增附註 getLifecycle()getViewLifecycleOwner()getViewLifecycleOwnerLiveData() 不應遭到覆寫,日後版本也將成為新版本。如果目前正在覆寫這個方法,請提出功能要求檔案。(aosp/880714)
  • 新增附註getViewModelStore()不應遭到覆寫,日後版本也將成為新版本。如果目前正在覆寫這個方法,請提出功能要求檔案。(aosp/880713)
  • 修正舊版 Fragments 的二進位檔相容性問題。(aosp/887877) (aosp/889834)

修正錯誤

  • 傳遞 nullsetTargetFragment() 時,系統會正確地清除目標片段。(aosp/849969)
  • 修正 onDestroy() 中或之後有時無法顯示目標片段的問題。(b/122312935)
  • DialogFragment 的 ondismiss() 現會在 onDestroy() 之前呼叫。(aosp/874133) (aosp/890734)

1.1.0-alpha03 版本

2018 年 12 月 17 日

新功能

  • 片段現已導入 BundleSavedStateRegistryOwner,取決於新推出的 SavedState 程式庫 [aosp/824380]
  • 新增 by activityViewModels Kotlin 屬性委派,以擷取與活動相關的 ViewModels [b/119050253]
  • by viewModels Kotlin 屬性委派已展開,讓您可以採用選擇性的 Lambda 方式以取得 ViewModelStoreOwner,從而在父項 Fragment 或其他自訂 ViewModelStoreOwner 中,以 val viewModel: MyViewModel by viewModels(::requireParentFragment) 等程式碼 傳遞 [b/119050253]

API 異動

  • FragmentScenario 現在可讓您指定主題,例如 Theme.AppCompat [b/119054431]。這是一項破壞性變更。
  • 新增可傳回 @NonNull View 或擲回 IllegalStateExceptionrequireView() 方法 [b/120241368]
  • 新增可傳回 @NonNull Fragment 或擲回 IllegalStateExceptionrequireParentFragment() 方法 [b/112103783]

修正錯誤

  • 修正 InvalidStateException:失敗儲存狀態 (b/120814739)
  • 從已儲存的執行個體狀態還原的片段,會一律接收非空值 Bundle [b/119794496]
  • 移除的片段如果重新加入,其 Lifecycle 物件就不會再重複使用 [b/118880674]

1.1.0-alpha02 版本

2018 年 12 月 3 日

新功能

  • FragmentScenario 的 Kotlin 擴充功能現在可讓您將 lambda 用於 Fragment 建構,做為傳遞 FragmentFactory 執行個體的替代選項。(aosp/812913)

修正錯誤

  • 修正在返回堆疊中使用巢狀片段的 IllegalStateException (b/119256498)
  • 修正搭配 FragmentFactory 使用 FragmentScenario.recreate() 會當機的問題 (aosp/820540)
  • 修正移除片段後即無法存取目標片段的問題 (aosp/807634)

1.1.0-alpha01 版本

2018 年 11 月 5 日

這是 fragment-testing 構件和 FragmentScenario 的第一個版本,此版本以 androidx.test:core API 為基礎。詳情請參閱片段測試說明文件

新功能

  • 全新 FragmentCase 類別可用於個別測試片段。
  • 您現在可以在任何 FragmentManager 上設定 FragmentFactory,以控制新的片段執行個體執行個體化的方式。
  • 新增 by viewModels() Kotlin 屬性委派,以從片段擷取 ViewModels。
  • Fragment onStop() 中的待處理輸入事件 (例如點擊) 現已取消。

API 異動

  • 大幅展開 Fragment API 途徑的空值註解。

修正錯誤

  • 修正導致 LiveData 中 Fragment 運算失敗的問題 (b/77944637)

已知問題

  • 從 FragmentManager 移除片段後,就無法存取目標片段。
  • fragment-testing 取決於 androidx.test:core:1.0.0-beta01,而不是正確的 androidx.test:core:1.0.0