ViewPager2

AndroidX 依赖项

要使用 ViewPager2，请将以下 AndroidX 依赖项添加到您项目的 build.gradle 文件中

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

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

反馈

您的反馈有助于改进 Jetpack。如果您发现新问题或有改进此库的建议，请告诉我们。在创建新问题之前，请查看该库中现有问题的列表。点击星标按钮，即可为您关注的问题投票。

创建新问题

如需了解详情，请参阅 问题跟踪器文档。

版本 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 现在可以正确填充 CollectionInfo 和 CollectionItemInfo，而 RecyclerView 1.2.0-alpha02 及更高版本默认不再填充这些信息。
• 添加了 FragmentTransactionCallback 接口，用于监听在 FragmentStateAdapter 内部发生的片段生命周期变化。
• 修复了将片段添加到 FragmentManager 时 FragmentStateAdapter 关于初始片段菜单可见性的问题。
• 修复了窗口嵌入 (window insets) 的分发：所有页面现在都能获得相同的嵌入。由于 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 添加了片段状态保存回调。(I45b90)
• ViewPager2 现在不再尝试修复旧 API 版本 (< 30) 中损坏的 WindowInsets 分发，因为该修复本身可能对 ViewPager2 的兄弟视图有害。该修复仍然可用，但已变为可选（opt-in），以便开发者可以根据具体情况决定。通过调用 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 的变更，填充了 RecyclerView 不再默认提供的 CollectionInfo 和 CollectionItemInfo。升级到 RecyclerView 1.2.0-alpha02 时，也请同时更新 ViewPager2 以防止辅助功能回归。

新功能

• 添加了 FragmentTransactionCallback 接口，用于监听在 FragmentStateAdapter 内部发生的片段生命周期变化。(Ibda77)

Bug 修复

• 修复了将片段添加到 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 在 Fragment 之间切换的指南。

版本 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 现在作为默认触摸阈值 (touch slop)
• 修复了空适配器的 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 的文档。

Bug 修复

• 修复了数据集更改/适配器更改后的 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 常量，则无需更改客户端代码。

Bug 修复

• 当 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 注解已设为非公开

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 支持修复
• 处理最小化时或屏幕旋转期间的数据集更新；
• 旋转后删除不相关的 Fragment；
• 删除已删除项的已保存状态。

API 变更

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

已知问题

• clipToPadding
• 无 fakeDrag
• JavaDoc
• 与方向平行的嵌套滚动
• 无屏幕外限制控制
• 需要更好的 TabLayout 集成
• 无 pageWidth 设置器（强制 100%/100%）
• 页面转换器：没有硬件/软件层选择；没有反向绘制顺序
• 在当前页面之前插入页面时保持当前项可见
• 键盘导航需要优化
• FragmentStateAdapter 即将进行稳定性/性能改进