Fragment：模块化容器

// 动态替换 Fragment 的典型操作
// 获取 FragmentManager，它是管理 Fragment 的核心入口
val fragmentManager = supportFragmentManager
 
// 开启一个事务，所有 Fragment 操作必须在事务中进行
fragmentManager.commit {
    // replace() 会先移除容器中已有的 Fragment，再添加新的
    // R.id.fragment_container 是布局中的容器 ID
    replace(R.id.fragment_container, TechNewsFragment())
 
    // 将此事务加入回退栈，用户按返回键可以回到上一个 Fragment
    // "tech_news" 是回退栈记录的名称，可用于后续定位
    addToBackStack("tech_news")
}

// Fragment 的核心特征：拥有生命周期 + 管理视图 + 依附于 Activity
class ArticleFragment : Fragment() {
 
    // Fragment 可以声明自己的布局资源
    // 通过构造函数传入布局 ID 是推荐的简洁写法
    // 等价于在 onCreateView 中手动 inflate
    constructor() : super(R.layout.fragment_article)
 
    // onViewCreated 是操作视图的最佳时机
    // view 参数就是 onCreateView 返回的根视图
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // viewLifecycleOwner 是 Fragment 的 View 生命周期持有者
        // 用它来观察 LiveData 可以避免视图销毁后仍收到数据更新
        // 这是 Fragment 区别于普通 View 的关键能力之一
        viewModel.article.observe(viewLifecycleOwner) { article ->
            // 当数据变化时更新 UI
            bindArticle(article)
        }
    }
}

// Fragment 的 onAttach 回调
// 这是 Fragment 生命周期中最早被调用的方法
override fun onAttach(context: Context) {
    // 必须调用 super，FragmentManager 内部会在此设置 mHost 引用
    super.onAttach(context)
    // 此时 context 就是宿主 Activity
    // 可以安全地进行类型转换来获取 Activity 引用
    // 但更推荐通过 requireActivity() 在需要时获取
    Log.d("Fragment", "onAttach: 已关联到 ${context::class.simpleName}")
    // 典型用途：获取依赖注入的组件、注册监听器等
}

// Fragment 的 onDetach 回调
// 这是 Fragment 生命周期中最后被调用的方法
override fun onDetach() {
    // 在这里清理与 Activity 相关的引用
    // 此回调之后，getActivity() 将返回 null
    // requireActivity() 将抛出 IllegalStateException
    Log.d("Fragment", "onDetach: 已与宿主断开关联")
    super.onDetach()
}

// 创建 Fragment 的视图层级
// inflater: 用于从 XML 膨胀布局的 LayoutInflater
// container: Fragment 将被放入的父 ViewGroup（不要自己 addView）
// savedInstanceState: 如果是重建，包含之前保存的状态
override fun onCreateView(
    inflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?
): View? {
    // inflate 的第三个参数必须传 false
    // 因为 FragmentManager 会负责将 View 添加到 container 中
    // 如果传 true，会导致 View 被添加两次，抛出异常
    return inflater.inflate(R.layout.fragment_example, container, false)
}

// onViewCreated 在 onCreateView 返回非 null View 后立即调用
// 这里是初始化视图组件的最佳位置
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    // 调用 super（虽然默认实现为空，但保持良好习惯）
    super.onViewCreated(view, savedInstanceState)
    // 通过 view 参数查找子控件
    val textView = view.findViewById<TextView>(R.id.tv_title)
    // 设置点击监听器
    textView.setOnClickListener {
        // 处理点击事件
    }
    // 观察 ViewModel 数据
    // 注意：这里使用 viewLifecycleOwner 而不是 this
    // 因为 Fragment 的生命周期比 View 的生命周期更长
    viewModel.data.observe(viewLifecycleOwner) { value ->
        textView.text = value
    }
}

// 当 Fragment 的视图层级被销毁时调用
// 典型场景：Fragment 进入回退栈、被 replace 等
override fun onDestroyView() {
    // 在 super 调用之前清理视图引用
    // 如果你持有了 View 的引用（如 binding），必须在这里置空
    // 否则已销毁的 View 树会因为被 Fragment 实例引用而无法被 GC 回收
    _binding = null
    super.onDestroyView()
}

// Fragment 双生命周期的内存模型示意
// 展示 Fragment 实例与 View 的生命周期差异
 
// Fragment 实例生命周期（长）
// ┌─────────────────────────────────────────────────┐
// │  onCreate ──────────────────────── onDestroy     │
// │     │                                  │         │
// │     │  ┌── View 生命周期（短）──┐      │         │
// │     │  │ onCreateView          │      │         │
// │     │  │ onViewCreated         │      │         │
// │     │  │ onStart               │      │         │
// │     │  │ onResume              │      │         │
// │     │  │ onPause               │      │         │
// │     │  │ onStop                │      │         │
// │     │  │ onDestroyView ────────┘      │         │
// │     │  │                              │         │
// │     │  │  （回退栈中等待...）          │         │
// │     │  │                              │         │
// │     │  ┌── 新 View 生命周期 ───┐      │         │
// │     │  │ onCreateView（再次）  │      │         │
// │     │  │ onViewCreated         │      │         │
// │     │  │ ...                   │      │         │
// │     │  └───────────────────────┘      │         │
// └─────────────────────────────────────────────────┘

// 演示 Activity 与 Fragment 生命周期的调用顺序
// 通过日志可以清晰观察同步机制
 
// === Activity 代码 ===
class HostActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Log.d("Lifecycle", "Activity: onCreate")
        // 设置布局
        setContentView(R.layout.activity_host)
        // 仅在首次创建时添加 Fragment，避免配置变更后重复添加
        if (savedInstanceState == null) {
            supportFragmentManager.beginTransaction()
                // 将 Fragment 添加到容器中
                .add(R.id.fragment_container, ExampleFragment())
                .commit()
        }
    }
 
    override fun onStart() {
        super.onStart()
        // 此时 Fragment 的 onStart 已经被调用（在 super 内部触发）
        Log.d("Lifecycle", "Activity: onStart")
    }
 
    override fun onResume() {
        super.onResume()
        // 此时 Fragment 的 onResume 已经被调用
        Log.d("Lifecycle", "Activity: onResume")
    }
 
    override fun onPause() {
        // 注意：super.onPause() 内部会先触发 Fragment 的 onPause
        Log.d("Lifecycle", "Activity: onPause (before super)")
        super.onPause()
        Log.d("Lifecycle", "Activity: onPause (after super)")
    }
 
    override fun onStop() {
        // super.onStop() 内部会先触发 Fragment 的 onStop
        super.onStop()
        Log.d("Lifecycle", "Activity: onStop")
    }
 
    override fun onDestroy() {
        super.onDestroy()
        Log.d("Lifecycle", "Activity: onDestroy")
    }
}
 
