企业官网建设流程全解析

如果你用AlertDialog直接弹一个删除确认框，用户手指刚碰到“删除”按钮的同时屏幕旋转了，你的App大概率会在那一刻直接闪退。这个场景我在真实项目里见过不下十次。后来把项目里所有弹窗统一改成DialogFragment，这类崩溃基本绝迹。DialogFragment从Android 3.0就有了，但它绝对不是一个该被遗忘的“老古董”，直到今天，它依然是承载Dialog最可靠、最值得按规范使用的容器。

这篇文章适合两类人：一是刚入门Android、准备把自定义弹窗写到生产环境的同学；二是已经用DialogFragment写了不少页面，但偶尔还是会被“旋转后闪退”“重复点击弹两个框”“深色模式主题错乱”折磨的开发。我会从为什么非它不可讲起，把生命周期、状态恢复、常见业务场景和真实踩过的坑一次说透。

1. 为什么DialogFragment至今仍是弹窗的最佳载体

1.1 裸写Dialog的隐藏风险：从一次线上闪退说起

先看一段在很多老项目里还能见到的写法：

val dialog = AlertDialog.Builder(this) .setMessage("确定删除这条记录吗？") .setPositiveButton("删除") { _, _ -> delete() } .show()

这段代码在Activity正常展示时没有任何问题，问题全藏在边界情况里：

• Activity被旋转销毁重建，旧的Dialog还会挂在WindowManager上，新的Activity却没有对应处理，于是出现“has leaked window”警告，严重时会直接抛异常。
• 异步接口回来后show()一个Dialog，如果赶上Activity正在执行onSaveInstanceState，就抛Can not perform this action after onSaveInstanceState。
• 用户在页面A弹了一个Dialog，然后快速返回，Dialog却还停在屏幕上，因为它根本不知道页面已经不可见了。

裸Dialog的本质问题是：它只是WindowManager里的一个窗口，和生命周期没有任何绑定关系。你必须在每个合适的时机手动去dismiss()，而“合适的时机”往往不是我们以为的那个时机。

1.2 DialogFragment对Dialog的三层改造

DialogFragment做的事情简单说就是：把Dialog塞进Fragment的生命周期里，让FragmentManager统一管理它的创建、展示、销毁、状态保存和恢复。

这里最值钱的其实是最后一点：复用性。当你把“弹窗”当成一个独立组件而不是页面里的临时代码块，它能被测试、被复用、被统一维护，这是代码质量的分水岭。DialogFragment提供了这个基础容器，剩下的就是你往里填东西的水平。

1.3 静态工厂方法：从构造传参开始就规避风险

早年间很多人写DialogFragment，是直接MyDialogFragment()然后给成员变量赋值：

class MyDialogFragment : DialogFragment() { var title: String? = null // 千万别这么干 }

这样写的问题在于：Fragment被系统重建时走的是无参构造函数，成员变量在旋转、进程恢复后会全部丢失。你需要手动在onSaveInstanceState里存一遍然后再取出来，麻烦且容易漏。

正确姿势是把参数放进arguments，并且用静态工厂方法创建实例：

class ConfirmDialogFragment : DialogFragment() { companion object { private const val ARG_MESSAGE = "arg_message" fun newInstance(message: String): ConfirmDialogFragment = ConfirmDialogFragment().apply { arguments = Bundle().apply { putString(ARG_MESSAGE, message) } } } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val message = requireArguments().getString(ARG_MESSAGE) } }

arguments是FragmentManager持久化保存的Bundle，在进程被系统回收后也能恢复。所以从创建实例这一步开始，就把它当成系统接管状态的一部分，而不是普通的Java对象。这个习惯不仅适用于DialogFragment，所有自定义Fragment都应该遵守。

2. 从零写一个DialogFragment：两条路线与窗口参数细节

2.1 先想清楚走哪条路线：onCreateDialog还是onCreateView

DialogFragment创建内容有两条路，很多人一开始没想明白就乱混着用，后面出问题都不知道去哪查：

