ViewPager2

以滑動式格式顯示檢視畫面或片段。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2024 年 5 月 14 日 1.1.0 - - -

AndroidX 依附元件

如要使用 ViewPager2，請將下列 AndroidX 依附元件新增至專案的 build.gradle 檔案：

Groovy

dependencies {
    implementation "androidx.viewpager2:viewpager2:1.1.0"
}

Kotlin

dependencies {
    implementation("androidx.viewpager2:viewpager2:1.1.0")
}

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.1.0 版本

1.1.0 版本

2024 年 5 月 14 日

發布 androidx.viewpager2:viewpager2:1.1.0。1.1.0 版包含這些修訂版本。

自 1.0.0 版以來的重要變更

  • 修正與 RecyclerView 1.3.1-rc01 以上版本搭配使用時發生的當機問題。
  • ViewPager2 現在會正確填入 RecyclerView 1.2.0-alpha02 以上版本不再預設填入的 CollectionInfo 和 CollectionItemInfo。
  • 新增 FragmentTransactionCallback 介面，以監聽 FragmentStateAdapter 中發生的片段生命週期變更。
  • 修正在 FragmentManager 中新增片段時，初始片段選單顯示設定的 FragmentStateAdapter 問題。
  • 已修正分派的視窗插網：所有頁面現在都會接收相同的插入點。由於 WindowInsets 在舊版 API (低於 API 30) 上調度的方式，可能會導致邊框無法提供給同層級檢視畫面，因此如果您想在低於 API 30 的裝置上套用邊框，就必須透過 WindowInsetsApplier.install(viewPager2) 選擇採用這項修正。

1.1.0-rc01 版本

2024 年 5 月 1 日

發布 androidx.viewpager2:viewpager2:1.1.0-rc01，且自 1.1.0-beta02 版以來皆無重大變更。1.1.0-rc01 版包含這些修訂版本。

1.1.0-beta02 版

2023 年 5 月 24 日

發布 androidx.viewpager2:viewpager2:1.1.0-beta02。查看 1.1.0-beta02 版的修訂項。

API 變更

  • 新增了將回呼儲存至 FragmentTransactionCallback 的 Fragment 狀態。(I45b90)
  • ViewPager2 現在不會再嘗試修正舊版 API (30 以下) 的損毀 WindowInsets 調度，因為修正本身可能會對 ViewPager2 的兄弟姊妹造成傷害。修正程式仍可使用，但已改為選擇性採用，讓開發人員可視情況決定是否採用。呼叫 WindowInsetsApplier.install(viewPager2)) 即可啟用修正項目。(Ic9a85)。

修正錯誤

  • 修正新版 RecyclerView 的相容性問題。這個版本的「ViewPager2」使用者至少應更新至 RecyclerView 1.3.1-rc01 以上版本。

1.1.0-beta01 版本

2021 年 8 月 4 日

發布 androidx.viewpager2:viewpager2:1.1.0-beta01。查看 1.1.0-beta01 版的修訂項。

API 變更

修正錯誤

  • 已修正分派的視窗插網，所有頁面現在都會接收相同的插入點。(I47fef)

1.1.0-alpha01 版本

2020 年 4 月 1 日

發布 androidx.viewpager2:viewpager2:1.1.0-alpha01。1.1.0-alpha01 版包含以下修訂項目。

這個版本會填入 RecyclerView 1.2.0-alpha02 的變更，而RecyclerView 會預設為不再提供 CollectionInfo 和 CollectionItemInfo。更新至 RecyclerView 1.2.0-alpha02 時，也會一併更新 ViewPager2，避免無障礙功能迴歸問題。

新功能

  • 新增了 FragmentTransactionCallback 介面，用於監聽 FragmentStateAdapter 中發生的片段生命週期變更(Ibda77)。

修正錯誤

  • 修正在 FragmentManager 中新增片段時，初始片段選單瀏覽權限的 FragmentStateAdapter 問題(I9d2ff、b/144442240)。

1.0.0 版本

1.0.0 版本

2019 年 11 月 20 日

發布 androidx.viewpager2:viewpager2:1.0.0，對比 1.0.0-rc01 版本無任何變更。1.0.0 版本包含這些修訂版本。

1.0.0 的主要功能

  • 先前的ViewPager導入項目改善項目：
    • 由右至左 (RTL) 版面配置支援
    • 支援垂直方向
    • 值得信賴的 Fragment 支援 (包括處理基礎 Fragment 集合的變更)
    • 資料集變更動畫 (包括DiffUtil支援)
  • 輕鬆從先前的 ViewPager 實作遷移 (盡可能使用 API 對等性)。請參閱遷移指南和範例應用程式。