// === Fragment 代码 ===
class ExampleFragment : Fragment() {
    override fun onAttach(context: Context) {
        super.onAttach(context)
        Log.d("Lifecycle", "  Fragment: onAttach")
    }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Log.d("Lifecycle", "  Fragment: onCreate")
    }
 
    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        Log.d("Lifecycle", "  Fragment: onCreateView")
        return inflater.inflate(R.layout.fragment_example, container, false)
    }
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        Log.d("Lifecycle", "  Fragment: onViewCreated")
    }
 
    override fun onStart() {
        super.onStart()
        Log.d("Lifecycle", "  Fragment: onStart")
    }
 
    override fun onResume() {
        super.onResume()
        Log.d("Lifecycle", "  Fragment: onResume")
    }
 
    override fun onPause() {
        super.onPause()
        Log.d("Lifecycle", "  Fragment: onPause")
    }
 
    override fun onStop() {
        super.onStop()
        Log.d("Lifecycle", "  Fragment: onStop")
    }
 
    override fun onDestroyView() {
        super.onDestroyView()
        Log.d("Lifecycle", "  Fragment: onDestroyView")
    }
 
    override fun onDestroy() {
        super.onDestroy()
        Log.d("Lifecycle", "  Fragment: onDestroy")
    }
 
    override fun onDetach() {
        super.onDetach()
        Log.d("Lifecycle", "  Fragment: onDetach")
    }
}

// 在 Activity 中注册全局 Fragment 生命周期监听
// 第二个参数 recursive 表示是否递归监听子 FragmentManager 中的 Fragment
supportFragmentManager.registerFragmentLifecycleCallbacks(
    object : FragmentManager.FragmentLifecycleCallbacks() {
        // 当任何 Fragment 被 attach 时回调
        override fun onFragmentAttached(
            fm: FragmentManager,
            f: Fragment,
            context: Context
        ) {
            Log.d("GlobalCallback", "${f::class.simpleName} attached")
        }
 
        // 当任何 Fragment 的 View 被创建时回调
        override fun onFragmentViewCreated(
            fm: FragmentManager,
            f: Fragment,
            v: View,
            savedInstanceState: Bundle?
        ) {
            Log.d("GlobalCallback", "${f::class.simpleName} view created")
        }
 
        // 当任何 Fragment 被 destroy 时回调
        override fun onFragmentDestroyed(fm: FragmentManager, f: Fragment) {
            Log.d("GlobalCallback", "${f::class.simpleName} destroyed")
        }
    },
    true // recursive = true，递归监听嵌套 Fragment
)

// setMaxLifecycle 的使用示例
// 场景：手动管理两个 Fragment 的可见性
supportFragmentManager.beginTransaction()
    // 添加 FragmentA，但限制其最大生命周期为 STARTED
    // 这意味着 FragmentA 的 onResume() 不会被调用
    .add(R.id.container, fragmentA)
    .setMaxLifecycle(fragmentA, Lifecycle.State.STARTED)
    // 添加 FragmentB，允许其进入 RESUMED（完全可见）
    .add(R.id.container, fragmentB)
    .setMaxLifecycle(fragmentB, Lifecycle.State.RESUMED)
    .commit()
 
// 当需要切换可见 Fragment 时
supportFragmentManager.beginTransaction()
    // 将 FragmentA 提升到 RESUMED（变为可见）
    .setMaxLifecycle(fragmentA, Lifecycle.State.RESUMED)
    // 将 FragmentB 降级到 STARTED（变为不可见但仍存活）
    .setMaxLifecycle(fragmentB, Lifecycle.State.STARTED)
    .commit()

// 错误示范：使用带参构造函数
// 配置变更后系统无法通过反射重建，会崩溃
class BadFragment(private val userId: String) : Fragment()
 
// 正确做法：使用 companion object + newInstance 工厂方法
class GoodFragment : Fragment() {
    companion object {
        // 参数 key 常量
        private const val ARG_USER_ID = "arg_user_id"
 
        // 工厂方法：创建 Fragment 实例并通过 arguments 传参
        fun newInstance(userId: String): GoodFragment {
            return GoodFragment().apply {
                // arguments 会被 FragmentManager 自动保存和恢复
                arguments = Bundle().apply {
                    putString(ARG_USER_ID, userId)
                }
            }
        }
    }
 
    // 在 onCreate 中安全地读取参数
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // requireArguments() 确保 arguments 不为 null
        val userId = requireArguments().getString(ARG_USER_ID)
    }
}

// 正确使用 viewLifecycleOwner 的示例
class UserProfileFragment : Fragment(R.layout.fragment_user_profile) {
 
    // 通过 activityViewModels 或 viewModels 获取 ViewModel
    private val viewModel: UserProfileViewModel by viewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // ✅ 正确：使用 viewLifecycleOwner 观察 UI 相关数据
        // 当 View 被销毁时（如进入回退栈），观察会自动取消
        // 当 View 重建时，在新的 onViewCreated 中重新注册观察
        viewModel.userName.observe(viewLifecycleOwner) { name ->
            view.findViewById<TextView>(R.id.tv_name).text = name
        }
 
        // ✅ 正确：使用 repeatOnLifecycle 收集 Flow
        // viewLifecycleOwner.lifecycleScope 确保协程跟随 View 生命周期
        viewLifecycleOwner.lifecycleScope.launch {
            // repeatOnLifecycle 在 STARTED 时启动收集，STOPPED 时取消
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.uiState.collect { state ->
                    // 更新 UI
                    updateUI(state)
                }
            }
        }
 
        // ❌ 错误：使用 this（Fragment 自身）作为 LifecycleOwner
        // 如果 Fragment 进入回退栈后 View 被销毁，
        // 但 Fragment 实例仍存活，观察不会取消
        // 当 LiveData 发射新值时，会尝试更新已销毁的 View，导致崩溃
        // viewModel.userName.observe(this) { name ->
        //     view.findViewById<TextView>(R.id.tv_name).text = name
        // }
    }
}

// ViewBinding 在 Fragment 中的标准用法
class StandardFragment : Fragment(R.layout.fragment_standard) {
 
    // backing field 使用 nullable 类型
    private var _binding: FragmentStandardBinding? = null
    // 对外暴露非空属性，仅在 View 存活期间使用
    // 通过 !! 断言，如果在错误的时机访问会立即崩溃（fail-fast）
    private val binding get() = _binding!!
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        // 绑定 View
        _binding = FragmentStandardBinding.bind(view)
        // 安全地使用 binding
        binding.tvTitle.text = "Hello"
    }
 
    override fun onDestroyView() {
        // 必须在 super 之前置空，释放对 View 树的引用
        _binding = null
        super.onDestroyView()
    }
}

// 在 Activity 中查找当前容器内的 Fragment
// findFragmentById 的参数是容器的 ID，不是 Fragment 的布局 ID
val currentFragment = supportFragmentManager
    .findFragmentById(R.id.fragment_container)  // 返回该容器中最后添加的 Fragment
 
// 需要进行类型判断和安全转换
if (currentFragment is HomeFragment) {
    // 当前显示的是 HomeFragment，可以安全调用其方法
    currentFragment.refreshData()
}

// 添加 Fragment 时指定 tag
supportFragmentManager.beginTransaction()
    .add(R.id.fragment_container, HomeFragment(), "HOME")  // "HOME" 就是 tag
    .commit()
 
// 之后在任何地方通过 tag 查找
val homeFragment = supportFragmentManager
    .findFragmentByTag("HOME")  // 根据 tag 精确查找，不依赖容器 ID
 