• onCreateDialog：适合复用系统的AlertDialog、BottomSheetDialog等现成容器，用AlertDialog.Builder去拼按钮和消息。你的控制权在Dialog内部，但拿不到完整的视图生命周期。
• onCreateView：适合完全自定义布局。XML布局由Fragment生命周期管理，视图创建、销毁都走标准流程，你还能在onViewCreated里做绑定和事件监听。

我的建议是：只要业务界面稍微复杂一点，比如带输入框、带列表、带自定义样式，就走onCreateView。理由很实际：onCreateDialog模式下，Dialog的窗口管理有一些历史包袱，比如你在onCreateDialog里inflate的视图，其实没走Fragment的onCreateView流程，部分生命周期回调的顺序和预期不一样。自定义布局用onCreateView是标准路径，文档多、坑少。

2.2 完整示例：一个带输入框的反馈对话框

假设要做一个反馈弹窗，包含一个多行输入框和“取消/提交”两个按钮：

<!-- layout_dialog_feedback.xml --> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content" android:orientation="vertical" android:background="@drawable/bg_dialog_feedback"> <TextView android:layout_width="match_parent" android:layout_height="wrap_content" android:padding="20dp" android:text="反馈内容" android:textSize="18sp" android:textStyle="bold" /> <EditText android:id="@+id/etFeedback" android:layout_width="match_parent" android:layout_height="120dp" android:gravity="top|start" android:hint="请输入你的意见或建议" android:padding="12dp" android:background="@drawable/bg_edit_feedback" /> <LinearLayout android:layout_width="match_parent" android:layout_height="wrap_content" android:orientation="horizontal" android:gravity="end" android:padding="12dp"> <Button android:id="@+id/btnCancel" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="取消" /> <Button android:id="@+id/btnSubmit" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="提交" /> </LinearLayout> </LinearLayout>

对应的Fragment代码：

