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现在正确填充了RecyclerView 1.2.0-alpha02及更高版本默认不再填充的CollectionInfo和CollectionItemInfo。
添加了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）

错误修复

修复了与更新版本的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）

错误修复

修复了窗口内嵌的调度，所有页面现在都获得相同的内嵌。（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）

错误修复

修复了将片段添加到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 包含这些提交。

错误修复

修复了在屏幕外页面上requestFocus导致页面更改的问题。此行为现在与原始 ViewPager 一致。（b/140656866）
修复了在页面更改后焦点仍然停留在屏幕外页面上的问题。现在在更改页面时会清除焦点。（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 已发布。此版本中包含的提交可以在这里找到这里。

错误修复

修复了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 已发布。此版本中包含的提交可以在这里找到这里。

错误修复

修复了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 已发布。此版本中包含的提交可以在这里找到这里。

错误修复

删除了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现在是默认触摸容差
修复了空适配器（页面0而不是-1，以便与ViewPager1保持一致）的OnPageChangeCallback事件

已知问题

在迁移到稳定版之前，我们仍在处理剩余的未解决问题

版本 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 的问题。
修复了 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 常量，则无需更改客户端代码。

错误修复

当 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 的一部分。
在 FragmentStateAdapter 中将 saveState 和 restoreState 方法设为 final。
将 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 类设为 final。

错误修复

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 的稳定性/性能改进即将推出。