// tag 查找的一个经典用途：防止重复添加
// 比如屏幕旋转后 Activity 重建，Fragment 会被系统自动恢复
// 如果不检查就再次 add，会导致重复叠加
if (supportFragmentManager.findFragmentByTag("HOME") == null) {
    // 只有在找不到时才添加，避免重复
    supportFragmentManager.beginTransaction()
        .add(R.id.fragment_container, HomeFragment(), "HOME")
        .commit()
}

// 演示异步 commit 的"延迟生效"问题
supportFragmentManager.beginTransaction()
    .add(R.id.container, MyFragment(), "MY_TAG")
    .commit()  // 事务被投递到 Handler 消息队列，但尚未执行
 
// ⚠️ 此时立即查找，返回 null！因为事务还在队列中等待
val fragment = supportFragmentManager.findFragmentByTag("MY_TAG")
// fragment == null  ← 这不是 Bug，是异步调度的正常行为

supportFragmentManager.beginTransaction()
    .add(R.id.container, MyFragment(), "MY_TAG")
    .commit()  // 投递到队列
 
// 强制立即执行所有待处理事务
supportFragmentManager.executePendingTransactions()
 
// 现在可以安全查找了
val fragment = supportFragmentManager.findFragmentByTag("MY_TAG")
// fragment != null ✓

supportFragmentManager.beginTransaction()
    .replace(R.id.container, DetailFragment())  // 用 DetailFragment 替换当前内容
    .addToBackStack("detail")  // 将这个事务压入回退栈，name 可以为 null
    .commit()
 
// 当用户按返回键时，FragmentManager 会自动：
// 1. 弹出栈顶事务（即这个 replace 操作）
// 2. 反向执行：移除 DetailFragment，恢复之前被替换掉的 Fragment

// 回退栈的弹出操作
// 方式一：弹出栈顶的一个事务（等同于用户按返回键的效果）
supportFragmentManager.popBackStack()
 
// 方式二：弹出到指定 name 的事务（包含该事务本身）
// flag = FragmentManager.POP_BACK_STACK_INCLUSIVE 表示连 name 对应的事务也一起弹出
supportFragmentManager.popBackStack("detail", FragmentManager.POP_BACK_STACK_INCLUSIVE)
 
// 方式三：弹出到指定 name 的事务（不包含该事务本身）
// flag = 0 表示弹出 "detail" 之上的所有事务，但保留 "detail" 本身
supportFragmentManager.popBackStack("detail", 0)
 
// 方式四：清空整个回退栈
// 传入 null 和 INCLUSIVE 标志，会弹出所有事务
supportFragmentManager.popBackStack(null, FragmentManager.POP_BACK_STACK_INCLUSIVE)

// 场景对比：replace vs add 配合回退栈
 
// 场景 1：replace + addToBackStack
// 假设当前容器中有 FragmentA
supportFragmentManager.beginTransaction()
    .replace(R.id.container, FragmentB())  // 移除 A 的视图，添加 B
    .addToBackStack(null)
    .commit()
// FragmentA 的生命周期：onPause → onStop → onDestroyView（视图销毁，但实例保留）
// FragmentB 的生命周期：onAttach → onCreate → onCreateView → onStart → onResume
// 按返回键弹出后：
// FragmentB：onPause → onStop → onDestroyView → onDestroy → onDetach（完全销毁）
// FragmentA：onCreateView → onStart → onResume（视图重建，实例复用）
 
// 场景 2：add + addToBackStack
// 假设当前容器中有 FragmentA
supportFragmentManager.beginTransaction()
    .add(R.id.container, FragmentB())  // B 叠加在 A 之上
    .addToBackStack(null)
    .commit()
// FragmentA 的生命周期：无变化！A 仍然处于 RESUMED 状态
// FragmentB 的生命周期：onAttach → onCreate → onCreateView → onStart → onResume
// 按返回键弹出后：
// FragmentB：完全销毁
// FragmentA：无变化（它一直都在）

// 监听回退栈变化，常用于根据栈深度更新 UI（如显示/隐藏返回按钮）
supportFragmentManager.addOnBackStackChangedListener {
    // 每当回退栈发生变化（push 或 pop）时回调
    val stackDepth = supportFragmentManager.backStackEntryCount  // 当前栈深度
    
    // 典型用法：栈为空时隐藏 Toolbar 的返回箭头
    val showBackButton = stackDepth > 0
    supportActionBar?.setDisplayHomeAsUpEnabled(showBackButton)
    
    // 也可以遍历栈中的条目获取详细信息
    for (i in 0 until stackDepth) {
        val entry = supportFragmentManager.getBackStackEntryAt(i)
        // entry.name 就是 addToBackStack 时传入的 name
        // entry.id 是系统分配的唯一 ID
        Log.d("BackStack", "Entry $i: name=${entry.name}, id=${entry.id}")
    }
}

// Fragment 内部状态常量（源码中的定义）
// 这些状态值是递增的整数，FragmentManager 通过比较当前状态和目标状态来决定前进还是后退
 
// static final int INITIALIZING = -1   // Fragment 刚被实例化，尚未 attach
// static final int ATTACHED = 0        // 已 attach 到 Activity，但 onCreate 未调用
// static final int CREATED = 1         // onCreate 已调用
// static final int VIEW_CREATED = 2    // onCreateView + onViewCreated 已调用（Jetpack 新增）
// static final int AWAITING_EXIT_EFFECTS = 3  // 等待退出动画完成
// static final int ACTIVITY_CREATED = 4 // onActivityCreated 已调用（已废弃但仍在状态机中）
// static final int STARTED = 5         // onStart 已调用，Fragment 可见
// static final int AWAITING_ENTER_EFFECTS = 6 // 等待进入动画完成
// static final int RESUMED = 7         // onResume 已调用，Fragment 可交互

// ① 获取当前所有已添加的 Fragment 列表
val allFragments: List<Fragment> = supportFragmentManager.fragments
// 注意：这个列表包含所有通过 add 添加的 Fragment（包括 hide 状态的）
// 但不包含已经被 remove 且不在回退栈中的 Fragment
 
// ② 判断当前是否有待执行的事务
// isStateSaved 返回 true 表示 Activity 已经执行了 onSaveInstanceState
// 此时再 commit 会抛出 IllegalStateException
val isSaved: Boolean = supportFragmentManager.isStateSaved
 
// ③ 注册 FragmentLifecycleCallbacks 监听所有 Fragment 的生命周期
// 这是一个非常强大的调试和监控工具
supportFragmentManager.registerFragmentLifecycleCallbacks(
    object : FragmentManager.FragmentLifecycleCallbacks() {
        // recursive = true 表示也监听子 FragmentManager 中的 Fragment
        override fun onFragmentCreated(
            fm: FragmentManager,
            f: Fragment,
            savedInstanceState: Bundle?
        ) {
            // 任何 Fragment 的 onCreate 被调用时都会触发
            Log.d("FragmentMonitor", "${f::class.simpleName} created")
        }
 
        override fun onFragmentResumed(fm: FragmentManager, f: Fragment) {
            Log.d("FragmentMonitor", "${f::class.simpleName} resumed")
        }
 
        override fun onFragmentDestroyed(fm: FragmentManager, f: Fragment) {
            Log.d("FragmentMonitor", "${f::class.simpleName} destroyed")
        }
    },
    true  // recursive: 是否递归监听子 Fragment
)
 