請參閱指南，瞭解如何使用 ViewPager2 在片段之間滑動。

1.0.0-rc01 版

2019 年 10 月 23 日

androidx.viewpager2:viewpager2:1.0.0-rc01 發布，且自 1.0.0-beta05 起沒有變更。1.0.0-rc01 版包含此連結所列的修訂項目。

1.0.0-beta05 版

2019 年 10 月 9 日

發布了 androidx.viewpager2:viewpager2:1.0.0-beta05。1.0.0-beta05 版包含這些修訂版本。

修正錯誤

  • 修正造成畫面外設定的requestFocus問題。此行為現在與原始 ViewPager 一致。(b/140656866)
  • 修正頁面更改後留在畫面外頁面上的focus。當您變更頁面時，焦點現已清除。(b/140656866)
  • 修正在變更頁面時暫停 / 繼續交易 Fragment 的順序 (現在我們一律會先暫停舊的主要項目，再恢復新項目)。(b/139489059)。
  • 修正 canScrollHorizontally(int) 和 canScrollVertically(int) - 這兩個函式現在會傳回 ViewPager2 是否能按照指定方向捲動。(b/141848404)
  • SwipeRefreshLayout 的問題已修正，使其與 ViewPager2 相容。

1.0.0-beta04 版

2019 年 9 月 5 日

發布了 androidx.viewpager2:viewpager2:1.0.0-beta04。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

  • 修正 Fragment 回溯堆疊的 FragmentStateAdapter 邊緣案例問題。(b/139095195)
  • 修正含有特定屬性設定的 EditText，導致捲動/頁面跳轉/聚焦。(b/138044582、b/139432498)
  • 修正 ItemDecoration 執行個體的問題，以及過度捲動指標位置的解決方法。(b/139012032)。
  • 修正了其他元件中的許多問題，可與 ViewPager2 搭配使用，例如：RecyclerView、NestedScrollView 和 Navigation。

1.0.0-beta03 版

2019 年 8 月 7 日

發布 androidx.viewpager2:viewpager2:1.0.0-beta03。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

  • 修正暫時Fragment狀態的FragmentStateAdapter問題。b/134246546
  • 修正為currentItem和scrollState資料集在順暢捲動期間變更時會發生問題 (已解決的案例)。b/137642608
  • 修正PageTransformer (包括 MarginPageTransformer) 動畫與資料集變更動畫相衝突的問題。b/134658996
  • 修正大型資料集中的流暢捲動動畫 (限制為float整數值)。b/134858960

1.0.0-beta02 版

2019 年 7 月 19 日

發布 androidx.viewpager2:viewpager2:1.0.0-beta02。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

  • 移除 1.0.0-beta01 中意外引入的 jacoco 依附元件。(b/137782951)

1.0.0-beta01 版

2019 年 7 月 17 日

發布 androidx.viewpager2:viewpager2:1.0.0-beta01。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

  • 修正捲動及更新資料集時發生的 ViewPager2.updateCurrentItem 當機問題
  • 修正與 ViewPager2.isLayoutRtl 相關的 NullPointerException 當機問題
  • TOUCH_SLOP_PAGING現在是預設的觸控滑桿
  • OnPageChangeCallback修正空轉接器相關問題 (頁面0而非-1以與ViewPager1進行奇偶校驗)

已知問題

1.0.0-alpha06 版本

2019 年 7 月 2 日

發布 androidx.viewpager2:viewpager2:1.0.0-alpha06。您可以前往這裡查看這個版本包含的修訂項目。

這是我們在凍結 API 並轉為 Beta 版之前計劃的最後一個 Alpha 版，請向我們提供 API 意見回饋。

新功能

  • 更完善的無障礙設計：ACTION_PAGE_RIGHT、ACTION_PAGE_DOWN 等

API 變更

  • FragmentStateAdapter：非主要項目 Fragment的上限為 STARTED，而 menuVisibility 已設為否。
  • PageTransformer、MarginPageTransformer、CompositePageTransformer：position 已修正說明文件。

修正錯誤

  • 修正資料集變更 / 轉接程式變更後的 currentItem。
  • 已修正「MarginPageTransformer」和「offscreenPageLimit」問題。
  • 已修正FakeDrag行為中的無障礙工具動作。

