ViewPager:传统翻页容器 · AndroidX 源码指南
AAndroidX 源码指南
View 体系
View 体系 · androidx.core

ViewPager:传统翻页容器Core 1.20.0-alpha01

PagerAdapter 与 FragmentPagerAdapter 的使用,以及迁移到 ViewPager2 的注意事项。

最后更新 2026-08-01

复制即用

<androidx.viewpager.widget.ViewPager
    android:id="@+id/view_pager"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
import androidx.viewpager.widget.ViewPager;

ViewPager pager = findViewById(R.id.view_pager);
pager.setAdapter(new PagerAdapter() {
    @Override
    public int getCount() { return pages.size(); }

    @Override
    public boolean isViewFromObject(View view, Object object) {
        return view == object;
    }

    @Override
    public Object instantiateItem(ViewGroup container, int position) {
        View page = pages.get(position);
        container.addView(page);
        return page;
    }

    @Override
    public void destroyItem(ViewGroup container, int position, Object object) {
        container.removeView((View) object);
    }
});

// 监听
pager.addOnPageChangeListener(new ViewPager.OnPageChangeListener() {
    @Override public void onPageScrolled(int pos, float offset, int offsetPx) {}
    @Override public void onPageSelected(int pos) {}
    @Override public void onPageScrollStateChanged(int state) {}
});

ViewPager 与 ViewPager2 对比

维度ViewPagerViewPager2
适配器PagerAdapter/FragmentPagerAdapterRecyclerView.Adapter/FragmentStateAdapter
方向仅横向横向 + 竖向
数据更新notifyDataSetChangednotifyDataSetChanged + getItemId 稳定 id
RTL部分支持完整支持
嵌套滚动有历史问题解决
垂直翻页不支持ORIENTATION_VERTICAL
PageTransformer单页卡顿流畅

迁移到 ViewPager2 要点

  • FragmentPagerAdapter.getItem()FragmentStateAdapter.createFragment()
  • getItemPosition() 通知机制不同(ViewPager2 用稳定 id + containsItem)。
  • addOnPageChangeListenerregisterOnPageChangeCallback(回调类有生命周期,需 unregister)。
  • XML 标签替换为 androidx.viewpager2.widget.ViewPager2

常见陷阱

  • getItemPosition() 不生效:ViewPager2 迁移时是常见坑,改用稳定 id。
  • 忘 unregister 回调OnPageChangeCallback 有泄漏风险。
  • 旧项目继续用 ViewPager:新项目直接 ViewPager2。

要点

  • PagerAdapter 直接管理 View;FragmentPagerAdapter/FragmentStatePagerAdapter 管理 Fragment。
  • 新项目推荐直接使用 ViewPager2:修复了方向、数据更新与嵌套滚动的多数问题。
  • ViewPager2 迁移注意:FragmentPagerAdaptergetItem() 改为 FragmentStateAdapter.createFragment()getItemPosition() 的通知机制不同。
  • Compose 场景直接用 HorizontalPager

相关页面