// ④ 设置 FragmentFactory（自定义 Fragment 实例化方式）
// 默认情况下 FragmentManager 通过反射调用无参构造函数来创建 Fragment
// 通过 FragmentFactory 可以实现依赖注入
supportFragmentManager.fragmentFactory = object : FragmentFactory() {
    override fun instantiate(classLoader: ClassLoader, className: String): Fragment {
        // 根据类名返回自定义构造的 Fragment 实例
        return when (className) {
            HomeFragment::class.java.name -> HomeFragment(repository)  // 注入依赖
            else -> super.instantiate(classLoader, className)  // 其他走默认逻辑
        }
    }
}

// ❌ 错误示范：在异步回调中直接 commit，可能此时 Activity 已经 onSaveInstanceState
fun onDataLoaded(data: Data) {
    // 如果这个回调在 Activity onStop 之后才到达，commit 会崩溃
    supportFragmentManager.beginTransaction()
        .replace(R.id.container, ResultFragment())
        .commit()  // 💥 IllegalStateException
}
 
// ✅ 方案一：使用 commitAllowingStateLoss()
// 允许状态丢失，不会抛异常，但事务可能在恢复时丢失
fun onDataLoaded(data: Data) {
    supportFragmentManager.beginTransaction()
        .replace(R.id.container, ResultFragment())
        .commitAllowingStateLoss()  // 不会崩溃，但有状态丢失风险
}
 
// ✅ 方案二（推荐）：检查生命周期状态，确保在安全时机执行
fun onDataLoaded(data: Data) {
    // 利用 Lifecycle 确保只在 STARTED 之后执行
    if (lifecycle.currentState.isAtLeast(Lifecycle.State.STARTED)) {
        supportFragmentManager.beginTransaction()
            .replace(R.id.container, ResultFragment())
            .commit()
    }
}
 
// ✅ 方案三（最佳）：结合 LifecycleOwner 自动调度
// 使用 lifecycleScope 确保协程在生命周期安全时执行
lifecycleScope.launchWhenStarted {
    val data = repository.loadData()  // 挂起等待数据
    // 恢复时一定处于 STARTED 之后，commit 安全
    supportFragmentManager.beginTransaction()
        .replace(R.id.container, ResultFragment())
        .commit()
}

// ❌ 错误示范：每次 onCreate 都无条件添加
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    
    // 屏幕旋转后，系统已经恢复了之前的 HomeFragment
    // 这里又添加了一个新的，导致重叠
    supportFragmentManager.beginTransaction()
        .add(R.id.container, HomeFragment(), "HOME")
        .commit()
}
 
// ✅ 正确做法：检查 savedInstanceState 或使用 findFragmentByTag
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    
    // 方式一：savedInstanceState 为 null 说明是首次创建，不是恢复
    if (savedInstanceState == null) {
        supportFragmentManager.beginTransaction()
            .add(R.id.container, HomeFragment(), "HOME")
            .commit()
    }
    // 如果是恢复（savedInstanceState != null），系统已经自动恢复了 Fragment，无需再添加
    
    // 方式二：通过 tag 检查是否已存在
    if (supportFragmentManager.findFragmentByTag("HOME") == null) {
        supportFragmentManager.beginTransaction()
            .add(R.id.container, HomeFragment(), "HOME")
            .commit()
    }
}

// 在子 Fragment 中想要"返回上一页"
class DetailChildFragment : Fragment() {
    
    fun navigateBack() {
        // ❌ 错误：childFragmentManager 管理的是自己内部的子 Fragment
        // 弹它的栈不会影响自己在父级中的位置
        childFragmentManager.popBackStack()
        
        // ✅ 正确：parentFragmentManager 是管理自己的那个 FragmentManager
        // 弹它的栈才能把自己从父级中移除
        parentFragmentManager.popBackStack()
    }
}

// 事务 1
supportFragmentManager.beginTransaction()
    .add(R.id.container, FragmentA(), "A")
    .addToBackStack("first")
    .commit()
 
// 事务 2
supportFragmentManager.beginTransaction()
    .replace(R.id.container, FragmentB(), "B")
    .addToBackStack("second")
    .commit()

// 方式一：add —— FragmentA 的视图和状态完全不受影响
// FragmentA 仍然处于 RESUMED 状态，视图仍在容器中
supportFragmentManager.beginTransaction()
    .add(R.id.container, FragmentB())  // 在容器中叠加 FragmentB
    .addToBackStack(null)              // 加入回退栈，按返回键可移除 FragmentB
    .commit()                          // 异步提交事务
 
// 方式二：replace —— FragmentA 会被移除
// 如果加了 addToBackStack，FragmentA 走到 onDestroyView（视图销毁，实例保留）
// 如果没加 addToBackStack，FragmentA 走到 onDetach（彻底销毁）
supportFragmentManager.beginTransaction()
    .replace(R.id.container, FragmentB())  // 移除容器中所有 Fragment，再添加 FragmentB
    .addToBackStack(null)                  // 加入回退栈
    .commit()                              // 异步提交事务

// 典型的底部导航 Tab 切换实现
class MainActivity : AppCompatActivity() {
 
    // 持有所有 Tab 对应的 Fragment 引用
    private val homeFragment = HomeFragment()
    private val searchFragment = SearchFragment()
    private val profileFragment = ProfileFragment()
    private var activeFragment: Fragment = homeFragment  // 记录当前显示的 Fragment
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
 
        // 初始化：将所有 Fragment 都 add 到容器中，但只 show 第一个
        supportFragmentManager.beginTransaction()
            .add(R.id.container, profileFragment, "profile")   // 添加 profileFragment（隐藏）
            .hide(profileFragment)                              // 立即隐藏
            .add(R.id.container, searchFragment, "search")     // 添加 searchFragment（隐藏）
            .hide(searchFragment)                               // 立即隐藏
            .add(R.id.container, homeFragment, "home")         // 添加 homeFragment（显示）
            .commit()                                           // 提交事务
 
        // 底部导航点击事件
        bottomNav.setOnItemSelectedListener { item ->
            val targetFragment = when (item.itemId) {
                R.id.nav_home -> homeFragment
                R.id.nav_search -> searchFragment
                R.id.nav_profile -> profileFragment
                else -> homeFragment
            }
            switchTab(targetFragment)  // 切换到目标 Tab
            true
        }
    }
 
    // 切换 Tab：隐藏当前 Fragment，显示目标 Fragment
    private fun switchTab(target: Fragment) {
        if (target == activeFragment) return  // 如果目标就是当前显示的，直接返回
        supportFragmentManager.beginTransaction()
            .hide(activeFragment)   // 隐藏当前 Fragment（设置 View.GONE）
            .show(target)           // 显示目标 Fragment（设置 View.VISIBLE）
            .commit()               // 提交事务
        activeFragment = target     // 更新当前活跃 Fragment 的引用
    }
}

class HomeFragment : Fragment() {
 
