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。如果您发现新问题或有改进此库的想法，请告诉我们。在创建新问题之前，请查看此库中现有问题。您可以通过点击星形按钮为您已有的问题投票。

创建新问题

有关更多信息，请参阅问题跟踪器文档。

版本 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 初始片段菜单可见性问题。
修复了窗口内边距分发问题：所有页面现在获得相同的内边距。由于旧 API 版本（< API 30）上 WindowInsets 的分发方式可能导致内边距无法用于同级视图，如果您希望在 < 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 中添加了片段状态保存回调。（I45b90）
ViewPager2 现在不再尝试修复旧 API 版本（< 30）损坏的 WindowInsets 分发，因为修复本身可能对 ViewPager2 的同级视图有害。该修复仍然可用，但已成为可选功能，开发者可以根据具体情况决定。通过调用 WindowInsetsApplier.install(viewPager2)) 启用修复。（Ic9a85）

Bug 修复

修复了与较新版本 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）
所有 androidx 库的目标移至 Java 8（2923f39）

Bug 修复

修复了窗口内边距分发问题，所有页面现在获得相同的内边距。（I47fef）

版本 1.1.0-alpha01

2020 年 4 月 1 日

androidx.viewpager2:viewpager2:1.1.0-alpha01 已发布。版本 1.1.0-alpha01 包含这些提交。

此版本伴随着 RecyclerView 1.2.0-alpha02 的一项变更，通过填充 CollectionInfo 和 CollectionItemInfo 来实现，而 RecyclerView 默认不再提供这些信息。更新到 RecyclerView 1.2.0-alpha02 时，请同时更新 ViewPager2 以防止无障碍功能退步。

新功能

添加了 FragmentTransactionCallback 接口，用于监听 FragmentStateAdapter 内部发生的片段生命周期变更。（Ibda77）

Bug 修复

修复了向 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 实现的改进
- 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 包含这些提交。

Bug 修复

修复了在屏幕外页面上 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 已发布。此版本中包含的提交可在此处找到。

Bug 修复

修复了 FragmentStateAdapter 在 Fragment 返回栈方面的边缘情况问题。（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 已发布。此版本中包含的提交可在此处找到。

Bug 修复

修复了 FragmentStateAdapter 瞬时 Fragment 状态的问题。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 已发布。此版本中包含的提交可在此处找到。

Bug 修复

移除了 1.0.0-beta01 中引入的非预期 jacoco 依赖项。（b/137782951）

版本 1.0.0-beta01

2019 年 7 月 17 日

androidx.viewpager2:viewpager2:1.0.0-beta01 已发布。此版本中包含的提交可在此处找到。

Bug 修复

修复了滚动和更新数据集时 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：非主项 Fragments 的状态上限为 STARTED，其 menuVisibility 设置为 false。
PageTransformer、MarginPageTransformer、CompositePageTransformer：position 文档已修复。

Bug 修复

数据集更改/适配器更改后 currentItem 已修复。
MarginPageTransformer 与 offscreenPageLimit 问题已修复。
FakeDrag 行为中的无障碍操作已修复。

版本 1.0.0-alpha05

2019 年 6 月 5 日

androidx.viewpager2:viewpager2:1.0.0-alpha05 已发布。此版本中包含的提交可在此处找到。

新功能

引入了与 RecyclerView 行为一致的 ItemDecorator。
引入了 MarginPageTransformer 以提供在页面之间创建空间（页面内边距之外）的能力。
引入了 CompositePageTransformer 以提供组合多个 PageTransformer 的能力。

API 变更

FragmentStateAdapter#getItem 方法重命名为 FragmentStateAdapter#createFragment - 以前的方法名称已被证明是过去错误的来源。
OFFSCREEN_PAGE_LIMIT_DEFAULT 值从 0 更改为 -1。如果使用 OFFSCREEN_PAGE_LIMIT_DEFAULT 常量，则无需更改客户端代码。

Bug 修复

当 SCROLL_STATE_SETTLING 被反方向拖动中断时，getCurrentItem() 行为已更正。
在“不保留活动”上下文中解决了 FragmentStateAdapter 类加载器问题。
setOffscreenPageLimit 文档已改进。

版本 1.0.0-alpha04

2019 年 5 月 7 日

androidx.viewpager2:viewpager2:1.0.0-alpha04 已发布。此版本中包含的提交可在此处找到。

新功能

offscreenPageLimit：允许严格控制视图层次结构中保留的页面 Views / Fragments 的数量

API 变更

orientation 和 isUserScrollable 属性不再是 SavedState 的一部分
FragmentStateAdapter 中的 saveState 和 restoreState 方法已设为 final
ViewPager2.Orientation 和 ViewPager2.ScrollState 注解已设为非公共

Bug 修复

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 获取它。

Bug 修复

许多 Fragment 支持修复
- 处理最小化或屏幕旋转期间的数据集更新；
- 旋转后移除不相关的 Fragments；
- 移除已移除项目的保存状态。
PageChangeCallback：修复了带边距页面的页面偏移计算。

版本 1.0.0-alpha02

2019 年 3 月 13 日

androidx.viewpager2:viewpager2:1.0.0-alpha02 已发布。此版本中包含的完整提交列表可在此处找到。

新功能

禁用用户输入的能力（setUserInputEnabled, isUserInputEnabled）

API 变更

ViewPager2 类已设为 final

Bug 修复

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 setter（强制 100%/100%）
页面转换器：无硬件/软件层选择；无反向绘制顺序
在当前页面之前插入页面时保持当前页面可见
键盘导航需要改进
FragmentStateAdapter 稳定性/性能改进即将推出