ViewPager2复用Fragment B出现Fragment already added异常的解决方法

问题场景 #

Fragment A中包含ViewPager2，手动创建了一组Fragment B用于ViewPager2展示；当导航到其他Fragment再返回Fragment A时，尝试复用这组Fragment B以避免重复创建，却触发如下异常：

java.lang.IllegalStateException: Fragment already added
at androidx.fragment.app.Fragment.setInitialSavedState(Fragment.java:828)
at androidx.viewpager2.adapter.FragmentStateAdapter.ensureFragment(FragmentStateAdapter.java:277)
at androidx.viewpager2.adapter.FragmentStateAdapter.onBindViewHolder(FragmentStateAdapter.java:183)
at androidx.viewpager2.adapter.FragmentStateAdapter.onBindViewHolder(FragmentStateAdapter.java:72)
at androidx.recyclerview.widget.RecyclerView$Adapter.onBindViewHolder(RecyclerView.java:7678)
at androidx.recyclerview.widget.RecyclerView$Adapter.bindViewHolder(RecyclerView.java:7761)
at androidx.recyclerview.widget.RecyclerView$Recycler.tryBindViewHolderByDeadline(RecyclerView.java:6582)
at androidx.recyclerview.widget.RecyclerView$Recycler.tryGetViewHolderForPositionByDeadline(RecyclerView.java:6848)
at androidx.recyclerview.widget.RecyclerView$Recycler.getViewForPosition(RecyclerView.java:6688)
at androidx.recyclerview.widget.RecyclerView$Recycler.getViewForPosition(RecyclerView.java:6684)
at androidx.recyclerview.widget.LinearLayoutManager$LayoutState.next(LinearLayoutManager.java:2362)
at androidx.recyclerview.widget.LinearLayoutManager.layoutChunk(LinearLayoutManager.java:1662)
at androidx.recyclerview.widget.LinearLayoutManager.fill(LinearLayoutManager.java:1622)
at androidx.recyclerview.widget.LinearLayoutManager.onLayoutChildren(LinearLayoutManager.java:687)
at androidx.recyclerview.widget.RecyclerView.dispatchLayoutStep2(RecyclerView.java:4604)
at androidx.recyclerview.widget.RecyclerView.onMeasure(RecyclerView.java:3981)
at android.view.View.measure(View.java:27124)
at android.view.ViewGroup.measureChild(ViewGroup.java:7951)
at androidx.viewpager2.widget.ViewPager2.onMeasure(ViewPager2.java:504)
at android.view.View.measure(View.java:27124)
at androidx.constraintlayout.widget.ConstraintLayout$Measurer.measure(ConstraintLayout.java:811)
at androidx.constraintlayout.core.widgets.ConstraintWidgetContainer.measure(ConstraintWidgetContainer.java:632)
at androidx.constraintlayout.core.widgets.ConstraintWidgetContainer.layout(ConstraintWidgetContainer.java:733)
at androidx.constraintlayout.core.widgets.analyzer.BasicMeasure.solveLinearSystem(BasicMeasure.java:160)
at androidx.constraintlayout.core.widgets.analyzer.BasicMeasure.solverMeasure(BasicMeasure.java:291)
at androidx.constraintlayout.core.widgets.ConstraintWidgetContainer.measure(ConstraintWidgetContainer.java:120)
at androidx.constraintlayout.widget.ConstraintLayout.resolveSystem(ConstraintLayout.java:1594)
at androidx.constraintlayout.widget.ConstraintLayout.onMeasure(ConstraintLayout.java:1708)
at android.view.View.measure(View.java:27124)
at androidx.swiperefreshlayout.widget.SwipeRefreshLayout.onMeasure(SwipeRefreshLayout.java:705)
at android.view.View.measure(View.java:27124)
at android.view.ViewGroup.measureChildWithMargins(ViewGroup.java:7980)
at android.widget.FrameLayout.onMeasure(FrameLayout.java:194)
at android.view.View.measure(View.java:27124)
at android.widget.LinearLayout.measureVertical(LinearLayout.java:995)
at android.widget.LinearLayout.onMeasure(LinearLayout.java:721)
at android.view.View.measure(View.java:27124)
at androidx.drawerlayout.widget.DrawerLayout.onMeasure(DrawerLayout.java:1156)
at android.view.View.measure(View.java:27124)
at android.view.ViewGroup.measureChildWithMargins(ViewGroup.java:7980)
at android.widget.FrameLayout.onMeasure(FrameLayout.java:194)
at androidx.appcompat.widget.ContentFrameLayout.onMeasure(ContentFrameLayout.java:145)
at android.view.View.measure(View.java:27124)
at android.view.ViewGroup.measureChildWithMargins(ViewGroup.java:7980)
at android.widget.LinearLayout.measureChildBeforeLayout(LinearLayout.java:1552)
at android.widget.LinearLayout.measureVertical(LinearLayout.java:842)
at android.widget.LinearLayout.onMeasure(LinearLayout.java:721)
at android.view.View.measure(View.java:27124)
at android.view.ViewGroup.measureChildWithMargins(ViewGroup.java:7980)
at android.widget.FrameLayout.onMeasure(FrameLayout.java:194)
at android.view.View.measure(View.java:27124)
at android.view.ViewGroup.measureChildWithMargins(ViewGroup.java:7980)
at android.widget.LinearLayout.measureChildBeforeLayout(LinearLayout.java:1552)
at android.widget.LinearLayout.measureVertical(LinearLayout.java:842)
at android.widget.LinearLayout.onMeasure(LinearLayout.java:721)
at android.view.View.measure(View.java:27124)
at android.view.ViewGroup.measureChildWithMargins(ViewGroup.java:7980)
at android.widget.FrameLayout.onMeasure(FrameLayout.java:194)
at com.android.internal.policy.DecorView.onMeasure(DecorView.java:1248)
at android.view.View.measure(View.java:27124)
at android.view.ViewRootImpl.performMeasure(ViewRootImpl.java:4418)
at android.view.ViewRootImpl.measureHierarchy(ViewRootImpl.java:3123)
at android.view.ViewRootImpl.performTraversals(ViewRootImpl.java:3415)
at android.view.ViewRootImpl.doTraversal(ViewRootImpl.java:2819)
at android.view.ViewRootImpl$TraversalRunnable.run(ViewRootImpl.java:10304)
at android.view.Choreographer$CallbackRecord.run(Choreographer.java:1063)
at android.view.Choreographer.doCallbacks(Choreographer.java:845)
at android.view.Choreographer.doFrame(Choreographer.java:780)
at android.view.Choreographer$FrameDisplayEventReceiver.run(Choreographer.java:1048)
at android.os.Handler.handleCallback(Handler.java:938)
at android.os.Handler.dispatchMessage(Handler.java:99)
at android.os.Looper.loopOnce(Looper.java:226)
at android.os.Looper.loop(Looper.java:313)
at android.app.ActivityThread.main(ActivityThread.java:8582)
at java.lang.reflect.Method.invoke(Native Method)
at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:563)
at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:1133)