    // 当 Fragment 的 hidden 状态发生变化时回调
    // 注意：首次 add 时如果没有 hide，这个方法不会被调用
    override fun onHiddenChanged(hidden: Boolean) {
        super.onHiddenChanged(hidden)
        if (hidden) {
            // Fragment 被隐藏了，可以暂停一些不必要的操作
            // 比如暂停视频播放、停止位置更新等
        } else {
            // Fragment 重新可见了，可以恢复操作
            // 比如刷新数据、恢复播放等
        }
    }
}

val fm = supportFragmentManager
 
// ① commit()：异步提交，最常用
// 事务会被 post 到主线程消息队列，稍后执行
fm.beginTransaction()
    .replace(R.id.container, DetailFragment())
    .addToBackStack("detail")   // 可以配合回退栈使用
    .commit()                   // 异步提交
 
// 注意：此时事务尚未执行，findFragmentByTag 可能返回 null
// 如果需要立即执行，可以调用 executePendingTransactions()
fm.executePendingTransactions()  // 强制立即执行所有待处理的异步事务
 
// ② commitNow()：同步提交，立即执行
// 适用于需要立即获取 Fragment 引用的场景
fm.beginTransaction()
    .add(R.id.container, LoadingFragment(), "loading")
    // .addToBackStack(null)    // ❌ 不能与 commitNow 一起使用！
    .commitNow()                // 同步执行，方法返回时事务已完成
 
// 此时可以安全地获取 Fragment
val loading = fm.findFragmentByTag("loading")  // 一定不为 null
 
// ③ commitAllowingStateLoss()：异步提交，允许状态丢失
// 适用于 onSaveInstanceState 之后仍需提交事务的场景
fm.beginTransaction()
    .replace(R.id.container, ToastFragment())
    .commitAllowingStateLoss()  // 不会抛异常，但状态可能丢失

// 良好实践：设置有意义的 tag 和回退栈名称
supportFragmentManager.beginTransaction()
    .replace(
        R.id.container,                    // 容器 ID
        DetailFragment.newInstance(itemId), // 使用工厂方法创建 Fragment
        "detail_fragment"                  // Fragment tag，便于后续查找
    )
    .addToBackStack("detail")              // 回退栈条目名称，便于精确回退
    .setReorderingAllowed(true)            // 允许事务重排序优化（推荐始终开启）
    .commit()

supportFragmentManager.beginTransaction()
    .replace(R.id.container, FragmentB())
    .addToBackStack("b")
    .commit()

<!-- activity_main.xml -->
<!-- 静态声明一个 Fragment，编译期就确定了类型 -->
<fragment
    android:id="@+id/fragment_static"
    android:name="com.example.MyFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

// Activity 中的典型代码
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 当这行执行时，XML 中的 <fragment> 就会被 FragmentManager 实例化
        // 并且该 Fragment 的 onAttach → onCreate → onCreateView → onViewCreated 会在此期间完成
        setContentView(R.layout.activity_main)
        // 此时静态 Fragment 已经存在于 FragmentManager 中，可以通过 findFragmentById 获取
        val fragment = supportFragmentManager.findFragmentById(R.id.fragment_static)
        // fragment 不为 null，且其 view 已经创建完毕
    }
}

<!-- 方式一：在 XML 中指定初始 Fragment（推荐的"类静态"写法） -->
<!-- 注意：这里用的是 android:name 属性，和旧的 <fragment> 标签看起来类似 -->
<!-- 但底层机制完全不同 -->
<androidx.fragment.app.FragmentContainerView
    android:id="@+id/fragment_container"
    android:name="com.example.MyFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:tag="my_fragment_tag" />

<!-- 方式二：纯容器，不指定初始 Fragment，完全由代码控制 -->
<!-- 这是最灵活的用法，适合需要根据条件动态决定显示哪个 Fragment 的场景 -->
<androidx.fragment.app.FragmentContainerView
    android:id="@+id/fragment_container"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

// 使用方式二：在代码中动态添加 Fragment 到 FragmentContainerView
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
 
        // 关键检查：只在首次创建时添加 Fragment
        // 如果 savedInstanceState 不为 null，说明是配置变更后的重建
        // FragmentManager 会自动恢复之前的 Fragment，无需重复添加
        if (savedInstanceState == null) {
            supportFragmentManager.commit {
                // setReorderingAllowed 优化事务执行顺序，推荐始终开启
                setReorderingAllowed(true)
                // 将 MyFragment 添加到 FragmentContainerView 容器中
                add<MyFragment>(R.id.fragment_container)
            }
        }
    }
}

// FragmentContainerView 源码中的关键逻辑（简化）
class FragmentContainerView : FrameLayout {
 
    // 重写 addView，禁止外部直接添加 View
    override fun addView(child: View, index: Int, params: LayoutParams) {
        // 只有 FragmentManager 在执行事务时才会通过内部方法添加 View
        // 外部调用会检查标志位，如果不是来自 FragmentManager 则抛异常
        if (FragmentManager.isFragmentManagerAdding) {
            super.addView(child, index, params)  // 允许 FragmentManager 的内部调用
        } else {
            throw UnsupportedOperationException(
                "FragmentContainerView 不支持直接添加 View，请使用 FragmentTransaction"
            )
        }
    }
 
    // 重写 Insets 分发，确保所有子 View 都能收到
    override fun dispatchApplyWindowInsets(insets: WindowInsets): WindowInsets {
        for (i in 0 until childCount) {
            // 每个子 View 都收到原始的、未被消费的 insets 副本
            getChildAt(i).dispatchApplyWindowInsets(WindowInsets(insets))
        }
        return insets  // 返回原始 insets，不标记为已消费
    }
}

<!-- 迁移前：旧写法 -->
<fragment
    android:id="@+id/nav_host"
    android:name="androidx.navigation.fragment.NavHostFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:navGraph="@navigation/nav_graph"
    app:defaultNavHost="true" />

<!-- 迁移后：新写法 -->
<!-- 只需将标签名从 fragment 改为 FragmentContainerView 的全限定名 -->
<!-- 其余属性（id、name、自定义属性）保持不变 -->
<androidx.fragment.app.FragmentContainerView
    android:id="@+id/nav_host"
    android:name="androidx.navigation.fragment.NavHostFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:navGraph="@navigation/nav_graph"
    app:defaultNavHost="true" />

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
 
        // 方案一：强制执行挂起事务（简单但不够优雅）
        // 调用后，FragmentContainerView 中通过 android:name 指定的 Fragment 会立即可用
        supportFragmentManager.executePendingTransactions()
        // 此时 findFragmentById 可以安全返回非 null
        val navHost = supportFragmentManager.findFragmentById(R.id.nav_host)
 
        // 方案二：注册生命周期回调（更健壮的做法）
        supportFragmentManager.registerFragmentLifecycleCallbacks(
            object : FragmentManager.FragmentLifecycleCallbacks() {
                // 当任何 Fragment 的 View 创建完成时回调
                override fun onFragmentViewCreated(
                    fm: FragmentManager,
                    f: Fragment,
                    v: View,
                    savedInstanceState: Bundle?
                ) {
                    // 在这里安全地与 Fragment 交互
                    if (f is NavHostFragment) {
                        // NavHostFragment 已就绪，可以进行导航相关操作
                    }
                }
            },
            false  // false 表示不递归监听子 FragmentManager
        )
    }
}