class FeedbackDialogFragment : DialogFragment() { companion object { private const val ARG_EDIT_HINT = "arg_edit_hint" fun newInstance(hint: String): FeedbackDialogFragment = FeedbackDialogFragment().apply { arguments = Bundle().apply { putString(ARG_EDIT_HINT, hint) } } } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setStyle(STYLE_NO_TITLE, R.style.Theme_App_Dialog_Feedback) } override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? ): View? { return inflater.inflate(R.layout.layout_dialog_feedback, container, false) } override fun onViewCreated(view: View, savedInstanceState: Bundle?) { super.onViewCreated(view, savedInstanceState) val etFeedback: EditText = view.findViewById(R.id.etFeedback) etFeedback.hint = requireArguments().getString(ARG_EDIT_HINT) view.findViewById<Button>(R.id.btnCancel).setOnClickListener { dismiss() } view.findViewById<Button>(R.id.btnSubmit).setOnClickListener { val content = etFeedback.text.toString() // 把结果回传给页面 parentFragmentManager.setFragmentResult(KEY_FEEDBACK, bundleOf(KEY_CONTENT to content)) dismiss() } } }

注意我在onCreate里调用了setStyle(STYLE_NO_TITLE, R.style.Theme_App_Dialog_Feedback)。STYLE_NO_TITLE会去掉默认标题栏，自定义style用来统一圆角、背景、动画等窗口属性。很多人漏了这一步，结果自定义布局外面套了一层默认白色背景加标题栏，怎么调都不对。

2.3 窗口装饰参数：圆角、宽度、透明背景的设置顺序

自定义DialogFragment最常见的三个问题：背景不是圆角、宽度不是预期、背景框是灰白色而不是透明。

圆角要在Drawable上做，而不是直接在代码里给Window设置圆角：

<!-- res/drawable/bg_dialog_feedback.xml --> <shape xmlns:android="http://schemas.android.com/apk/res/android"> <solid android:color="?attr/colorSurface" /> <corners android:radius="16dp" /> </shape>

背景透明必须设置给Window，否则布局外面的默认背景会兜底：

override fun onStart() { super.onStart() dialog?.window?.setBackgroundDrawable(ColorDrawable(Color.TRANSPARENT)) }

这里有一个细节：setBackgroundDrawable(ColorDrawable(Color.TRANSPARENT))必须在onStart之后设置才稳定。因为在onCreateView阶段，Window可能还没有真正挂载到WindowManager上，部分属性设置会被忽略。onStart是DialogFragment的窗口准备好显示的时机，大部分Window级配置都放这里。

宽度控制同理：

override fun onStart() { super.onStart() dialog?.window?.apply { setBackgroundDrawable(ColorDrawable(Color.TRANSPARENT)) setLayout( (resources.displayMetrics.widthPixels * 0.9f).toInt(), ViewGroup.LayoutParams.WRAP_CONTENT ) } }

宽度取屏幕宽度的90%，这几乎是自定义对话框最常用的配件参数。如果你的需求是左右留边距、底部弹层、或者全屏，改后面的数字就行。

3. 生命周期与跨配置变更：旋转屏幕时DialogFragment到底做了什么

3.1 show()和dismiss()背后的事务调度

show()的完整逻辑可以拆成两层：

第一层，调用fragmentManager.show(dialogFragment, tag)，本质是提交一个Fragment事务，把DialogFragmentadd到FragmentManager，然后安排它走完整的Fragment生命周期。

第二层，当Fragment进入onStart时，DialogFragment内部拿到之前创建的Dialog，调用dialog.show()真正把窗口挂到WindowManager上。当Fragment进入onStop时，自动调用dialog.hide()。

dismiss()则是反向操作：先把Dialog关闭，再提交一个移除事务，把这个Fragment从FragmentManager里移除，随后走onDestroyView、onDestroy。

这里有个隐藏的坑：Fragment事务默认是异步的。如果你在同一个方法里先show()后立即dismiss()，事务还没执行完，FragmentManager的状态还不够稳定，可能出现界面闪烁甚至崩溃。遇到这种场景，要么用showNow()强制同步执行，要么把dismiss()放到下一次消息循环里，比如view.post { dismiss() }。

3.2 setRetainInstance被废弃之后，跨配置变更该靠谁

老Android开发者都有印象，以前处理Fragment跨旋转保留，用的是一只setRetainInstance(true)。这个方法从API 28开始被标记废弃，目前官方态度很明确：不要再用，请用ViewModel。

废弃的直接原因是：被保留的Fragment实例会持有旧Binding、旧View状态，而且它的生命周期行为在非配置变更场景下很难预测，测试也不好写。ViewModel能表达同样的诉求，并且职责更单一。

拿上面的反馈对话框举例，如果用户在里面输了很长一段文字，然后旋转了屏幕，你肯定不希望输入内容丢光。在DialogFragment里，页面级的ViewModel可以这样获取：

class FeedbackViewModel : ViewModel() { val feedbackContent = MutableLiveData("") } class FeedbackDialogFragment : DialogFragment() { private val viewModel: FeedbackViewModel by activityViewModels() override fun onViewCreated(view: View, savedInstanceState: Bundle?) { super.onViewCreated(view, savedInstanceState) viewModel.feedbackContent.observe(viewLifecycleOwner) { content -> // 恢复输入框内容 if (::etFeedback.isInitialized) { etFeedback.setText(content) } } } }

注意观察用的是viewLifecycleOwner，而不是this。DialogFragment的onViewCreated和onDestroyView和普通Fragment一样会发生在旋转过程中，如果不绑定viewLifecycleOwner，会产生观察者泄漏或者回调时操作已销毁视图的问题。

如果数据不需要在“页面A”和“页面B”之间共享，只希望Dialog自己扛住旋转，也可以把ViewModel作用域挂在Activity上，用activityViewModels()；无论如何，别再碰setRetainInstance了。

3.3 进程被系统回收后，对话框能自动复活吗

能，前提是你按规范来。系统在onSaveInstanceState阶段会把DialogFragment的实例状态、arguments、FragmentManager中的任务栈一并写进Bundle。当用户从后台切回来、Activity被重建时，FragmentManager会根据保存的状态重新创建DialogFragment实例，走一遍完整生命周期，并且自动重新弹出原来的Dialog。

这看起来像魔法，其实是“无参构造 + arguments恢复 + FragmentManager管理”三者配合的结果。正因为如此，前面强调的“所有传参都走arguments”才会如此重要——这是进程复活时唯一可靠的数据来源。

如果你的Dialog里还有网络请求、大列表等重度依赖，请把数据放ViewModel，让它和进程的生命周期解耦。DialogFragment负责界面，ViewModel负责数据，这是最省心的分工。

4. 高频业务场景的完整解法：确认框、底部弹窗与全屏弹层

4.1 回调型确认框：结果怎么安全地回传给页面

经典做法是定义接口回调：

class ConfirmDialogFragment : DialogFragment() { var onConfirm: (() -> Unit)? = null override fun onDetach() { onConfirm = null super.onDetach() } }

简单场景够用，但如果页面在对话框显示的过程中被系统回收，lambda会丢失，恢复后点击确认没有任何反应。更安全的方式是用官方推荐的FragmentManager.setFragmentResult返回结果，系统会帮你保证目标Fragment存活时才能收到回调：

// DialogFragment 中点击确定： parentFragmentManager.setFragmentResult("request_delete", bundleOf("confirmed" to true)) dismiss() // 页面Fragment 中，onCreate时注册监听： parentFragmentManager.setFragmentResultListener("request_delete", this) { _, bundle -> if (bundle.getBoolean("confirmed")) { delete() } }

setFragmentResult这套API的本质是一个轻量级的结果总线，不持有彼此的强引用，不依赖View存活状态，非常适合“弹窗→页面”的单次回传。比我过去用接口回调的老办法，少了一大半状态恢复的心智负担。

4.2 BottomSheetDialogFragment：底部弹出列表的现代做法

底部弹窗在产品里出现的频率很高：分享菜单、筛选条件、更多操作。官方推荐直接继承BottomSheetDialogFragment，它内部已经封装好了BottomSheetBehavior，默认滑动手势和遮罩都有：

class ShareSheetFragment : BottomSheetDialogFragment() { override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? ): View? { return inflater.inflate(R.layout.layout_share_sheet, container, false) } override fun onStart() { super.onStart() (requireDialog() as BottomSheetDialog).behavior.apply { state = BottomSheetBehavior.STATE_EXPANDED skipCollapsed = true // 禁止收起为“半个高度”的状态 } } }

skipCollapsed = true是产品经理们最常提的“要么完全展开，要么缩回消失”的需求。如果你不做这一步，默认行为是往下拖到一半会停在中间高度，视觉上很突兀。

另外一个常见需求：禁止用户下滑关闭。在普通Dialog里是setCancelable(false)，在BottomSheet里除了这个，还要禁用拖拽：

val behavior = (requireDialog() as BottomSheetDialog).behavior behavior.isDraggable = false behavior.state = BottomSheetBehavior.STATE_EXPANDED

否则用户直接下拉还是能关掉，setCancelable(false)管不住拖拽关。

4.3 三个高频控件细节：点击外部不消失、全屏宽度、软键盘避让

我在项目里总结出一套高频配置，基本所有Dialog都会用到：

点击外部不消失：

dialog?.setCancelable(false) dialog?.setCanceledOnTouchOutside(false)

注意setCancelable(false)要放在onCreate阶段，因为它在Dialog创建时决定了返回键响应逻辑；setCanceledOnTouchOutside放在onStart之前设置即可。

全屏宽度（常见于筛选、编辑弹层）：

override fun onStart() { super.onStart() dialog?.window?.apply { setLayout( ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT ) setGravity(Gravity.BOTTOM or Gravity.CENTER_HORIZONTAL) } }

配setGravity(Gravity.BOTTOM)的效果是底部全宽弹层，很多“从底部滑出的编辑面板”就是这么做的。

软键盘避让：

当Dialog里带了输入框，键盘弹出来会压住输入区域。需要给Window设置自适应：

dialog?.window?.setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE)

写完之后记得测试重点不是键盘出来后能不能输入，而是键盘收起后布局是否弹回原样。如果还不行，检查布局根节点是否设置了android:windowSoftInputMode="adjustResize"，以及Dialog布局最外层是否给了足够的可压缩空间。

5. 项目中真正会踩的坑：三个崩溃案例的完整排查链路

5.1 Fragment already added：重复show的隐蔽来源

现象：用户快速点击某个按钮两次，或者异步回调返回后页面又执行了一次show，控制台报IllegalStateException: Fragment already added: ConfirmDialogFragment{...}。

排查链路：

第一步，复现时用adb shell dumpsys activity top或者日志确认FragmentManager里确实已经存在同tag的实例。

第二步，检查show入口是否做了防抖。最常用的防御式写法是：

private fun showConfirm(message: String) { val tag = "confirm_dialog" if (parentFragmentManager.findFragmentByTag(tag) != null) { // 已经存在，避免重复添加 return } ConfirmDialogFragment.newInstance(message) .show(parentFragmentManager, tag) }

第三步，逐个排查异步回调。比如网络请求成功后才show，如果请求被触发了两次，回调也会来两次。这里要查的是请求层的防重，而不是只在show这里堵。

经验教训：永远给Dialog一个固定tag，并且在show之前用findFragmentByTag判断一次。这招在绝大多数场景下能直接消灭“add twice”崩溃。

5.2 Can not perform this action after onSaveInstanceState

现象：Activity切到后台，系统准备保存状态，此时一个异步回调触发show()，App直接闪退，异常信息是Can not perform this action after onSaveInstanceState。

这个问题的本质是：show()内部会执行FragmentTransaction.commit()，而系统规定onSaveInstanceState之后不能再commit事务，否则Activity恢复时的状态会乱套。

排查链路：

第一步，定位到show的调用时机。常见来源是：网络回调、Handler延时、广播回调。

第二步，对这些异步来源加状态判断。我建议在show前做两个检查：

if (parentFragmentManager.isStateSaved) { // 状态正在保存，等下一个适合的时机再弹 return }

第三步，如果你确定这个Dialog即使丢了也没关系，比如“刷新成功”的提示，可以用showAllowingStateLoss()。但我要说句实话：showAllowingStateLoss()不是银弹，它允许的是“丢失本次状态变更”，如果用户正在等待这个Dialog的确认结果，状态丢了会引发更隐蔽的业务问题。所以业务上重要的Dialog宁可延迟到onResume再弹，也不要图省事。

5.3 深浅色切换后Dialog主题没跟上

现象：App已经适配了深色模式，普通的页面都正常，但DialogFragment背景还是白色的，或者按钮文字变成白底白字看不见。

排查链路：

第一步，检查项目主题里是否设置了dialogTheme或alertDialogTheme。如果设了一个固定浅色Theme，深色模式自然失效。

第二步，确认自定义style是否正确继承了DayNight系列：

<!-- values/themes.xml --> <style name="Theme.App" parent="Theme.MaterialComponents.DayNight.NoActionBar"> <item name="android:dialogTheme">@style/Theme.App.Dialog</item> <item name="alertDialogTheme">@style/Theme.App.Dialog</item> </style> <style name="Theme.App.Dialog" parent="Theme.MaterialComponents.DayNight.Dialog.Alert"> <item name="android:windowBackground">@drawable/bg_dialog</item> <item name="colorSurface">?attr/colorSurface</item> </style>

在这里，bg_dialog这个drawable里的颜色也要用?attr/colorSurface这类主题属性，而不是写死#FFFFFF：

<shape xmlns:android="http://schemas.android.com/apk/res/android"> <solid android:color="?attr/colorSurface" /> <corners android:radius="16dp" /> </shape>

第三步，如果项目走的是自定义样式、没有用Material主题属性，那就在Fragment里根据当前模式手动切换：

val isDark = resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK == Configuration.UI_MODE_NIGHT_YES

不过这种硬编码方式只适合临时救急，长期维护还是建议把颜色收敛到主题属性里。

根据我自己的经验，Dialog阴影和背景最容易在深浅色切换时翻车。配置好后记得把系统切到深色模式，用Dialog手动旋转一次、再杀进程恢复一次，三个维度测完再合代码。

我现在的习惯是把所有Dialog的主题配置独立成一个style，和页面主题分开维护。这样做的好处是页面主题无论怎么演进，弹窗样式都能稳定不炸。配合着DialogFragment的生命周期托管、arguments传参、ViewModel数据兜底，一套弹窗代码面对旋转、杀进程、深浅色切换，都能保持行为一致。写DialogFragment与其说是学一个组件，不如说是把Android的状态管理思路在“弹窗”这个场景里彻底想明白了。