ViewPager2

以可滑动的格式显示视图或 Fragment。
最近更新时间 稳定版 候选版 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

版本 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 内发生的 fragment 生命周期更改。
  • 修复了将 Fragment 添加到 FragmentManager 时，初始 Fragment 菜单可见性的 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）

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 变更

bug 修复

  • 修复了窗口边衬区的调度问题，现在所有页面都会获得相同的边衬区。(I47fef)

版本 1.1.0-alpha01

2020 年 4 月 1 日

发布了 androidx.viewpager2:viewpager2:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

此版本通过填充默认情况下 RecyclerView 不再提供的 CollectionInfo 和 CollectionItemInfo，随附了 RecyclerView 1.2.0-alpha02 中的一项更改。更新到 RecyclerView 1.2.0-alpha02 时，请同时更新 ViewPager2，以防止 Accessibility 回归问题。

新功能

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

bug 修复

  • 修复了向 FragmentManager 添加 Fragment 时，与初始 Fragment 菜单可见性有关的 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)
  • 为了与 ViewPager2 更好地搭配使用，修复了 SwipeRefreshLayout 中的一个问题。

版本 1.0.0-beta04

2019 年 9 月 5 日

发布了 androidx.viewpager2:viewpager2:1.0.0-beta04。点击此处可查看此版本中包含的提交内容。

bug 修复

  • 修复了 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。点击此处可查看此版本中包含的提交内容。

bug 修复

  • 修复了 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。点击此处可查看此版本中包含的提交内容。

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 现在是默认的触摸溢出值
  • 修复了空适配器（页面 0 而不是 -1，等同于 ViewPager1）的 OnPageChangeCallback 事件问题

已知问题

版本 1.0.0-alpha06

2019 年 7 月 2 日

发布了 androidx.viewpager2:viewpager2:1.0.0-alpha06。点击此处可查看此版本中包含的提交内容。

这是我们在使 API 固定不变并转到测试版之前计划的最后一个 Alpha 版，请向我们提供 API 反馈。

新功能

  • 为改进无障碍功能奠定了基础：ACTION_PAGE_RIGHT、ACTION_PAGE_DOWN 等。

API 变更

  • FragmentStateAdapter：非主要项 Fragment 在 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。点击此处可查看此版本中包含的提交内容。

新功能

  • 引入了 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() 行为。
  • 解决了“不保留 Activity”上下文中的 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 注释已设为非公开状态

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；
    • 移除已移除项的已保存状态。
  • PageChangeCallback：修复了包含外边距的页面的页面偏移量计算问题。

版本 1.0.0-alpha02

2019 年 3 月 13 日

发布了 androidx.viewpager2:viewpager2:1.0.0-alpha02。点击此处可查看此版本中包含的完整提交内容列表。

新功能

  • 停用用户输入的功能（setUserInputEnabled、isUserInputEnabled）

API 变更

  • ViewPager2 类最终确定

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 稳定性/性能有待改进