// SharedProductViewModel.kt
// 共享 ViewModel，作用域绑定到宿主 Activity
class SharedProductViewModel : ViewModel() {
 
    // 内部可变的 LiveData，仅 ViewModel 自身可写
    private val _selectedProduct = MutableLiveData<Product>()
 
    // 对外暴露不可变的 LiveData，Fragment 只能读和观察
    val selectedProduct: LiveData<Product> = _selectedProduct
 
    // 由列表页调用，设置当前选中的商品
    fun selectProduct(product: Product) {
        _selectedProduct.value = product
    }
}

// ProductListFragment.kt
class ProductListFragment : Fragment() {
 
    // 关键：by activityViewModels() 委托从宿主 Activity 的 ViewModelStore 获取实例
    // 这确保了与 DetailFragment 拿到的是同一个 ViewModel 对象
    private val sharedViewModel: SharedProductViewModel by activityViewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 用户点击列表项时，通过 ViewModel 传递选中的商品
        adapter.onItemClick = { product ->
            // 写入共享 ViewModel，DetailFragment 会自动收到通知
            sharedViewModel.selectProduct(product)
        }
    }
}

// ProductDetailFragment.kt
class ProductDetailFragment : Fragment() {
 
    // 同样从宿主 Activity 的 ViewModelStore 获取，拿到的是同一个实例
    private val sharedViewModel: SharedProductViewModel by activityViewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 观察共享数据，一旦 ListFragment 调用了 selectProduct()，这里立即回调
        // viewLifecycleOwner 确保只在视图存活期间接收更新，避免内存泄漏
        sharedViewModel.selectedProduct.observe(viewLifecycleOwner) { product ->
            // 更新详情页 UI
            binding.productName.text = product.name
            binding.productPrice.text = product.price.toString()
        }
    }
}

// FilterFragment.kt — 发送方（筛选页）
class FilterFragment : Fragment() {
 
    // 用户点击"应用筛选"按钮时调用
    private fun applyFilter() {
        // 构建结果 Bundle
        val result = bundleOf(
            "category" to selectedCategory,   // 选中的分类
            "price_range" to selectedRange     // 选中的价格区间
        )
        // 通过 parentFragmentManager 发送结果
        // "filter_request" 是约定的 key，接收方必须用同一个 key 注册监听
        parentFragmentManager.setFragmentResult("filter_request", result)
 
        // 发送完结果后关闭自身（回退到上一个 Fragment）
        parentFragmentManager.popBackStack()
    }
}

// ProductListFragment.kt — 接收方（商品列表页）
class ProductListFragment : Fragment() {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 在 parentFragmentManager 上注册监听器
        // viewLifecycleOwner 确保监听器在视图销毁时自动移除，防止泄漏
        parentFragmentManager.setFragmentResultListener(
            "filter_request",        // 与发送方约定的 key
            viewLifecycleOwner       // 生命周期所有者，控制回调时机
        ) { requestKey, bundle ->
            // 从 Bundle 中提取结果
            val category = bundle.getString("category")
            val priceRange = bundle.getString("price_range")
            // 根据筛选条件刷新列表
            viewModel.applyFilter(category, priceRange)
        }
    }
}

// ConfirmDialogFragment.kt — 子 Fragment（确认弹窗）
class ConfirmDialogFragment : DialogFragment() {
 
    private fun onConfirmClicked() {
        val result = bundleOf("confirmed" to true)
        // 子 Fragment 的 parentFragmentManager 就是父 Fragment 的 childFragmentManager
        parentFragmentManager.setFragmentResult("confirm_request", result)
        dismiss()
    }
 
    private fun onCancelClicked() {
        val result = bundleOf("confirmed" to false)
        parentFragmentManager.setFragmentResult("confirm_request", result)
        dismiss()
    }
}

// OrderFragment.kt — 父 Fragment
class OrderFragment : Fragment() {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 注意：这里用 childFragmentManager 注册监听，因为弹窗是子 Fragment
        childFragmentManager.setFragmentResultListener(
            "confirm_request",
            viewLifecycleOwner
        ) { _, bundle ->
            val confirmed = bundle.getBoolean("confirmed")
            if (confirmed) {
                // 用户确认，提交订单
                viewModel.submitOrder()
            }
        }
 
        // 点击按钮弹出确认弹窗
        binding.submitButton.setOnClickListener {
            ConfirmDialogFragment().show(childFragmentManager, "confirm_dialog")
        }
    }
}

// ArticleListFragment.kt
class ArticleListFragment : Fragment() {
 
    // 第一步：定义接口，声明 Fragment 需要宿主提供的能力
    // 接口名通常以 Listener/Callback 结尾
    interface OnArticleSelectedListener {
        // 当用户选中某篇文章时调用
        fun onArticleSelected(articleId: Long)
    }
 
    // 持有接口引用，初始为 null
    private var listener: OnArticleSelectedListener? = null
 
    // 第二步：在 onAttach 中获取接口实现
    // onAttach 是 Fragment 与 Activity 建立关联的最早时机
    override fun onAttach(context: Context) {
        super.onAttach(context)
        // 检查宿主 Activity 是否实现了接口
        listener = context as? OnArticleSelectedListener
            ?: throw ClassCastException(
                "${context::class.java.simpleName} must implement OnArticleSelectedListener"
            )
    }
 
    // 第三步：在合适的时机通过接口回调通知宿主
    private fun onItemClicked(articleId: Long) {
        // 安全调用，避免 onDetach 后的空指针
        listener?.onArticleSelected(articleId)
    }
 
    // 第四步：在 onDetach 中释放引用，防止内存泄漏
    override fun onDetach() {
        super.onDetach()
        // 切断对 Activity 的引用
        listener = null
    }
}

// MainActivity.kt
class MainActivity : AppCompatActivity(), ArticleListFragment.OnArticleSelectedListener {
 
    // 实现接口方法，处理 Fragment 传来的事件
    override fun onArticleSelected(articleId: Long) {
        // 收到文章 ID 后，可以启动详情 Fragment 或传递给其他 Fragment
        val detailFragment = ArticleDetailFragment.newInstance(articleId)
        supportFragmentManager.beginTransaction()
            .replace(R.id.fragment_container, detailFragment)
            .addToBackStack(null)
            .commit()
    }
}

// FragmentManager 的层级树结构示意
// Activity.supportFragmentManager          ← 根管理器
//   ├── FragmentA                          ← 由 supportFragmentManager 管理
//   │     └── FragmentA.childFragmentManager  ← A 的子管理器
//   │           ├── ChildFragment1         ← 由 A 的 childFragmentManager 管理
//   │           └── ChildFragment2         ← 由 A 的 childFragmentManager 管理
//   └── FragmentB                          ← 由 supportFragmentManager 管理

class ParentFragment : Fragment(R.layout.fragment_parent) {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // childFragmentManager：管理当前 Fragment 内部的子 Fragment
        // 当你要在这个 Fragment 的布局中添加子 Fragment 时，必须使用它
        val childFm: FragmentManager = childFragmentManager
 
        // parentFragmentManager：管理当前 Fragment 自身的那个 FragmentManager
        // 如果当前 Fragment 是直接添加到 Activity 的，它就等于 Activity.supportFragmentManager
        // 如果当前 Fragment 是某个父 Fragment 的子 Fragment，它就等于父 Fragment 的 childFragmentManager
        val parentFm: FragmentManager = parentFragmentManager
 
