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 及更高版本在默认情况下不再填充的 CollectionInfoCollectionItemInfo
  • 添加了 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 不再提供的 CollectionInfoCollectionItemInfo,随附了 RecyclerView 1.2.0-alpha02 中的一项更改。更新到 RecyclerView 1.2.0-alpha02 时,请同时更新 ViewPager2,以防止 Accessibility 回归问题。

新功能

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

bug 修复

  • 修复了向 FragmentManager 添加 Fragment 时,与初始 Fragment 菜单可见性有关的 FragmentStateAdapter 问题。(I9d2ffb/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/138044582b/139432498
  • 修复了 ItemDecoration 实例的问题,并解决了过量滚动指示器定位的问题。(b/139012032)
  • 为了与 ViewPager2 更好地搭配使用,修复了其他组件中的多个问题:RecyclerViewNestedScrollViewNavigation

版本 1.0.0-beta03

2019 年 8 月 7 日

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

bug 修复

  • 修复了 Fragment 瞬态的 FragmentStateAdapter 问题。b/134246546
  • 修复了数据集在流畅滚动期间发生更改时出现的 currentItemscrollState 问题(解决了极端情况下的问题)。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_RIGHTACTION_PAGE_DOWN 等。

API 变更

  • FragmentStateAdapter:非主要项 FragmentSTARTED 时设有上限,并且其 menuVisibility 设为 false。
  • PageTransformerMarginPageTransformerCompositePageTransformer:修复了针对 position 的文档。

bug 修复

  • 修复了数据集更改/适配器更改后的 currentItem
  • 修复了 MarginPageTransformeroffscreenPageLimit 问题。
  • 修复了 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 变更

  • orientationisUserScrollable 属性不再是 SavedState 的一部分
  • saveStaterestoreState 方法已在 FragmentStateAdapter 中设为最终状态
  • ViewPager2.OrientationViewPager2.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。点击此处可查看此版本中包含的完整提交内容列表。

新功能

  • 停用用户输入的功能(setUserInputEnabledisUserInputEnabled

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