异常原因 #

FragmentStateAdapter内部已经实现了Fragment的复用与状态管理逻辑，当你手动缓存Fragment B实例并尝试复用，返回Fragment A时，Adapter会尝试重新将这些Fragment添加到FragmentManager，但它们已经被关联到FragmentManager中，导致触发"Fragment already added"异常。

解决方法 #

1. 依赖FragmentStateAdapter自带的复用机制（推荐） #

FragmentStateAdapter会自动处理Fragment的创建、复用和状态保存，无需手动缓存实例。只需在createFragment方法中按需创建Fragment即可：

class MyPagerAdapter(fragment: Fragment) : FragmentStateAdapter(fragment) {
    private val pageData = listOf("页面1", "页面2", "页面3")

    override fun getItemCount(): Int = pageData.size

    override fun createFragment(position: Int): Fragment {
        // 传递必要参数，按需创建Fragment B
        return FragmentB.newInstance(pageData[position])
    }
}

2. 手动管理缓存时正确清理Fragment关联 #

如果必须手动缓存Fragment实例（比如需要保留特殊状态），需在Fragment A的生命周期中清理缓存Fragment与FragmentManager的关联：

private val cachedFragments = mutableListOf<FragmentB>()

override fun onDestroyView() {
    super.onDestroyView()
    // 移除所有缓存Fragment的关联，避免返回时重复添加
    cachedFragments.forEach { fragment ->
        parentFragmentManager.beginTransaction().remove(fragment).commitNow()
    }
    cachedFragments.clear()
}

同时，在创建Fragment时先检查是否已存在于FragmentManager中：

private fun getFragment(position: Int): FragmentB {
    val tag = "fragment_b_$position"
    val existingFragment = parentFragmentManager.findFragmentByTag(tag) as? FragmentB
    return existingFragment ?: FragmentB.newInstance().apply {
        parentFragmentManager.beginTransaction().add(this, tag).commitNow()
        cachedFragments.add(this)
    }
}

3. 检查导航模式与生命周期 #

• 若使用Navigation Component，确保Fragment A的launchMode未设置为singleInstance等可能导致生命周期异常的模式。
• 导航到其他Fragment时，使用replace而非hide/show，确保Fragment A的onDestroyView被正确调用，避免Fragment实例残留。

内容的提问来源于stack exchange，提问作者Maya