        // 在父 Fragment 的布局中添加一个子 Fragment
        // 注意：这里必须用 childFragmentManager，而不是 activity 的 supportFragmentManager
        if (savedInstanceState == null) {
            childFm.commit {
                // R.id.child_container 是 fragment_parent.xml 中的 FragmentContainerView
                replace(R.id.child_container, ChildFragment())
            }
        }
    }
}

class ParentFragment : Fragment(R.layout.fragment_parent) {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // childFragmentManager 拥有独立的回退栈
        childFragmentManager.commit {
            replace(R.id.child_container, FirstChildFragment())
            // 这条记录被压入 childFragmentManager 自己的回退栈
            // 与 Activity 或父 Fragment 的回退栈完全隔离
            addToBackStack("first_child")
        }
    }
 
    // 如果需要手动拦截返回键（通常配合 OnBackPressedDispatcher 使用）
    // 可以先检查子回退栈是否有内容需要弹出
    fun handleBackPress(): Boolean {
        // 检查 childFragmentManager 的回退栈是否非空
        if (childFragmentManager.backStackEntryCount > 0) {
            // 弹出子回退栈的最顶层事务
            childFragmentManager.popBackStack()
            return true // 表示已消费该返回事件
        }
        return false // 未消费，交给上层处理
    }
}

class ChildFragment : Fragment(R.layout.fragment_child) {
 
    override fun onAttach(context: Context) {
        super.onAttach(context)
        // ✅ 安全：可以通过 parentFragment 获取父 Fragment 的引用
        val parent = parentFragment
        // ⚠️ 不安全：父 Fragment 的 View 可能尚未创建完成
        // 尤其在 XML 静态声明子 Fragment 的场景下
        // val parentView = parentFragment?.view  // 可能为 null
    }
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        // ✅ 安全：此时父 Fragment 的 View 已经创建完成
        // 但仍然建议通过 ViewModel 或 FragmentResultListener 通信
        // 而不是直接操作父 Fragment 的 View
    }
}

class ParentFragment : Fragment(R.layout.fragment_parent) {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        val viewPager = view.findViewById<ViewPager2>(R.id.view_pager)
 
        // ✅ 正确：传入 this（当前 Fragment），Adapter 内部会使用 childFragmentManager
        // 页面 Fragment 的生命周期将正确跟随 ParentFragment
        viewPager.adapter = MyPagerAdapter(this)
 
        // ❌ 错误：传入 requireActivity()，Adapter 会使用 Activity 的 supportFragmentManager
        // 页面 Fragment 的生命周期脱离 ParentFragment 的控制
        // viewPager.adapter = MyPagerAdapter(requireActivity())
    }
}
 
class MyPagerAdapter(
    fragment: Fragment  // 接收父 Fragment 作为参数
) : FragmentStateAdapter(fragment) {
 
    // 定义页面总数
    override fun getItemCount(): Int = 3
 
    // 根据位置创建对应的页面 Fragment
    // FragmentStateAdapter 内部会通过 childFragmentManager 管理这些 Fragment
    override fun createFragment(position: Int): Fragment {
        return when (position) {
            0 -> FirstPageFragment()   // 第一个页面
            1 -> SecondPageFragment()  // 第二个页面
            2 -> ThirdPageFragment()   // 第三个页面
            else -> throw IllegalArgumentException("Invalid position: $position")
        }
    }
}

class ParentFragment : Fragment(R.layout.fragment_parent) {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        val viewPager = view.findViewById<ViewPager2>(R.id.view_pager)
        viewPager.adapter = MyPagerAdapter(this)
 
        // offscreenPageLimit 控制离屏页面的保留数量
        // 默认值 OFFSCREEN_PAGE_LIMIT_DEFAULT (-1)：由 RecyclerView 自行管理
        // 设为 1：当前页面左右各保留 1 个页面的 View 不被销毁
        // 设为 2：当前页面左右各保留 2 个页面
        viewPager.offscreenPageLimit = 1
 
        // 配合 TabLayout 使用（常见组合）
        val tabLayout = view.findViewById<TabLayout>(R.id.tab_layout)
        TabLayoutMediator(tabLayout, viewPager) { tab, position ->
            // 为每个 Tab 设置标题文本
            tab.text = when (position) {
                0 -> "首页"
                1 -> "发现"
                2 -> "我的"
                else -> ""
            }
        }.attach() // 调用 attach() 建立 TabLayout 与 ViewPager2 的联动
    }
}

class PageFragment : Fragment(R.layout.fragment_page) {
 
    override fun onResume() {
        super.onResume()
        // ✅ 在 ViewPager2 + FragmentStateAdapter 中
        // onResume 被调用意味着当前页面确实对用户可见
        // 可以在这里开始加载数据、启动动画、上报页面曝光埋点等
        loadData()
        startAnimation()
    }
 
    override fun onPause() {
        super.onPause()
        // ✅ onPause 被调用意味着页面不再对用户可见
        // 可以在这里暂停动画、释放资源
        stopAnimation()
    }
 
    // 不再需要旧版 ViewPager 中的 setUserVisibleHint()
    // 也不需要自定义 lazyLoad 逻辑（除非有更精细的懒加载需求）
}

/**
 * 解决 ViewPager2 嵌套滑动冲突的包装布局
 * 将需要水平滑动的子 View 包裹在此布局中
 * 当子 View 可以水平滑动时，阻止外层 ViewPager2 拦截触摸事件
 */
class NestedScrollableHost @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null
) : FrameLayout(context, attrs) {
 
    // 记录触摸起始点的 X 坐标
    private var touchSlop = 0
    private var initialX = 0f
    private var initialY = 0f
 
    // 获取父级 ViewPager2 实例（向上遍历 View 树查找）
    private val parentViewPager: ViewPager2?
        get() {
            var v: View? = parent as? View
            while (v != null && v !is ViewPager2) {
                v = v.parent as? View
            }
            return v as? ViewPager2
        }
 
    init {
        // 获取系统定义的最小滑动距离阈值
        touchSlop = ViewConfiguration.get(context).scaledTouchSlop
    }
 
    override fun onInterceptTouchEvent(e: MotionEvent): Boolean {
        handleInterceptTouchEvent(e)
        return super.onInterceptTouchEvent(e)
    }
 
    private fun handleInterceptTouchEvent(e: MotionEvent) {
        val orientation = parentViewPager?.orientation ?: return
 
        // 如果子 View 在 ViewPager2 的滑动方向上不能继续滚动，则不干预
        if (!canChildScroll(orientation, -1f) && !canChildScroll(orientation, 1f)) {
            return
        }
 
        when (e.action) {
            MotionEvent.ACTION_DOWN -> {
                // 记录按下位置，并立即请求父级不要拦截
                initialX = e.x
                initialY = e.y
                parent.requestDisallowInterceptTouchEvent(true)
            }
            MotionEvent.ACTION_MOVE -> {
                // 计算水平和垂直方向的滑动距离
                val dx = e.x - initialX
                val dy = e.y - initialY
                val isVpHorizontal = orientation == ViewPager2.ORIENTATION_HORIZONTAL
 
                // 判断主要滑动方向
                val scaledDx = dx.absoluteValue * if (isVpHorizontal) 0.5f else 1f
                val scaledDy = dy.absoluteValue * if (isVpHorizontal) 1f else 0.5f
 
                if (scaledDx > touchSlop || scaledDy > touchSlop) {
                    if (isVpHorizontal == (scaledDy > scaledDx)) {
                        // 滑动方向与 ViewPager2 方向垂直，允许父级拦截
                        parent.requestDisallowInterceptTouchEvent(false)
                    } else {
                        // 滑动方向与 ViewPager2 方向一致
                        // 检查子 View 是否还能在该方向上滚动
                        if (canChildScroll(orientation, if (isVpHorizontal) -dx else -dy)) {
                            // 子 View 还能滚动，阻止父级拦截
                            parent.requestDisallowInterceptTouchEvent(true)
                        } else {
                            // 子 View 已到边界，允许父级 ViewPager2 接管滑动
                            parent.requestDisallowInterceptTouchEvent(false)
                        }
                    }
                }
            }
        }
    }
 
    // 检查子 View 是否可以在指定方向上滚动
    private fun canChildScroll(orientation: Int, delta: Float): Boolean {
        val direction = -delta.toInt()
        return when (orientation) {
            0 -> children.any { it.canScrollHorizontally(direction) }
            1 -> children.any { it.canScrollVertically(direction) }
            else -> false
        }
    }
}