1.0.0-alpha05 版本

2019 年 6 月 5 日

發布 androidx.viewpager2:viewpager2:1.0.0-alpha05。您可以前往這裡查看這個版本包含的修訂項目。

新功能

  • ItemDecorator 導入與 RecyclerView 一致的行為。
  • 導入 MarginPageTransformer，可在頁面之間插入空格 (插邊外)。
  • CompositePageTransformer 可結合多個 PageTransformer。

API 變更

  • FragmentStateAdapter#getItem 方法已重新命名為 FragmentStateAdapter#createFragment - 先前的方法名稱經證實是過去發生的錯誤來源。
  • OFFSCREEN_PAGE_LIMIT_DEFAULT 的值已從 0 變更為 -1。如果使用OFFSCREEN_PAGE_LIMIT_DEFAULT常數，則不需要變更用戶端程式碼。

修正錯誤

  • 「getCurrentItem()」行為已修正 SCROLL_STATE_SETTLING 受到相反方向的拖曳幹擾。
  • 「不保留活動」情境中的 FragmentStateAdapter 類別載入器問題已修正。
  • 已改善 setOffscreenPageLimit 說明文件。

1.0.0-alpha04 版本

2019 年 5 月 7 日

發布了 androidx.viewpager2:viewpager2:1.0.0-alpha04。您可以前往這裡查看這個版本包含的修訂項目。

新功能

  • offscreenPageLimit：用於嚴格控管資料檢視階層中的View / Fragment頁數

API 變更

  • orientation 和 isUserScrollable 屬性不再是 SavedState 的一部分
  • saveState 和 restoreState 方法最後在 FragmentStateAdapter 完成
  • ViewPager2.Orientation和ViewPager2.ScrollState註解已設為不公開

修正錯誤

  • SavedState：修正Activity在刪除 / 重新建立資料後還原的問題
  • SavedState：延遲設定，直到轉接程式設定完成
  • OnPageChangeCallback：修正小邊緣案例

1.0.0-alpha03 版本

2019 年 4 月 3 日

androidx.viewpager2:viewpager2:1.0.0-alpha03 發布。您可以前往這裡查看這個版本包含的修訂項目。

新功能

  • 能夠以程式捲動 ViewPager2：fakeDragBy(offsetPx)。

API 變更

  • FragmentStateAdapter 現在需要 Lifecycle 物件。已新增兩個公用程式建構函式，可從主機 FragmentActivity 或 Fragment 主機取得該建構函式。

修正錯誤

  • 許多 Fragment 支援修正問題：
    • 在最小化或螢幕旋轉期間處理資料集更新；
    • 輪播後移除不相關的片段。
    • 已移除已移除項目的已儲存狀態。
  • PageChangeCallback：修正含有邊界的網頁偏移值計算。

1.0.0-alpha02 版

2019 年 3 月 13 日

發布了 androidx.viewpager2:viewpager2:1.0.0-alpha02。您可以前往這裡查看這個版本包含的修訂項目完整清單。

新功能

  • 停用使用者輸入功能 (setUserInputEnabled、isUserInputEnabled)

API 變更

  • ViewPager2 類別最終結果

修正錯誤

  • FragmentStateAdapter 穩定性修正

1.0.0-alpha01 版

2019 年 2 月 7 日

發布了 androidx.viewpager2:viewpager2 1.0.0-alpha01。這是 ViewPager2 的第一個版本。

新功能

  • 與其先前的android.support.v4.view.ViewPager (VP1) 相比：
    • 支援從右到左 (RTL) 的版面配置
    • 支援垂直方向
    • notifyDataSetChanged完全正常運作 (已解決的 VP1 錯誤)

API 變更

  • FragmentStateAdapter 取代 FragmentStatePagerAdapter
  • RecyclerView.Adapter 取代 PagerAdapter
  • registerOnPageChangeCallback 取代 addPageChangeListener

已知問題

  • clipToPadding
  • 沒有 fakeDrag
  • JavaDoc
  • 與方向平行的巢狀結構捲動
  • 沒有裝置使用時間限制
  • 需要更完善的 TabLayout 整合
  • 未指 pageWidth 設定 (強制 100%/100%)
  • 頁面轉換器：不提供硬體/軟體圖層；無反向繪圖順序
  • 在目前項目之前插入頁面時保持目前項可見
  • 需要鍵盤導覽
  • 即將推出FragmentStateAdapter穩定性 / 效能改善