本頁面由 Cloud Translation API 翻譯而成。

ViewPager2

API 參考資料
androidx.viewpager.adapter
androidx.viewpager.widget

以可滑動格式顯示檢視畫面或片段。

最近更新時間	穩定版	候選版	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 版本

2024 年 5 月 14 日

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

自 1.0.0 版本以來的重要變更

修正與 RecyclerView 1.3.1-rc01 以上版本搭配使用時發生的當機問題。
ViewPager2 現在可正確填入 CollectionInfo 和 CollectionItemInfo，根據預設，RecyclerView 1.2.0-alpha02 以上版本不再填入。

新增 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 變更

已將 Fragment 狀態儲存回呼新增至 FragmentTransactionCallback。(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 變更

升級 Androidx 版本即可使用 Kotlin 1.4 (Id6471、b/165307851、b/165300826)
繼續為所有 Android 程式庫指定 Java 8 (2923f39)

修正錯誤

修正調度視窗插邊的問題，所有頁面現在都會取得相同的插邊。(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 版本

2019 年 11 月 20 日

發布了 androidx.viewpager2:viewpager2:1.0.0，1.0.0-rc01 版沒有任何變更。1.0.0 版本包含這些修訂版本。

1.0.0 的主要功能

先前的 ViewPager 實作項目改善項目：
- 支援從右至左的版面配置
- 支援垂直方向
- 可靠的 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 設為 False。
PageTransformer、MarginPageTransformer、CompositePageTransformer：修正 position 的說明文件。

修正錯誤

修正資料集變更 / 轉接程式變更後的 currentItem。
已修正offscreenPageLimit問題的MarginPageTransformer。
已修正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 常數，則不需要變更用戶端程式碼。

修正錯誤

SCROLL_STATE_SETTLING 受到相反方向的拖曳幹擾時，getCurrentItem() 行為得到修正。
「不要保留活動」情境中的 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 支援修正：
- 在最小化或螢幕旋轉期間處理資料集更新；
- 旋轉後移除不相關的 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
無假拖曳
JavaDoc
與方向平行的巢狀捲動
沒有裝置使用時間限制
需要更完善的 TabLayout 整合功能
無 pageWidth setter (強制 100%/100%)
頁面轉換器：不提供硬體/軟體圖層；無反向繪圖順序
在目前項目之前插入頁面時保持目前項目可見
鍵盤導覽功能需要運作
即將推出FragmentStateAdapter穩定性 / 效能改善措施