class ParentFragment : Fragment(R.layout.fragment_parent) {
 
    // 在父 Fragment 作用域创建 ViewModel
    // 所有子页面 Fragment 都可以通过 parentFragment 获取同一个实例
    private val sharedViewModel: SharedViewModel by viewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        val viewPager = view.findViewById<ViewPager2>(R.id.view_pager)
        viewPager.adapter = MyPagerAdapter(this)
    }
}
 
class FirstPageFragment : Fragment(R.layout.fragment_first_page) {
 
    // 通过 requireParentFragment() 获取父 Fragment 作用域的 ViewModel
    // 这样所有页面 Fragment 拿到的是同一个 ViewModel 实例
    private val sharedViewModel: SharedViewModel by viewModels(
        ownerProducer = { requireParentFragment() }
    )
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 向共享 ViewModel 写入数据
        view.findViewById<Button>(R.id.btn_send).setOnClickListener {
            sharedViewModel.updateMessage("来自第一个页面的消息")
        }
    }
}
 
class SecondPageFragment : Fragment(R.layout.fragment_second_page) {
 
    // 同样通过 requireParentFragment() 获取同一个 ViewModel 实例
    private val sharedViewModel: SharedViewModel by viewModels(
        ownerProducer = { requireParentFragment() }
    )
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 观察共享数据的变化
        // 使用 viewLifecycleOwner 确保在 View 销毁时自动取消观察
        viewLifecycleOwner.lifecycleScope.launch {
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                sharedViewModel.message.collect { msg ->
                    // 当 FirstPageFragment 更新数据时，这里会收到通知
                    view.findViewById<TextView>(R.id.tv_message).text = msg
                }
            }
        }
    }
}
 
// 共享 ViewModel，作用域绑定在父 Fragment 上
class SharedViewModel : ViewModel() {
    // 使用 StateFlow 作为数据源
    private val _message = MutableStateFlow("")
    val message: StateFlow<String> = _message.asStateFlow()
 
    // 更新消息的方法，任何持有此 ViewModel 的页面都可以调用
    fun updateMessage(msg: String) {
        _message.value = msg
    }
}

class FirstPageFragment : Fragment(R.layout.fragment_first_page) {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 在父 Fragment 的 childFragmentManager 上注册结果监听
        // 这样同一个 childFragmentManager 下的兄弟 Fragment 发送的结果都能收到
        parentFragmentManager.setFragmentResultListener(
            "page_result_key",           // 结果的唯一标识 key
            viewLifecycleOwner           // 生命周期 owner，View 销毁时自动取消监听
        ) { _, bundle ->
            // 收到兄弟 Fragment 发送的结果
            val data = bundle.getString("data", "")
            view.findViewById<TextView>(R.id.tv_result).text = data
        }
    }
}
 
class SecondPageFragment : Fragment(R.layout.fragment_second_page) {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        view.findViewById<Button>(R.id.btn_send_result).setOnClickListener {
            // 通过 parentFragmentManager 发送结果
            // 同一个 FragmentManager 下注册了 "page_result_key" 的 Fragment 会收到
            parentFragmentManager.setFragmentResult(
                "page_result_key",       // 与监听方使用相同的 key
                bundleOf("data" to "来自第二个页面的结果")
            )
        }
    }
}

// ✅ 推荐：工厂方法模式，参数通过 arguments Bundle 传递
class UserProfileFragment : Fragment(R.layout.fragment_user_profile) {
 
    companion object {
        // 定义 Bundle 中的 key 常量，避免硬编码字符串
        private const val ARG_USER_ID = "arg_user_id"
        private const val ARG_DISPLAY_NAME = "arg_display_name"
        private const val ARG_IS_EDITABLE = "arg_is_editable"
 
        // 工厂方法：外部通过此方法创建 Fragment 实例
        // 所有初始化参数都被打包进 arguments Bundle
        fun newInstance(
            userId: Long,
            displayName: String,
            isEditable: Boolean = false
        ): UserProfileFragment {
            // 创建 Fragment 实例（调用无参构造函数）
            return UserProfileFragment().apply {
                // 将参数打包到 arguments 中
                arguments = bundleOf(
                    ARG_USER_ID to userId,           // Long 类型参数
                    ARG_DISPLAY_NAME to displayName, // String 类型参数
                    ARG_IS_EDITABLE to isEditable    // Boolean 类型参数
                )
            }
        }
    }
 
    // 在 Fragment 内部通过 arguments 取出参数
    // requireArguments() 会在 arguments 为 null 时抛出异常，比 arguments!! 更安全
    private val userId: Long by lazy {
        requireArguments().getLong(ARG_USER_ID)
    }
 
    private val displayName: String by lazy {
        requireArguments().getString(ARG_DISPLAY_NAME, "")
    }
 
    private val isEditable: Boolean by lazy {
        requireArguments().getBoolean(ARG_IS_EDITABLE, false)
    }
}

// ❌ 反模式：通过构造函数传参
// 系统重建时只调用无参构造函数，这些参数会全部丢失
class UserProfileFragment(
    private val userId: Long,        // 重建后变为默认值 0
    private val displayName: String  // 重建后变为默认值 ""
) : Fragment(R.layout.fragment_user_profile)

// ❌ 不推荐：运行时修改 arguments
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    // 这种做法虽然技术上可行（直接操作已有 Bundle），但违反设计意图
    arguments?.putString("runtime_data", "some_value")
}
 
// ✅ 推荐：运行时变化的数据使用 ViewModel 或 onSaveInstanceState
class UserProfileViewModel : ViewModel() {
    // 运行时动态数据放在 ViewModel 中管理
    private val _editedName = MutableLiveData<String>()
    val editedName: LiveData<String> = _editedName
 
    fun updateName(name: String) {
        _editedName.value = name
    }
}